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 Program_Root/widgets/data_list/DataList.inc (line 108)

Container
   |
   --BaseWidget
      |
      --DataList
Direct descendents
Class Description
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.
SimpleGUIDataList This object is the base class that can be
ListAction A class for showing a list of items to preform an action on
Variable Summary
Method Summary
void 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 (mixed $offset, [mixed $showall_flag = FALSE], mixed $showall_value)
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 filter_column_string (string $data)
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 ()
void gui_init ()
boolean is_search_enabled ()
int numrows ()
int offset ()
string. orderby ()
void render (mixed $indent_level, mixed $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_data_source (DataListSource $datasource)
void set_default_num_rows (int $num_rows)
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 (mixed $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_reverseorder (string $new_value)
void set_save_vars (array $vars)
void set_search_type (string $type)
void set_show_results ([boolean $flag = TRUE])
void set_simple_search_modifier ([string $modifier = SEARCH_ALL])
string showall ()
void user_setup ()
Container _build_default_vars ()
mixed _build_save_vars ()
string _build_tool_url (int $offset, [boolean $showall_flag = FALSE], int $showall_value)
void _check_datasource (mixed $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 $alternating_row_colors = TRUE (line 138)

Do we want to alternate the row colors? This helps to see each row easier.

mixed $_advanced_search_flag = FALSE (line 187)

Flag to let us know that

advanced search is enabled

array $_columns = array() (line 220)

The column descriptions for the data we are working on

DataListSource $_datasource = NULL (line 258)

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

  • var:

    object

mixed $_default_orderby = '' (line 167)

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

mixed $_default_reverseorder = "false" (line 173)

Holds a flag to let us know to

reverse order the column by default

mixed $_default_rows_per_page = 10 (line 124)

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 232)

This holds the form attributes

mixed $_form_render_flag = FALSE (line 241)

Build everything inside a form?

mixed $_global_prefix = '' (line 145)

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

mixed $_image_path = "/phphtmllib/images/widgets" (line 266)

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 131)

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

mixed $_num_columns = 0 (line 225)

Keeps track of the # of columns we have

mixed $_num_pages = 1 (line 116)

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

mixed $_save_vars = array() (line 211)

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

mixed $_search_flag = FALSE (line 180)

Flag to let us know that search is enabled.

mixed $_search_table = NULL (line 202)

Holds the object block that is the

search UI

mixed $_show_results_flag = TRUE (line 248)

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

mixed $_simple_search_modifier = FALSE (line 195)

Flag to enable simple search modifyer.

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

mixed $_vars = array("offsetVar" => "offset",
"orderbyVar" => "orderby",
"reverseorderVar" => "reverseorder",
"numrowsVar" => "numrows",
"showallVar" => "showall",
"search_fieldVar" => "search_field",
"search_valueVar" => "search_value",
"search_typeVar" => "search_type",
"simple_search_modifierVar" => "simple_search_modifier")
(line 153)

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

Inherited Variables

Inherited from BaseWidget

BaseWidget::$title
BaseWidget::$width

Inherited from Container

Container::$_flags
Methods
Constructor DataList (line 277)

The constructor

void 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 592)

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 700)

Disable the advanced search

capability

void advanced_search_disable ()
advanced_search_enable (line 688)

Enable the advanced search

capability NOTE: Child class MUST extend the _build_advanced_search_table

void advanced_search_enable ()
build_base_url (line 1303)

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 1079)

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 1610)

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 399)

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 926)

This builds a query string var for the orderby value.

  • return:

    - "orderby=(thevalue)"

string build_orderby_querystring ()
build_reverseorder_querystring (line 957)

This builds a query string var for the reverseorder value.

  • return:

    - "orderby=(thevalue)"

string build_reverseorder_querystring ()
build_searchfield_querystring (line 998)

This builds a query string var for the searchfield value.

  • return:

    - "orderby=(thevalue)"

string build_searchfield_querystring ()
build_searchvalue_querystring (line 1019)

This builds a query string var for the searchfield value.

  • return:

    - "orderby=(thevalue)"

string build_searchvalue_querystring ()
build_state_vars_query_string (line 1480)

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 (mixed $offset, [mixed $showall_flag = FALSE], mixed $showall_value)
build_tool_link (line 1349)

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 530)

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 510)

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 557)

This function builds the search block that lives above the results

Container child_build_search_table ()

Redefined in descendants as:
child_get_gui (line 544)

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 805)

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 453)

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 ()
filter_column_string (line 1664)

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_current_page (line 1538)

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

int get_current_page ()
get_data_source (line 465)

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 771)

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

int get_default_num_rows ()
get_form_action (line 1187)

This function is used to get the form action

  • return:

    (POST or GET)

string get_form_action ()
get_form_method (line 1168)

This function is used to get the form method

  • return:

    (POST or GET)

string get_form_method ()
get_form_name (line 1124)

This function is used to get the form name

string get_form_name ()
get_form_render (line 1205)

Return the state of the form render

bool get_form_render ()
get_form_target (line 1144)

This function is used to get the form target

string get_form_target ()
get_global_prefix (line 635)

returns the current variable prefix string being used.

  • return:

    - current global prefix

string get_global_prefix ()
get_image_path (line 1518)

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

string get_image_path ()
get_last_page (line 1566)

This calculates the last page # for this list of items

int get_last_page ()
get_max_rows (line 781)

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

int get_max_rows ()
get_num_pages (line 1549)

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

int get_num_pages ()
get_page_info (line 1577)

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_simple_search_modifier (line 750)

gets the value of the search modifier flag.

void get_simple_search_modifier ()
gui_init (line 492)

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 710)

This returns the status of the advanced search flag.

boolean is_advanced_search_enabled ()
is_search_enabled (line 676)

get the status of the search ability.

boolean is_search_enabled ()
numrows (line 968)

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

  • return:

    - the number of rows

int numrows ()
offset (line 896)

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 916)

This function returns the value of the current orderby variable.

string. orderby ()
render (line 321)

This function renders the final

widget

void render (mixed $indent_level, mixed $output_debug)

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

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

string. reverseorder ()
search_disable (line 666)

Disable the search ability.

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

Enable the search ability.

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

returns the current value of the search field name

string search_field ()
search_type (line 1040)

returns the type of search being used

string search_type ()
search_value (line 1009)

returns the current value of te search field value.

string search_value ()
search_value_filter (line 1756)

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 827)
void setup_columns ()
set_data_source (line 645)

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

void set_data_source (DataListSource $datasource)
set_default_num_rows (line 761)

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_form_action (line 1177)

Sets the form action

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

This function is used to set the form method

void set_form_method (string $method)
  • string $method:

    (POST or GET)

set_form_name (line 1114)

This function is used to set the form name

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

Sets whether to the output into a form

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

This function is used to set the form target

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

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 1528)

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

string set_image_path (mixed $path)
set_max_rows (line 793)

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 1215)

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 978)

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 906)

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_reverseorder (line 947)

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 1270)

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 1050)

This function sets the search type

void set_search_type (string $type)
  • string $type:

    - the search type "simple" or "advanced"

set_show_results (line 1227)

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 735)

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
showall (line 1062)

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

  • return:

    - the current value

string showall ()
simple_search_modifier_value (line 1030)

returns the current value of the simple search modifier

string simple_search_modifier_value ()
user_setup (line 478)

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 1282)

This function builds the list of

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

Container _build_default_vars ()
_build_save_vars (line 1254)

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 1721)

This builds the simple search modifier select box.

  • return:

    object.

INPUTtag _build_simple_search_modifier ()
_build_tool_url (line 1450)

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

(first, prev, next, last, all)

string _build_tool_url (int $offset, [boolean $showall_flag = FALSE], int $showall_value)
  • int $offset:

    - the offset for the link

  • boolean $showall_flag:

    - add the showall value to the url

  • int $showall_value:

    - the showall value to use if the flag is on

_check_datasource (line 847)

general DataListSource object checker.

void _check_datasource (mixed $function_name)
_clean_string (line 1680)

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 1099)

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 870)

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 1705)

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

array _get_searchable_fields ()
_javascript (line 571)

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 1507)

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 885)

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 1238)

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_title()
BaseWidget::set_width()

Inherited From Container

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

Documention generated on Thu, 31 Jul 2003 18:32:21 -0700 by phpDocumentor 1.2.0