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 44]

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::$is_fadeout_line Table::$nb_cols Table::$no_results_text 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_col_end() Table::display_col_headers() Display column headers Table::display_col_start() 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::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::$is_fadeout_line

Table::$nb_cols

Table::$no_results_text

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_col_end()

Table::display_col_headers()

Display column headers

Table::display_col_start()

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::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	$filter_area	Parameters for the filter area:
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
mixed	$param_prefix	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_colselect()	Display the column selection
void	display_filters()	Display the filtering form
void	display_first()	returns the link to the first page, if necessary
void	display_functions()	Display the functions
void	display_head()	Display list/table head.
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_option_area()	Display options area
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	restart()	Rewind resultset

[ Top ]

Properties

DataObjectCache $Cache [line 118]

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 144]

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 150]

Do we want to display column headers?

[ Top ]

array $current_group_ID [line 181]

Current group identifier (by level/depth)

[ Top ]

integer $current_idx = 0 [line 92]

Current object idx in $rows array

[ Top ]

mixed $current_Obj [line 123]

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

[ Top ]

mixed $filter_area [line 226]

Parameters for the filter area:

[ Top ]

mixed $functions_area [line 232]

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

[ Top ]

integer $global_idx [line 98]

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

[ Top ]

mixed $global_is_first [line 103]

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

[ Top ]

mixed $global_is_last [line 108]

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

[ Top ]

mixed $group_by = '' [line 162]

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 175]

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 192]

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 202]

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 59]

Number of lines per page

[ Top ]

mixed $nofollow_pagenav = false [line 238]

Should there be nofollows on page navigation

[ Top ]

array $order_callbacks [line 220]

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

[ Top ]

mixed $order_field_list [line 214]

List of sortable fields

[ Top ]

mixed $order_param [line 209]

[ Top ]

mixed $page [line 69]

Current page

[ Top ]

mixed $page_ID_array [line 86]

Array of IDs for current page.

API Tags:

Uses:

Results::$ID_col

[ Top ]

mixed $page_ID_list [line 80]

List of IDs for current page.

API Tags:

Uses:

Results::$ID_col

[ Top ]

mixed $page_param [line 208]

[ Top ]

mixed $param_prefix [line 207]

URL param names

[ Top ]

mixed $result_num_rows [line 64]

Number of rows in result set for current page.

[ Top ]

mixed $rows [line 74]

Array of DB rows for current page.

[ Top ]

mixed $sql [line 49]

SQL query

[ Top ]

mixed $total_rows [line 54]

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

[ Top ]

Methods

Constructor Results [line 257]

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

Constructor

Parameters:

NULL\|string	6:	SQL query used to count the total # of rows (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 503]

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 608]

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:	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 708]

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 983]

void display_body(
)

Display list/table body.

This includes groups and data rows.

API Tags:

Access:

protected

[ Top ]

display_colselect [line 906]

void display_colselect(
)

Display the column selection

[ Top ]

display_filters [line 922]

void display_filters(
)

Display the filtering form

[ Top ]

display_first [line 1787]

void display_first(
[
$page_url = ''] 
)

returns the link to the first page, if necessary

Parameters:

$page_url:

[ Top ]

display_functions [line 1271]

void display_functions(
)

Display the functions

Redefined in descendants as:

ResultSel::display_functions() : Display functions

[ Top ]

display_head [line 943]

void display_head(
)

Display list/table head.

This includes list head/title and column headers. EXPERIMENTAL: also dispays <tfoot>

API Tags:

Access:

protected

Redefinition of:

Table::display_head(): Display list/table head.

[ Top ]

display_if_empty [line 1954]

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 773]

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 1803]

void display_last(
[
$page_url = ''] 
)

returns the link to the last page, if necessary

Parameters:

$page_url:

[ Top ]

display_nav [line 1326]

void display_nav(
string
$template 
)

Display navigation text, based on template.

Parameters:

string

$template:

template: 'header' or 'footer'

API Tags:

Access:

protected

[ Top ]

display_next [line 1833]

void display_next(
[
$page_url = ''] 
)

returns a link to next pages, if necessary

Parameters:

$page_url:

[ Top ]

display_option_area [line 793]

void display_option_area(
string
$option_name, string
$area_name, string
$option_title, string
$submit_title, [string
$default_folde_state = 'expanded'] 
)

Display options area

Parameters:

string	$option_name:	name of the option ( ma_colselect, tsk_filter....)
string	$area_name:	area name ( colselect_area, filter_area )
string	$option_title:	option title
string	$submit_title:	submit button title
string	$default_folde_state:	default folde state when is empty in the session

[ Top ]

display_prev [line 1819]

void display_prev(
[
$page_url = ''] 
)

returns a link to previous pages, if necessary

Parameters:

$page_url:

[ Top ]

display_totals [line 1192]

void display_totals(
)

Display totals line if set.

[ Top ]

first [line 1751]

void first(
)

Returns the first page number to be displayed in the list

[ Top ]

get_col_sort_values [line 1359]

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 1943]

integer get_num_rows(
)

Get number of rows available for display

[ Top ]

get_order_field_list [line 1429]

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 584]

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 567]

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 682]

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 1771]

void last(
)

returns the last page number to be displayed in the list

[ Top ]

mergesort [line 461]

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 1574]

void move_icons(
)

Information Tags:

Todo:

Support Results::$order_callbacks

[ Top ]

next_idx [line 308]

void next_idx(
)

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

[ Top ]

order_callback_wrapper_objects [line 540]

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 555]

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 1846]

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 1875]

void page_scroll_list(
)

[ Top ]

parse_col_content [line 1541]

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 327]

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 1665]

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 ]

restart [line 288]

void restart(
)

Rewind resultset

Redefined in descendants as:

ArchiveList::restart() : Rewind resultset

[ Top ]

Multilingual multiuser multiblog engine

Class: Results

Class Results

Packages

Classes

Files