The Item List library provides a full-featured interface for searching, sorting and paginating results. Core concrete5 classes like PageList, UserList and FileList extend this library. If you extend the DatabaseItemList or ItemList class, you’ll easily get pagination and sorting.

Loading the Library

Loader::library(‘item_list’);

Extending the Library

	 class YourSearchList extends DatabaseItemList 

Instantiation

$l = new YourSearchList();

Properties

Your derived class can set the following variables:

$autoSortColumns

An associative array of column names which, when specified, are allowed to be sorted. This is used in the pagination/sorting display.

$sortByString

Allows a derived class to specify the sorting.

$sortByString = ‘name asc’;

$itemsPerPage

Specifies the default number of items per page.

$enableStickySearchRequest

When set to true, the search request will be stored in session, and will be remembered when it is next accessed.

Methods

When extending the DatabaseItemList class, the following methods will become available to your list class.

$l->getTotal()

Executes the query and runs NumRows() on the result, to return the total number of rows available in the result.

$l->debug()

When specified, the query will be output to the browser immediately prior to running.

$l->setQuery($query)

Sets the current query to $query.

$l->getQuery()

Returns the current database query.

$l->addToQuery($query)

Adds to the portion of the query that can be added to at runtime.

$l->get($itemsToGet = 0, $offset = 0)

Returns an array of items from the database. Derived classes can extend this to convert that array into the objects that they wish to return.

$l->filter($column, $value, $comparison = ‘=’)

Adds a filter to the current item list. $comparison can be any MySQL comparison operator.

$l->getSearchResultsClass($field)

Gets a sort class for a column based on whether it is being sorted, and in what direction.

$l->sortBy($key, $dir)

Sorts by column in a direction at runtime.

$l->sortByMultiple($field1, $field2, etc…)

Takes 1 to n fields to sort by. Includes direction

$l->sortByMultiple(“name asc”, “date_added desc”);

$l->getSortByURL($column, $dir = ‘asc’, $baseURL = false, $additionalVars = array())

Gets a “sort by” URL. Useful when working in search result columns.

$l->enableStickySearchRequest()

Turns sticky search request on.

$l->resetSearchRequest()

If sticky search request is enabled, resets the search request.

$l->getSearchRequest()

Gets the current search request, whether from the $_REQUEST variable or the $_SESSION sticky search request for this search type.

$l->setItemsPerPage($num)

Sets the number of items per page at runtime

$l->setNameSpace($ns)

Sets a namespace for this entire search request. Useful when displaying multiple search fields and forms on the same page.

$l->getPage($page = false)

Returns the contents of get() based on a page. If $page is false, gets the current page.

$l->displaySummary()

Outputs summary text about a list (‘Viewing X to X of X total.’)

$l->getPagination($url = false, $additionalVars = array())

Returns a pagination object for the current search request.

$l->requiresPaging()

Returns true if the current result set requires paging.

$l->displayPaging($script = false, $return = false, $additionalVars = array())

Displays pagination for the current list. If $script is defined, $script will be used as the base for all URLs. If $return is true, the HTML will be returned from the function, otherwise it will be printed. $additionalVars will be added to the query string.