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
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 |
Flag to let us know that
advanced search is enabled
flag indicating if we should scrub the data
The column descriptions for the data we are working on
Holds our reference/copy of the DataListSource object which is used to access the data that this object uses
debugging flag for debugging queries.
Holds the db column name that we want to order by default.
Holds a flag to let us know to
reverse order the column by default
The number of rows of data to show per "page".
The default is 20.
This holds the form attributes
Build everything inside a form?
prefix for all list variable names, so we can potentially have more then 1 list per page.
This stores the base path to where the tool link images live. This lets you specify a new path to where your images live.
The max number of rows to show when the user does the "EXPAND" command.
This is the message displayed when no data
was retrieved from the database
Keeps track of the # of columns we have
This value holds the number of pages of data we have to display.
This holds a list of name=>value vars that the caller/child wants to propogate automatically.
Flag to let us know that search is enabled.
Holds the object block that is the
search UI
Flag to tell us to show every row that comes from the DB or not.
By default this is off.
flag to let us know if we want to show the results or not.
Flag to enable simple search modifyer.
IF enabled it will add a select that adds the "beings with", "contains" options for a simple search.
Holds an array of all the form vars we need for this class to work.
Inherited from BaseWidget
BaseWidget::$title
BaseWidget::$width
BaseWidget::$_image_prefix
The constructor
This function adds a header item to the column headers from a list of parameters.
Disable the advanced search
capability
Enable the advanced search
capability NOTE: Child class MUST extend the _build_advanced_search_table
This builds the base url used by the column headers as well as the page tool links.
it basically builds: $_SELF?$_GET
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.
This builds a url for a particular column header.
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
This builds a query string var for the orderby value.
This builds a query string var for the reverseorder value.
This builds a query string var for the searchfield value.
This builds a query string var for the searchfield value.
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
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
This method is supposed to be written by the child class to add the cell data to the current row in the UI
This method is supposed to be written by the child class to build and add the column title to the UI
This function builds the search block that lives above the results
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
This function is used to set up any
data that needs to be munged before the data is fetched from the DataListSource
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.
returns the current value of the expandrows flag. This tells us if they want the entire list of data back from the DB.
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 value of the clean string flag
This function returns the current page that the item list is on.
This function is called automatically by the DataList constructor. It must be extended by the child class to actually set the DataListSource object.
This function gets the current default number of rows to display setting.
This function is used to get the form action
This function is used to get the form method
This function is used to get the form name
Return the state of the form render
This function is used to get the form target
returns the current variable prefix string being used.
This function returns the path to the images used in this class
This calculates the last page # for this list of items
This returns the Maximum # of rows to display when in expand mode
This function is used to get the message displayed when no data is found
This function returns the # of pages that are available for this list of items.
This function builds the string that describes the current page out of n pages the list is showing
This returns the value of the show all rows flag
gets the value of the search modifier flag.
A subclass can override this function to setup the class variables after the constructor. The constructor automatically calls this function.
This returns the status of the advanced search flag.
get the status of the search ability.
This function returns the number of rows that the query found.
This function returns the current value of the offset variable. This is an offset into the query return data set.
This function returns the value of the current orderby variable.
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
This function renders the final
widget
This function returns the current value of the reverse order member variable.
Disable the search ability.
Enable the search ability.
returns the current value of the search field name
returns the type of search being used
returns the current value of te search field value.
This function is used to make safe any query string value that is used
This method sets the flag to tell us if we want to clean the data
This function is used to set the DataListSource object for this instance
This function is used to set the debug level.
This function sets the default # of rows per page to display. By default its 10.
This lets the user override this value.
This sets the expandrows.
Sets the form action
This function is used to set the form method
This function is used to set the form name
Sets whether to the output into a form
This function is used to set the form target
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.
This function returns the path to the images used in this class
This sets the maximum # of rows to display when in expand mode
This function is used to set the message displayed when no data is found
This function sets the # of rows to display per page.
This function is used to set/change the offset for this list.
This is used to reset the orderby
This function sets the reverse order flag to a new value.
This function sets the save variables that the user/child wants to automatically propogate
This function sets the search type
This method sets the flag to tell us to show every row found in the DataListSource.
This function is used to set the value of the _show_results_flag
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.
returns the current value of the simple search modifier
A subclass can override this function to setup the class variables after the constructor. The constructor automatically calls this function.
This function builds the list of
default hidden form vars for when the datalist is being rendered as a POST
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.
This builds the simple search modifier select box.
This function is used to build the url for a tool link.
(first, prev, next, last, all)
general DataListSource object checker.
This function is used to make sure that the string we are placing in a cell has been "cleaned"
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.
Function used to get the current value of one of the control vars for this class
This method gets the array of searchable header fields (columns)
This function provides a way to automatically add javascript to this object.
This function is meant to be extended by the child class.
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
This function is used to set the value of the control var
This function is used to let render() know that we should show the results or not.
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