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 functionality 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 (Document-Controller 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 configuration
[{SectionName}] Pager.DatabaseConnection = "ConnectionKey" Pager.EntriesPerPage = "{Objects per page}" Pager.ParameterPageName = "{URL parameter for the page parameter}" Pager.ParameterCountName = "{URL parameter for the entries per page 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" Pager.AllowDynamicEntriesPerPage = "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:

SQL statement
SELECT COUNT({row}) AS EntriesCount ...
The Load-Entry statement must always contain the LIMIT clause
SQL statement
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:
SQL statement
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.
The configuration directive Pager.AllowDynamicEntriesPerPage added in 1.13 activates the dynamic entries per page feature. By default this facility is deactivated for secutity reasons.

3. Example of use

A detailed description on the function of this module and its usage can be found in the data layer chapter of the comment function tutorial. Besides, the API documentation 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.