phpDocumentor pond
[ class tree: pond ] [ index: pond ] [ all elements ]

Class: Results

Source Location: /qp_inc/_core/ui/results/_results.class.php

Class Results

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

[ 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()
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
void   display_if_empty()   T-Tag: Display a message if Results 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()   Returns a scrolling page list under the table
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 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   $functions_area [line 225]

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

Should there be nofollows on page navigation


[ Top ]
array   $order_callbacks [line 219]

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


[ Top ]
mixed   $order_field_list [line 213]

List of sortable fields


[ Top ]
mixed   $order_param [line 208]

[ 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 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 252]

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

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

  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:

[ Top ]
display  [line 722]

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

  void display_body( )

Display list/table body.

This includes groups and data rows.



[ Top ]
display_first  [line 1600]

  void display_first( [ $page_url = '']  )

returns the link to the first page, if necessary

Parameters:
   $page_url: 


[ Top ]
display_functions  [line 1090]

  void display_functions( )

Display the functions



Redefined in descendants as:

[ Top ]
display_if_empty  [line 1777]

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

T-Tag: Display a message if Results list is empty

  1.  $params array_mergearray(
  2.    'before'    => '<p class="msg_nothing">',
  3.    'after'     => '</p>',
  4.    'msg_empty' => T_('Sorry, there is nothing to display...'),
  5.  )$params );

Parameters:
   $params: 

API Tags:
Usedby:  display_if_empty()
Usedby:  CommentList::display_if_empty()

Information Tags:
Todo:  EdB: one day this needs a 'class' param instead of assuming "msg_nothing"

Redefined in descendants as:

[ Top ]
display_init  [line 787]

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

  void display_last( [ $page_url = '']  )

returns the link to the last page, if necessary

Parameters:
   $page_url: 


[ Top ]
display_nav  [line 1144]

  void display_nav( string $template  )

Display navigation text, based on template.

Parameters:
string   $template:  template: 'header' or 'footer'


[ Top ]
display_next  [line 1647]

  void display_next( [ $page_url = '']  )

returns a link to next pages, if necessary

Parameters:
   $page_url: 


[ Top ]
display_prev  [line 1632]

  void display_prev( [ $page_url = '']  )

returns a link to previous pages, if necessary

Parameters:
   $page_url: 


[ Top ]
display_totals  [line 1011]

  void display_totals( )

Display totals line if set.



[ Top ]
first  [line 1564]

  void first( )

Returns the first page number to be displayed in the list



[ Top ]
get_col_sort_values  [line 1177]

  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:

[ Top ]
get_num_rows  [line 1758]

  integer get_num_rows( )

Get number of rows available for display



[ Top ]
get_order_field_list  [line 1247]

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

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

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

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

  void last( )

returns the last page number to be displayed in the list



[ Top ]
mergesort  [line 473]

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

  void move_icons( )


Information Tags:
Todo:  Support Results::$order_callbacks

[ Top ]
next_idx  [line 313]

  void next_idx( )

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



[ Top ]
order_callback_wrapper_objects  [line 552]

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

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

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

  void page_scroll_list( )

Returns a scrolling page list under the table



[ Top ]
parse_col_content  [line 1356]

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

  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:

[ Top ]
replace_callback  [line 1479]

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

  void reset( )

Reset the query -- EXPERIMENTAL

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



Redefined in descendants as:

[ Top ]
restart  [line 293]

  void restart( )

Rewind resultset



Redefined in descendants as:

[ Top ]