Class: Results

Source Location: /blogs/inc/_core/ui/results/_results.class.php

Class Results

Class Overview

Results class

Located in /blogs/inc/_core/ui/results/_results.class.php [line 50]

Widget
   |
   --Table
      |
      --Results

Author(s):

Information Tags:

Todo:

Support $cols[]['order_rows_callback'] / order_objects_callback also if there's a LIMIT?

Properties

Methods

[ Top ]

Direct descendents

Child Class	Description
ArchiveList	Archive List Class
ResultSel	ResultSel class: displays Results and provides Selection capabilities
DataObjectList	Data Object List Base Class
FilteredResults

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties	Inherited Methods	Inherited Constants
Inherited From Table Table::$displayed_cols_count Table::$displayed_lines_count Table::$fadeout_array Table::$fadeout_count Table::$filter_area Table::$is_fadeout_line Table::$nb_cols Table::$no_results_text Table::$param_prefix Table::$total_pages Inherited From Widget Widget::$global_icons Widget::$params Widget::$title	Inherited From Table Table::Table() Constructor Table::display_body_end() Table::display_body_start() Table::display_colselect() Display the column selection Table::display_col_end() Table::display_col_headers() Display column headers Table::display_col_start() Start a column (data). Table::display_filters() Display the filtering form Table::display_head() Display list/table head. Table::display_init() Initialize things in order to be ready for displaying. Table::display_line_end() Table::display_line_start() Table::display_list_end() Display list/table end. Table::display_list_start() Display list/table start. Table::display_option_area() Display options area Table::replace_callback() Widget callback for template vars. Inherited From Widget Widget::Widget() Constructor Widget::disp_template_raw() Display a template param without replacing variables Widget::disp_template_replaced() Display a template param with its variables replaced Widget::gen_global_icons() Generate img tags for registered icons, through global_icon(). Widget::global_icon() Registers a global action icon Widget::replace_callback() Callback function used to replace only necessary values in template. Widget::replace_callback_wrapper() This is an additional wrapper to replace_vars() that allows to react on the return value of it. Widget::replace_vars() Replaces $vars$ with appropriate values.

Inherited Properties

Inherited Methods

Inherited Constants

Inherited From Table

Table::$displayed_cols_count

Table::$displayed_lines_count

Table::$fadeout_array

Table::$fadeout_count

Table::$filter_area

Table::$is_fadeout_line

Table::$nb_cols

Table::$no_results_text

Table::$param_prefix

Table::$total_pages

Inherited From Widget

Widget::$global_icons

Widget::$params

Widget::$title

Inherited From Table

Table::Table()

Constructor

Table::display_body_end()

Table::display_body_start()

Table::display_colselect()

Display the column selection

Table::display_col_end()

Table::display_col_headers()

Display column headers

Table::display_col_start()

Start a column (data).

Table::display_filters()

Display the filtering form

Table::display_head()

Display list/table head.

Table::display_init()

Initialize things in order to be ready for displaying.

Table::display_line_end()

Table::display_line_start()

Table::display_list_end()

Display list/table end.

Table::display_list_start()

Display list/table start.

Table::display_option_area()

Display options area

Table::replace_callback()

Widget callback for template vars.

Inherited From Widget

Widget::Widget()

Constructor

Widget::disp_template_raw()

Display a template param without replacing variables

Widget::disp_template_replaced()

Display a template param with its variables replaced

Widget::gen_global_icons()

Generate img tags for registered icons, through global_icon().

Widget::global_icon()

Registers a global action icon

Widget::replace_callback()

Callback function used to replace only necessary values in template.

Widget::replace_callback_wrapper()

This is an additional wrapper to replace_vars() that allows to react on the return value of it.

Widget::replace_vars()

Replaces $vars$ with appropriate values.

[ Top ]

Property Summary

DataObjectCache	$Cache	Cache to use to instantiate an object and cache it for each line of results.
mixed	$cols	Definitions for each column:
boolean	$col_headers	Do we want to display column headers?
array	$current_group_ID	Current group identifier (by level/depth)
integer	$current_idx	Current object idx in $rows array
mixed	$current_Obj	This will hold the object instantiated by the Cache for the current line.
mixed	$functions_area	Parameters for the functions area (to display functions at the end of results array):
integer	$global_idx	idx relative to whole list (range: 0 to total_rows-1)
mixed	$global_is_first	Is this gobally the 1st item in the list? (NOT just the 1st in current page)
mixed	$global_is_last	Is this gobally the last item in the list? (NOT just the last in current page)
mixed	$group_by	DB fieldname to group on.
mixed	$group_by_obj_prop	Object property/properties to group on.
mixed	$grp_cols	Definitions for each GROUP column:
string	$ID_col	Fieldname to detect empty data rows.
mixed	$limit	Number of lines per page
mixed	$nofollow_pagenav	Should there be nofollows on page navigation
array	$order_callbacks	List of sortable columns by callback ("order_objects_callback" and "order_rows_callback")
mixed	$order_field_list	List of sortable fields
mixed	$order_param
mixed	$page	Current page
mixed	$page_ID_array	Array of IDs for current page.
mixed	$page_ID_list	List of IDs for current page.
mixed	$page_param	URL param names
mixed	$result_num_rows	Number of rows in result set for current page.
mixed	$rows	Array of DB rows for current page.
mixed	$sql	SQL query
mixed	$total_rows	Total number of rows (if > $limit, it will result in multiple pages)

[ Top ]

Method Summary

Results	Results()	Constructor
integer	callback_group_by_obj_prop()	Callback, to sort Result::$rows according to Result::$group_by_obj_prop.
void	count_total_rows()	Count the total number of rows of the SQL result (all pages)
int	display()	Display paged list/table based on object parameters
void	display_body()	Display list/table body.
void	display_first()	returns the link to the first page, if necessary
void	display_functions()	Display the functions
boolean	display_if_empty()	Template function: display message if list is empty
void	display_init()	Initialize things in order to be ready for displaying.
void	display_last()	returns the link to the last page, if necessary
void	display_nav()	Display navigation text, based on template.
void	display_next()	returns a link to next pages, if necessary
void	display_prev()	returns a link to previous pages, if necessary
void	display_totals()	Display totals line if set.
void	first()	Returns the first page number to be displayed in the list
array	get_col_sort_values()	Returns values needed to make sort links for a given column
integer	get_num_rows()	Get number of rows available for display
string	get_order_field_list()	Returns order field list add to SQL query:
void	get_page_ID_array()	Get an array of IDs for current page
void	get_page_ID_list()	Get a list of IDs for current page
void	instantiate_page_to_Cache()	Note: this function might actually not be very useful.
void	last()	returns the last page number to be displayed in the list
void	mergesort()	Merge sort. This is required to not re-order items when sorting for e.g. grouping at the end.
void	move_icons()
void	next_idx()	Increment and update all necessary counters before processing a new line in result set
integer	order_callback_wrapper_objects()	Wrapper method to http://www.php.net/usort, which instantiates objects and passed them on to the order callback.
integer	order_callback_wrapper_rows()	Wrapper method to http://www.php.net/usort, which passes the rows to the order callback.
void	page_list()	Returns the page link list under the table
void	page_scroll_list()
void	parse_col_content()	Handle variable subtitutions for column contents.
void	query()	Run the query now!
string	replace_callback()	Widget callback for template vars.
void	reset()	Reset the query -- EXPERIMENTAL
void	restart()	Rewind resultset

[ Top ]

Properties

DataObjectCache $Cache [line 124]

Cache to use to instantiate an object and cache it for each line of results.

For this to work, all columns of the related table must be selected in the query

[ Top ]

mixed $cols [line 150]

Definitions for each column:

th
td
order: SQL column name(s) to sort by (delimited by comma)
order_objects_callback: a PHP callback function (can be array($Object, $method)). This gets three params: $a, $b, $desc. $a and $b are instantiated objects from Results::$Cache $desc is either 'ASC' or 'DESC'. The function has to return -1, 0 or 1, according to if the $a < $b, $a == $b or $a > $b.
order_rows_callback: a PHP callback function (can be array($Object, $method)). This gets three params: $a, $b, $desc. $a and $b are DB row objects $desc is either 'ASC' or 'DESC'. The function has to return -1, 0 or 1, according to if the $a < $b, $a == $b or $a > $b.
td_class

[ Top ]

boolean $col_headers = true [line 156]

Do we want to display column headers?

[ Top ]

array $current_group_ID [line 187]

Current group identifier (by level/depth)

[ Top ]

integer $current_idx = 0 [line 98]

Current object idx in $rows array

[ Top ]

mixed $current_Obj [line 129]

This will hold the object instantiated by the Cache for the current line.

[ Top ]

mixed $functions_area [line 231]

Parameters for the functions area (to display functions at the end of results array):

[ Top ]

integer $global_idx [line 104]

idx relative to whole list (range: 0 to total_rows-1)

[ Top ]

mixed $global_is_first [line 109]

Is this gobally the 1st item in the list? (NOT just the 1st in current page)

[ Top ]

mixed $global_is_last [line 114]

Is this gobally the last item in the list? (NOT just the last in current page)

[ Top ]

mixed $group_by = '' [line 168]

DB fieldname to group on.

Leave empty if you don't want to group.

NOTE: you have to use ORDER BY goup_column in your query for this to work correctly.

[ Top ]

mixed $group_by_obj_prop [line 181]

Object property/properties to group on.

Objects get instantiated and grouped by the given property/member value.

NOTE: this requires Result::$Cache to be set and is probably only useful, if you do not use Result::$limit, because grouping appears after the relevant data has been pulled from DB.

[ Top ]

mixed $grp_cols = NULL [line 198]

Definitions for each GROUP column:

-td -td_start. A column with no def will de displayed using the default defs from Results::$params, that is to say, one of these:

$this->params['grp_col_start_first'];
$this->params['grp_col_start_last'];
$this->params['grp_col_start'];

[ Top ]

string $ID_col = '' [line 208]

Fieldname to detect empty data rows.

Empty data rows can happen when left joining on groups. Leave empty if you don't want to detect empty datarows.

API Tags:

Usedby:	Results::get_page_ID_array()
Usedby:	Results::get_page_ID_list()
Usedby:	Results::$page_ID_array
Usedby:	Results::$page_ID_list

[ Top ]

mixed $limit [line 65]

Number of lines per page

[ Top ]

mixed $nofollow_pagenav = false [line 237]

Should there be nofollows on page navigation

[ Top ]

array $order_callbacks [line 225]

List of sortable columns by callback ("order_objects_callback" and "order_rows_callback")

[ Top ]

mixed $order_field_list [line 219]

List of sortable fields

[ Top ]

mixed $order_param [line 214]

[ Top ]

mixed $page [line 75]

Current page

[ Top ]

mixed $page_ID_array [line 92]

Array of IDs for current page.

API Tags:

Uses:

Results::$ID_col

[ Top ]

mixed $page_ID_list [line 86]

List of IDs for current page.

API Tags:

Uses:

Results::$ID_col

[ Top ]

mixed $page_param [line 213]

URL param names

[ Top ]

mixed $result_num_rows [line 70]

Number of rows in result set for current page.

[ Top ]

mixed $rows [line 80]

Array of DB rows for current page.

[ Top ]

mixed $sql [line 55]

SQL query

[ Top ]

mixed $total_rows [line 60]

Total number of rows (if > $limit, it will result in multiple pages)

[ Top ]

Methods

Constructor Results [line 258]

Results Results(
string
$sql, [string
$param_prefix = ''], [string
$default_order = ''], [integer
$limit = NULL], [string
$count_sql = NULL], [boolean
$init_page = true], string|integer
6 
)

Constructor

Parameters:

string\|integer	6:	SQL query used to count the total # of rows if integer, we'll use that as the count if NULL, we'll try to COUNT(*) by ourselves
string	$sql:	SQL query
string	$param_prefix:	prefix to differentiate page/order params when multiple Results appear one same page
string	$default_order:	default ordering of columns (special syntax) if not specified in the URL params example: -A-- will sort in ascending order on 2nd column example: ---D will sort in descending order on 4th column
integer	$limit:	number of lines displayed on one page (0 to disable paging; null to use $UserSettings/results_per_page)
string	$count_sql:	SQL to get the total count of results
boolean	$init_page:

Information Tags:

Todo:	we might not want to count total rows when not needed...
Todo:	fplanque: I am seriously considering putting $count_sql into 2nd or 3rd position. Any prefs?
Todo:	dh> We might just use "SELECT SQL_CALC_FOUND_ROWS ..." and "FOUND_ROWS()"..! - available since MySQL 4 - would save one query just for counting!

[ Top ]

callback_group_by_obj_prop [line 521]

integer callback_group_by_obj_prop(
array
$row_a, array
$row_b, [integer
$depth = 0] 
)

Callback, to sort Result::$rows according to Result::$group_by_obj_prop.

Parameters:

array	$row_a:	DB row for object A
array	$row_b:	DB row for object B
integer	$depth:	Depth, used internally (you can group on a list of member properties)

[ Top ]

count_total_rows [line 629]

void count_total_rows(
[
$sql_count = NULL] 
)

Count the total number of rows of the SQL result (all pages)

This is done by dynamically modifying the SQL query and forging a COUNT() into it.

Parameters:

$sql_count:

Information Tags:

Todo:	dh> This might get done using SQL_CALC_FOUND_ROWS (I noted this somewhere else already) fp> I have a vague memory about issues with SQL_CALC_FOUND_ROWS. Maybe it was not returned accurate counts. Or maybe it didn't work with GROUP BY. Sth like that.
Todo:	allow overriding?
Todo:	handle problem of empty groups!

Redefined in descendants as:

ArchiveList::count_total_rows() : Count the number of rows of the SQL result

[ Top ]

display [line 736]

int display(
[array|NULL
$display_params = NULL], [array
$fadeout = NULL] 
)

Display paged list/table based on object parameters

This is the meat of this class!

Parameters:

array\|NULL	$display_params:
array	$fadeout:	Fadeout settings array( 'key column' => array of values ) or 'session'

API Tags:

Return:

# of rows displayed

[ Top ]

display_body [line 816]

void display_body(
)

Display list/table body.

This includes groups and data rows.

[ Top ]

display_first [line 1625]

void display_first(
[
$page_url = ''] 
)

returns the link to the first page, if necessary

Parameters:

$page_url:

[ Top ]

display_functions [line 1107]

void display_functions(
)

Display the functions

Redefined in descendants as:

ResultSel::display_functions() : Display functions

[ Top ]

display_if_empty [line 1794]

boolean display_if_empty(
[
$params = array()] 
)

Template function: display message if list is empty

Parameters:

$params:

API Tags:

Return:

true if empty

Redefined in descendants as:

CommentList::display_if_empty() : Template function: display message if list is empty

[ Top ]

display_init [line 801]

void display_init(
[array
$display_params = NULL], [array
$fadeout = NULL] 
)

Initialize things in order to be ready for displaying.

This is useful when manually displaying, i-e: not by using Results::display()

Parameters:

array	$display_params:	*please document*
array	$fadeout:	Fadeout settings array( 'key column' => array of values ) or 'session'

Redefinition of:

Table::display_init(): Initialize things in order to be ready for displaying.

[ Top ]

display_last [line 1641]

void display_last(
[
$page_url = ''] 
)

returns the link to the last page, if necessary

Parameters:

$page_url:

[ Top ]

display_nav [line 1161]

void display_nav(
string
$template 
)

Display navigation text, based on template.

Parameters:

string

$template:

template: 'header' or 'footer'

[ Top ]

display_next [line 1672]

void display_next(
[
$page_url = ''] 
)

returns a link to next pages, if necessary

Parameters:

$page_url:

[ Top ]

display_prev [line 1657]

void display_prev(
[
$page_url = ''] 
)

returns a link to previous pages, if necessary

Parameters:

$page_url:

[ Top ]

display_totals [line 1028]

void display_totals(
)

Display totals line if set.

[ Top ]

first [line 1589]

void first(
)

Returns the first page number to be displayed in the list

[ Top ]

get_col_sort_values [line 1194]

array get_col_sort_values(
integer
$col_idx 
)

Returns values needed to make sort links for a given column

Returns an array containing the following values:

current_order : 'ASC', 'DESC' or ''
order_asc : url to order in ascending order
order_desc
order_toggle : url to toggle sort order

Parameters:

integer

$col_idx:

column to sort

Redefined in descendants as:

ItemList2::get_col_sort_values() : Returns values needed to make sort links for a given column

[ Top ]

get_num_rows [line 1783]

integer get_num_rows(
)

Get number of rows available for display

[ Top ]

get_order_field_list [line 1264]

string get_order_field_list(
)

Returns order field list add to SQL query:

API Tags:

Return:

May be empty

[ Top ]

get_page_ID_array [line 602]

void get_page_ID_array(
)

Get an array of IDs for current page

API Tags:

Uses:

Results::$ID_col

[ Top ]

get_page_ID_list [line 585]

void get_page_ID_list(
)

Get a list of IDs for current page

API Tags:

Uses:

Results::$ID_col

[ Top ]

instantiate_page_to_Cache [line 710]

void instantiate_page_to_Cache(
DataObjectCache
&$Cache 
)

Note: this function might actually not be very useful.

If you define ->Cache before display, all rows will be instantiated on the fly. No need to restart et go through the rows a second time here.

Parameters:

DataObjectCache

&$Cache:

[ Top ]

last [line 1609]

void last(
)

returns the last page number to be displayed in the list

[ Top ]

mergesort [line 479]

void mergesort(
array
&$array, callback
$cmp_function 
)

Merge sort. This is required to not re-order items when sorting for e.g. grouping at the end.

Parameters:

array	&$array:	List of items to sort
callback	$cmp_function:	Sort function/method

API Tags:

See:

38827

[ Top ]

move_icons [line 1412]

void move_icons(
)

Information Tags:

Todo:

Support Results::$order_callbacks

[ Top ]

next_idx [line 319]

void next_idx(
)

Increment and update all necessary counters before processing a new line in result set

[ Top ]

order_callback_wrapper_objects [line 558]

integer order_callback_wrapper_objects(

$row_a, 
$row_b 
)

Wrapper method to http://www.php.net/usort, which instantiates objects and passed them on to the order callback.

Parameters:

	$row_a:
	$row_b:

[ Top ]

order_callback_wrapper_rows [line 573]

integer order_callback_wrapper_rows(

$row_a, 
$row_b 
)

Wrapper method to http://www.php.net/usort, which passes the rows to the order callback.

Parameters:

	$row_a:
	$row_b:

[ Top ]

page_list [line 1686]

void page_list(

$min, 
$max, [
$page_url = ''] 
)

Returns the page link list under the table

Parameters:

	$min:
	$max:
	$page_url:

[ Top ]

page_scroll_list [line 1715]

void page_scroll_list(
)

[ Top ]

parse_col_content [line 1377]

void parse_col_content(

$content 
)

Handle variable subtitutions for column contents.

This is one of the key functions to look at when you want to use the Results class.

$var$
£var£
#var#
{row}
%func()%
¤func()¤

Parameters:

$content:

[ Top ]

query [line 338]

void query(
[
$create_default_cols_if_needed = true], [
$append_limit = true], [
$append_order_by = true], [
$query_title = 'Results::Query()'] 
)

Run the query now!

Will only run if it has not executed before.

Parameters:

	$create_default_cols_if_needed:
	$append_limit:
	$append_order_by:
	$query_title:

Redefined in descendants as:

ItemListLight::query() : Run Query: GET DATA ROWS *** LIGHT ***
ItemList2::query() : Run Query: GET DATA ROWS *** HEAVY ***

[ Top ]

replace_callback [line 1503]

string replace_callback(

$matches 
)

Widget callback for template vars.

This allows to replace template vars, see Widget::replace_callback().

Parameters:

$matches:

Redefinition of:

Table::replace_callback(): Widget callback for template vars.

[ Top ]

reset [line 290]

void reset(
)

Reset the query -- EXPERIMENTAL

Useful in derived classes such as ItemList to requery with a slighlty moidified filterset

Redefined in descendants as:

ItemListLight::reset() : Reset the query -- EXPERIMENTAL

[ Top ]

restart [line 299]

void restart(
)

Rewind resultset

Redefined in descendants as:

ArchiveList::restart() : Rewind resultset

[ Top ]

Multilingual multiuser multiblog engine

Class: Results

Class Results

Packages

Classes

Files