Class DataList

Description

This object is the base class that can be

used to build a widget that shows lists of data from any source via the DataListSource object. It fetches/builds/gets its data from the DataListSource object, which can be written to support any data source (MySQL, Oracle, comma delimited file, xml, etc.)

This base class MUST be extended by a child to actually render the list. The job of the DataList class is to provide the basic API and abstraction mechanism to handling searching, showing, sorting lists of data.

Each column of data is associated with a title and a name. The title is what is shown to the user for that column. The name is the mapping between the column and the DataListSource. Each column can be marked as sortable and searchable. If a column is sortable, the title is a link that can be clicked on to sort. The sorting is done in the DataListSource object ( via the sql query, or sort() functions depending on the data source itself)

The DataList object will build the title, the search block (if any), the datalist controls (the links/imges for first, prev, next, last, all). Then the data columns/labels. Then it will fetch each of the rows of data to display from the DataListSource.

The logic of the output calls follows in the order:

title search table/block datalist controls (first, prev, next, last, all) data columns/labels data rows x through y

REQUIREMENTS: You must use/define a DataListSource object. You MUST override/extend the following methods:

* get_data_source() - used to set the DataListSource by this class. * user_setup() - used to set the columns to show and any options used by the DataList class and DataListSource object.

UI ABSTRACTION METHODS These methods allow for some level of abstraction for the layout/look/feel of the actual list of data.

* gui_init() - the function gives the child class a chance to do any building of the objects that will hold the search area, column headers and the rows of data.

* child_build_column_header() - This method is responsible for building and inserting the column header title into the UI object.

* child_add_row_cell() - This function is responsible for adding the cell in the current row. The method is responsible for keeping track of the location in its UI object for the current row.

* child_get_gui() - This method returns the entire UI in 1 object or container. At this point the entire UI has been constructed, the entire list of data has been walked and inserted.

Located in /widgets/data_list/DataList.inc (line 118)

Container
   |
   --BaseWidget
      |
      --DataList
Direct descendents
Class Description
SimpleGUIDataList This object is the base class that can be
DefaultGUIDatalist This class is the Default phpHtmlLib GUI interface child of the DataList class. This child simply does the job of rendering the html/layout for a DataList.
ListAction A class for showing a list of items to preform an action on
Variable Summary
Method Summary
DataList DataList (string $title, [string $width = "100%"], [string $default_orderby = ''], [boolean $default_reverseorder = FALSE])
array add_header_item (string $label, [int $size = 100], [string $data_name = NULL], [boolean $sortable = FALSE], [boolean $searchable = FALSE], [string $align = "left"], [string $sortorder = ""], [string $max_text_length = NULL])
string build_base_url ()
mixed build_column_item (array $row_data, string $col_name)
Atag build_column_url (string $col_name)
Container build_gui ()
string build_state_vars_query_string (int $offset, [boolean $expandrows_flag = FALSE], [int $expandrows_value = 0])
Object build_tool_link (string $which)
void child_add_row_cell (mixed $obj, string $col_name, boolean $last_in_row_flag)
void child_build_column_header (string $title, array $col_data, int $col_count)
Container child_get_gui ()
void data_prefetch ()
void do_action ()
string expandrows ()
string filter_column_string (string $data)
boolean get_cleanstring ()
void get_data_source ()
string get_form_action ()
string get_form_method ()
string get_form_name ()
bool get_form_render ()
string get_form_target ()
string get_global_prefix ()
string get_image_path ()
int get_last_page ()
int get_max_rows ()
int get_num_pages ()
string get_page_info ()
boolean get_showall ()
void gui_init ()
boolean is_search_enabled ()
int numrows ()
int offset ()
string. orderby ()
void render ( $indent_level,  $output_debug)
string. reverseorder ()
void search_disable (boolean 0)
void search_enable (boolean 0)
string search_field ()
string search_type ()
string search_value ()
string search_value_filter (string $value)
void setup_columns ()
void set_cleanstring ([boolean $flag = TRUE])
void set_data_source (DataListSource $datasource)
none set_debug ([mixed $level = FALSE])
void set_default_num_rows (int $num_rows)
void set_expandrows ([boolean $flag = TRUE])
void set_form_action (string $action)
void set_form_method (string $method)
void set_form_name (string $name)
void set_form_render (bool $flag)
void set_form_target (string $target)
void set_global_prefix (string $prefix)
string set_image_path ( $path)
void set_max_rows (int $max)
void set_not_found_message (string $mesg)
void set_numrows (int $new_numrows)
void set_offset (int $new_offset)
void set_orderby (string $orderby)
void set_reverseorder (string $new_value)
void set_save_vars (array $vars)
void set_search_type (string $type)
void set_showall ([boolean $flag = TRUE])
void set_show_results ([boolean $flag = TRUE])
void set_simple_search_modifier ([string $modifier = SEARCH_ALL])
void user_setup ()
Container _build_default_vars ()
mixed _build_save_vars ()
string _build_tool_url (int $offset, [boolean $expandrows_flag = FALSE], [int $expandrows_value = 0])
void _check_datasource ( $function_name)
mixed _clean_string (mixed $obj, string $col_name)
string _filter_column_string (string $data)
the _get (string $name, [mixed $default_value = NULL])
void _save_mozilla_nav_link (string $which, string $url)
void _set (string $name, mixed $value)
boolean _show_results ()
Variables
mixed $_advanced_search_flag = FALSE (line 197)

Flag to let us know that

advanced search is enabled

mixed $_clean_string = TRUE (line 281)

flag indicating if we should scrub the data

array $_columns = array() (line 230)

The column descriptions for the data we are working on

DataListSource $_datasource = NULL (line 268)

Holds our reference/copy of the DataListSource object which is used to access the data that this object uses

  • var: object
mixed $_debug = FALSE (line 288)

debugging flag for debugging queries.

mixed $_default_orderby = '' (line 177)

Holds the db column name that we want to order by default.

mixed $_default_reverseorder = "false" (line 183)

Holds a flag to let us know to

reverse order the column by default

mixed $_default_rows_per_page = 10 (line 134)

The number of rows of data to show per "page".

The default is 20.

mixed $_form_attributes = array("method" => "get",
"target" => "",
"action" => "",
"name" => "datalist")
(line 242)

This holds the form attributes

mixed $_form_render_flag = FALSE (line 251)

Build everything inside a form?

mixed $_global_prefix = '' (line 155)

prefix for all list variable names, so we can potentially have more then 1 list per page.

mixed $_image_path = PHPHTMLLIB_WIDGET_IMAGEPATH (line 276)

This stores the base path to where the tool link images live. This lets you specify a new path to where your images live.

mixed $_max_rows = 200 (line 141)

The max number of rows to show when the user does the "EXPAND" command.

mixed $_not_found_message = "No data was found" (line 294)

This is the message displayed when no data

was retrieved from the database

mixed $_num_columns = 0 (line 235)

Keeps track of the # of columns we have

mixed $_num_pages = 1 (line 126)

This value holds the number of pages of data we have to display.

mixed $_save_vars = array() (line 221)

This holds a list of name=>value vars that the caller/child wants to propogate automatically.

mixed $_search_flag = FALSE (line 190)

Flag to let us know that search is enabled.


Redefined in descendants as:
mixed $_search_table = NULL (line 212)

Holds the object block that is the

search UI

mixed $_show_all_rows = FALSE (line 148)

Flag to tell us to show every row that comes from the DB or not.

By default this is off.

mixed $_show_results_flag = TRUE (line 258)

flag to let us know if we want to show the results or not.

mixed $_simple_search_modifier = FALSE (line 205)

Flag to enable simple search modifyer.

IF enabled it will add a select that adds the "beings with", "contains" options for a simple search.


Redefined in descendants as:
mixed $_vars = array("offsetVar" => "offset",
"orderbyVar" => "orderby",
"reverseorderVar" => "reverseorder",
"numrowsVar" => "numrows",
"expandrowsVar" => "expandrows",
"search_fieldVar" => "search_field",
"search_valueVar" => "search_value",
"search_typeVar" => "search_type",
"simple_search_modifierVar" => "simple_search_modifier")
(line 163)

Holds an array of all the form vars we need for this class to work.

Inherited Variables

Inherited from BaseWidget

BaseWidget::$title
BaseWidget::$width
BaseWidget::$_image_prefix
Methods
Constructor DataList (line 305)

The constructor

DataList DataList (string $title, [string $width = "100%"], [string $default_orderby = ''], [boolean $default_reverseorder = FALSE])
  • string $title: - the title of the data list
  • string $width: - the overall width
  • string $default_orderby: - the column to use as the default sorting order
  • boolean $default_reverseorder: - sort the default column in reverse order?
add_header_item (line 628)

This function adds a header item to the column headers from a list of parameters.

  • return: a single header array
array add_header_item (string $label, [int $size = 100], [string $data_name = NULL], [boolean $sortable = FALSE], [boolean $searchable = FALSE], [string $align = "left"], [string $sortorder = ""], [string $max_text_length = NULL])
  • string $label: - $label - the label to use for the column header.
  • int $size: - $size - the size for the table column.
  • string $data_name: - $dbfield - the db field associated with this label from the query.
  • boolean $sortable: - $sortable - flag to make this column sortable.
  • boolean $searchable: - $searchable - flag to make this column searchable.
  • string $align: - header align value.
  • string $sortorder: - the sort order
  • string $max_text_length: - the maximum # of characters to allow in the cell.
advanced_search_disable (line 734)

Disable the advanced search

capability

void advanced_search_disable ()
advanced_search_enable (line 724)

Enable the advanced search

capability NOTE: Child class MUST extend the _build_advanced_search_table

void advanced_search_enable ()
build_base_url (line 1453)

This builds the base url used by the column headers as well as the page tool links.

it basically builds: $_SELF?$_GET

string build_base_url ()
build_column_item (line 1222)

This is the basic function for letting us do a mapping between the column name in the header, to the value found in the DB.

NOTE: this function is meant to be overridden so that you can push whatever you want.

  • return: - either a HTMLTag object, or raw text.
mixed build_column_item (array $row_data, string $col_name)
  • array $row_data: - $row_data - the entire data for the row
  • string $col_name: - $col_name - the name of the column header for this row to render.
build_column_url (line 1778)

This builds a url for a particular column header.

  • return: object;
Atag build_column_url (string $col_name)
  • string $col_name: - $col_name
build_gui (line 431)

This function is responsible for calling the child class's methods for building the GUI container.

This function builds the search area, the title, page controls, the column headers, and walks the rows of data and adds them

A child class can override this method to move the placement of the search box relative to the data list. By default the search area comes above the table for the data list and page controls

Container build_gui ()

Redefined in descendants as:
build_orderby_querystring (line 1054)

This builds a query string var for the orderby value.

  • return: - "orderby=(thevalue)"
string build_orderby_querystring ()
build_reverseorder_querystring (line 1085)

This builds a query string var for the reverseorder value.

  • return: - "orderby=(thevalue)"
string build_reverseorder_querystring ()
build_searchfield_querystring (line 1126)

This builds a query string var for the searchfield value.

  • return: - "orderby=(thevalue)"
string build_searchfield_querystring ()
build_searchvalue_querystring (line 1147)

This builds a query string var for the searchfield value.

  • return: - "orderby=(thevalue)"
string build_searchvalue_querystring ()
build_state_vars_query_string (line 1633)

this function is used to build a sub query string

of all of the query string vars to save the state of the DBItemList. This is used for pages that want to come back to the list at the same state

  • return: - name=value& pairs
string build_state_vars_query_string (int $offset, [boolean $expandrows_flag = FALSE], [int $expandrows_value = 0])
  • int $offset: - the offset for the link
  • boolean $expandrows_flag: - add the expandrows value to the url
  • int $expandrows_value: - the expandrows value to use if the flag is on
build_tool_link (line 1499)

This function builds the 'tool' images that allow you to walk through the data list itself.

It provides image links for first - go to the first page in the data list prev - go to the previous page in the data list next - go to the next page in the data list last - go to the last page in the data list all - show the rest of the list from the current offset

Object build_tool_link (string $which)
  • string $which: - which tool image to build
child_add_row_cell (line 566)

This method is supposed to be written by the child class to add the cell data to the current row in the UI

void child_add_row_cell (mixed $obj, string $col_name, boolean $last_in_row_flag)
  • mixed $obj: - the object/string/entity that should get put into the column row cell.
  • string $col_name: - the name/title of the column that the object will live in
  • boolean $last_in_row_flag: - flag that tells the function if this is is the last cell for the current row.

Redefined in descendants as:
child_build_column_header (line 546)

This method is supposed to be written by the child class to build and add the column title to the UI

void child_build_column_header (string $title, array $col_data, int $col_count)
  • string $title: - the title of the column
  • array $col_data: - the column data ( from $this->_columns )
  • int $col_count: - the column #

Redefined in descendants as:
child_build_search_table (line 593)

This function builds the search block that lives above the results

Container child_build_search_table ()

Redefined in descendants as:
child_get_gui (line 580)

This function is called after all of the data has been added to the UI object. It just returns the container that is the entire UI for the DataList

Container child_get_gui ()

Redefined in descendants as:
data_prefetch (line 879)

This function is used to set up any

data that needs to be munged before the data is fetched from the DataListSource

void data_prefetch ()
do_action (line 489)

This method is called prior to get_data_source and user_setup() to allow you to do some generic action on data. By default this does nothing.

void do_action ()
expandrows (line 1190)

returns the current value of the expandrows flag. This tells us if they want the entire list of data back from the DB.

  • return: - the current value
string expandrows ()
filter_column_string (line 1836)

This does some magic filtering on the data that we display in a column. This helps to prevent nast data that may have html tags in it.

  • return: the cleaned/filtered data
string filter_column_string (string $data)
  • string $data: - the column data u want to filter
get_cleanstring (line 847)

return the value of the clean string flag

boolean get_cleanstring ()
get_current_page (line 1691)

This function returns the current page that the item list is on.

int get_current_page ()
get_data_source (line 501)

This function is called automatically by the DataList constructor. It must be extended by the child class to actually set the DataListSource object.

void get_data_source ()
get_default_num_rows (line 805)

This function gets the current default number of rows to display setting.

int get_default_num_rows ()
get_form_action (line 1330)

This function is used to get the form action

  • return: (POST or GET)
string get_form_action ()
get_form_method (line 1311)

This function is used to get the form method

  • return: (POST or GET)
string get_form_method ()
get_form_name (line 1267)

This function is used to get the form name

string get_form_name ()
get_form_render (line 1348)

Return the state of the form render

bool get_form_render ()
get_form_target (line 1287)

This function is used to get the form target

string get_form_target ()
get_global_prefix (line 671)

returns the current variable prefix string being used.

  • return: - current global prefix
string get_global_prefix ()
get_image_path (line 1671)

This function returns the path to the images used in this class

string get_image_path ()
get_last_page (line 1723)

This calculates the last page # for this list of items

int get_last_page ()
get_max_rows (line 815)

This returns the Maximum # of rows to display when in expand mode

int get_max_rows ()
get_not_found_message (line 1368)

This function is used to get the message displayed when no data is found

string get_not_found_message ()
get_num_pages (line 1702)

This function returns the # of pages that are available for this list of items.

int get_num_pages ()
get_page_info (line 1734)

This function builds the string that describes the current page out of n pages the list is showing

  • return: (ie. 1 to 10 of 25)
string get_page_info ()
get_showall (line 867)

This returns the value of the show all rows flag

boolean get_showall ()
get_simple_search_modifier (line 784)

gets the value of the search modifier flag.

void get_simple_search_modifier ()
gui_init (line 528)

A subclass can override this function to setup the class variables after the constructor. The constructor automatically calls this function.

void gui_init ()

Redefined in descendants as:
is_advanced_search_enabled (line 744)

This returns the status of the advanced search flag.

boolean is_advanced_search_enabled ()
is_search_enabled (line 712)

get the status of the search ability.

boolean is_search_enabled ()
numrows (line 1096)

This function returns the number of rows that the query found.

  • return: - the number of rows
int numrows ()
offset (line 1010)

This function returns the current value of the offset variable. This is an offset into the query return data set.

  • return: - the current value.
int offset ()
orderby (line 1034)

This function returns the value of the current orderby variable.

string. orderby ()
pre_query_sanity_check (line 920)

This method is used to do a sanity check on the data that is about to be passed to the query for security reasons and data type checks.

This function is responsible for detecting any invalid values and setting them to their defaults if they are bogus to protect the query

none pre_query_sanity_check ()
render (line 353)

This function renders the final

widget

void render ( $indent_level,  $output_debug)
  • $indent_level
  • $output_debug

Redefinition of:
Container::render()
This function is compatible with the rest of the phpHtmllib API spec.
reverseorder (line 1065)

This function returns the current value of the reverse order member variable.

string. reverseorder ()
search_disable (line 702)

Disable the search ability.

void search_disable (boolean 0)
  • boolean 0
search_enable (line 690)

Enable the search ability.

void search_enable (boolean 0)
  • boolean 0
search_field (line 1116)

returns the current value of the search field name

string search_field ()
search_type (line 1168)

returns the type of search being used

string search_type ()
search_value (line 1137)

returns the current value of te search field value.

string search_value ()
search_value_filter (line 1936)

This function is used to make safe any query string value that is used

string search_value_filter (string $value)
  • string $value
setup_columns (line 941)
void setup_columns ()
set_cleanstring (line 837)

This method sets the flag to tell us if we want to clean the data

void set_cleanstring ([boolean $flag = TRUE])
  • boolean $flag: TRUE = clean it
set_data_source (line 681)

This function is used to set the DataListSource object for this instance

void set_data_source (DataListSource $datasource)
set_debug (line 1948)

This function is used to set the debug level.

none set_debug ([mixed $level = FALSE])
  • mixed $level
set_default_num_rows (line 795)

This function sets the default # of rows per page to display. By default its 10.

This lets the user override this value.

void set_default_num_rows (int $num_rows)
  • int $num_rows: - the # of rows to use.
set_expandrows (line 1204)

This sets the expandrows.

void set_expandrows ([boolean $flag = TRUE])
  • boolean $flag
set_form_action (line 1320)

Sets the form action

void set_form_action (string $action)
  • string $action
set_form_method (line 1297)

This function is used to set the form method

void set_form_method (string $method)
  • string $method: (POST or GET)
set_form_name (line 1257)

This function is used to set the form name

void set_form_name (string $name)
  • string $name
set_form_render (line 1339)

Sets whether to the output into a form

void set_form_render (bool $flag)
  • bool $flag
set_form_target (line 1277)

This function is used to set the form target

void set_form_target (string $target)
  • string $target
set_global_prefix (line 657)

This function sets a prefix for all variables that are used in the item list table on a page. This allows you to have multiple itemlists on a single html page.

void set_global_prefix (string $prefix)
  • string $prefix: - the prefix for all vars.

Redefined in descendants as:
  • DefaultGUIDatalist::set_global_prefix() : This function sets a prefix for all variables that are used in the item list table on a page. This allows you to have multiple itemlists on a single html page.
set_image_path (line 1681)

This function returns the path to the images used in this class

string set_image_path ( $path)
  • $path
set_max_rows (line 827)

This sets the maximum # of rows to display when in expand mode

void set_max_rows (int $max)
  • int $max: - new # of maximum rows to display when in 'expand' mode
set_not_found_message (line 1358)

This function is used to set the message displayed when no data is found

void set_not_found_message (string $mesg)
  • string $mesg
set_numrows (line 1106)

This function sets the # of rows to display per page.

void set_numrows (int $new_numrows)
  • int $new_numrows: - the # of rows
set_offset (line 1024)

This function is used to set/change the offset for this list.

void set_offset (int $new_offset)
  • int $new_offset: - the new offset.
set_orderby (line 1043)

This is used to reset the orderby

void set_orderby (string $orderby)
  • string $orderby
set_reverseorder (line 1075)

This function sets the reverse order flag to a new value.

void set_reverseorder (string $new_value)
  • string $new_value: - the new value.
set_save_vars (line 1422)

This function sets the save variables that the user/child wants to automatically propogate

void set_save_vars (array $vars)
  • array $vars: - name=>value pairs of the data that they want to propogate
set_search_type (line 1178)

This function sets the search type

void set_search_type (string $type)
  • string $type: - the search type "simple" or "advanced"
set_showall (line 857)

This method sets the flag to tell us to show every row found in the DataListSource.

void set_showall ([boolean $flag = TRUE])
  • boolean $flag: TRUE = show all rows
set_show_results (line 1379)

This function is used to set the value of the _show_results_flag

void set_show_results ([boolean $flag = TRUE])
  • boolean $flag: - TRUE to show the results
set_simple_search_modifier (line 769)

Set the simple search modifyer flag.

NOTE: by default all the modifiers are enabled. You can limit the modifiers by passing in the string of defines of which ones you want enabled.

MODIFIERS: SEARCH_BEGINS_WITH SEARCH_CONTAINS SEARCH_EXACT SEARCH_ENDS_WITH

ie. SEARCH_BEGINS_WITH.SEARCH_EXACT will enable ONLY the "begins with" and "exact" modifiers.

void set_simple_search_modifier ([string $modifier = SEARCH_ALL])
  • string $modifier
simple_search_modifier_value (line 1158)

returns the current value of the simple search modifier

string simple_search_modifier_value ()
user_setup (line 514)

A subclass can override this function to setup the class variables after the constructor. The constructor automatically calls this function.

void user_setup ()
_build_default_vars (line 1434)

This function builds the list of

default hidden form vars for when the datalist is being rendered as a POST

Container _build_default_vars ()

Redefined in descendants as:
_build_save_vars (line 1406)

this method builds some hidden form fields to automatically be placed inside the form.

This method returns a list of hidden form fields if we are a POST. It returns a portion of a query string If we are a GET.

  • return: depending on form method
mixed _build_save_vars ()
_build_simple_search_modifier (line 1901)

This builds the simple search modifier select box.

  • return: object.
INPUTtag _build_simple_search_modifier ()
_build_tool_url (line 1600)

This function is used to build the url for a tool link.

(first, prev, next, last, all)

string _build_tool_url (int $offset, [boolean $expandrows_flag = FALSE], [int $expandrows_value = 0])
  • int $offset: - the offset for the link
  • boolean $expandrows_flag: - add the expandrows value to the url
  • int $expandrows_value: - the expandrows value to use if the flag is on
_check_datasource (line 961)

general DataListSource object checker.

void _check_datasource ( $function_name)
  • $function_name
_clean_string (line 1852)

This function is used to make sure that the string we are placing in a cell has been "cleaned"

  • return: - the cleaned string or object
mixed _clean_string (mixed $obj, string $col_name)
  • mixed $obj: - the cell object. It can be a string.
  • string $col_name: - the name of the column this object/string will live
_filter_column_string (line 1242)

This does some magic filtering on the data that we display in a column. This helps to prevent nast data that may have html tags in it.

  • return: the cleaned/filtered data
string _filter_column_string (string $data)
  • string $data: - the column data u want to filter
_get (line 984)

Function used to get the current value of one of the control vars for this class

  • return: current value or default if not set
the _get (string $name, [mixed $default_value = NULL])
  • string $name: - the name we want to get
  • mixed $default_value: - the default value if not set
_get_searchable_fields (line 1883)

This method gets the array of searchable header fields (columns)

array _get_searchable_fields ()
_javascript (line 607)

This function provides a way to automatically add javascript to this object.

This function is meant to be extended by the child class.

  • return: object
SCRIPTtag _javascript ()

Redefined in descendants as:
_save_mozilla_nav_link (line 1660)

This function stores the url for each of the tool urls, so we can push these out for mozilla.

Mozilla has a nice navigation bar feature that lets you program first, prev, next, last links

void _save_mozilla_nav_link (string $which, string $url)
  • string $which: - which tool link
  • string $url: - the url for that link
_set (line 999)

This function is used to set the value of the control var

void _set (string $name, mixed $value)
  • string $name: - the name we want to get
  • mixed $value: - the new value for it.
_show_results (line 1390)

This function is used to let render() know that we should show the results or not.

boolean _show_results ()

Inherited Methods

Inherited From BaseWidget

BaseWidget::get_align()
BaseWidget::get_css()
BaseWidget::get_javascript()
BaseWidget::get_title()
BaseWidget::get_width()
BaseWidget::set_align()
BaseWidget::set_image_path_prefix()
BaseWidget::set_title()
BaseWidget::set_width()

Inherited From Container

Container::Container()
Container::add()
Container::add_reference()
Container::count_content()
Container::get_element()
Container::get_indent_flag()
Container::push()
Container::push_reference()
Container::render()
Container::reset_content()
Container::set_collapse()
Container::set_indent_flag()

Documentation generated on Fri, 28 Jan 2011 08:52:51 -0500 by phpDocumentor 1.4.3