Pager

The pager component is a backend tool, that can be used to control the loading of database objects. To provide paging functionality, the pager is included in the modules comment function and guestbook. Below the intent and the functionalities are described in detail.


1. Usage

The pager merely consists of a business component (PagerManager), a presentation layer component that generates the HTML code of the pager widget (DocumentController pager_v1_controller and pager_2_v1_controller) and a data layer module that gathers information that are needed in the busines tier. To use the pager, it must be created by using the PagerManagerFabric.


2. Configuration

To be able to use a PagerManager for loading database objects it must be configured properly. Therefore the developer must create one configuration file and at two statement files. The config file envelops the following parameters:
APF-Template
[<SectionName>] Pager.DatabaseConnection = "<ConnectionKey>" Pager.EntriesPerPage = "<Objects per page>" Pager.ParameterStartName = "<URL parameter for the start parameter>" Pager.ParameterCountName = "<URL parameter for the count parameter>" Pager.StatementNamespace = "<Statement namespace>" Pager.CountStatement = "<Load-Entries-Count statement>" Pager.CountStatement.Params = "<Statement parameter>" Pager.EntriesStatement = "<Statement parameter>" Pager.EntriesStatement.Params = "<Load-Entry statement>" Pager.DesignNamespace = "<Namespace of the pres template>" Pager.DesignTemplate = "<Template name>" Pager.CacheInSession = "true|false"
Both of the statement files must contain a set of parameters, that can be filled by the PagerManager. Within the load entries count statements various parameters can be used to delimit the result set. These can be defined by the Pager.CountStatement.Params directive or while loading ids or business objects with the PagerManager. The result of the query is expected in the result offset EntriesCount (aliasing necessary!). Hence, the statement must contain an alias like this:
Code
SELECT COUNT(row) AS EntriesCount ...
The Load-Entry statement must always contain the LIMIT clause
Code
LIMIT [Start],[EntriesCount]
Further, the pager expects the result of the load entry statement to be stored in the offset DB_ID. Therefore the sql query must contain an alias definition like this:
Code
SELECT <row> AS DB_ID ...
Other parameters must be configured using the Pager.EntriesStatement.Params directive or while loading data with the PagerManager.

The params defined in the configuration file, should have the following semantic:
Code
param1:value1|param2:value2|...

Hints:
  • During initialization of the configuration param, the PagerManager tries to fill the params with values contained in the URL. This provides the possibility to influence the statement params by URL directly. If this is not wished to take placem you must take care, that the params do not appear in the request. Then, the params can be added to the statements as desired.

  • The config option Pager.CacheInSession defines, if the total count of objects and the ids of the current page is stored within a session to gain performance. If the option is set to true, the pager's data layer stores these information in the session. The data is thus valid as long as the session exists.

3. Example of use

A detailed description on the function of this modul and its usage can be found in the data layer chapter of the comment function tutorial. Besides, the API of the PagerManager is used as follows:

3.1. Load the relevant object IDs:

PHP-Code
// generate pagerManager $pMF = &$this->__getServiceObject('modules::pager::biz','PagerManagerFabric'); $pM = &$pMF->getPagerManager('{CONFIG_SECTION}'); // load IDs $IDs = $pM->loadEntries(array('AddParams' => 'Value')); // load data $M = &$this->__getServiceObject('namespace::to::data::component','DataMapper'); $list = array(); for($i = 0; $i < count($IDs); $i++){ $list[] = $M->loadDomainObjectByID($IDs[$i]); }

3.2. Load the business objects directly:

PHP-Code
// generate pagerManager $pMF = &$this->__getServiceObject('modules::pager::biz','PagerManagerFabric'); $pM = &$pMF->getPagerManager('{CONFIG_SECTION}'); // load data $M = &$this->__getServiceObject('namespace::to::data::component','DataMapper'); $list = $pM->loadEntriesByAppDataComponent($M,'loadDomainObjectByID',array('AddParams' => 'Value'));

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.