The method {{display()}} is the place where we define the custom mask we created. This method accepts 2 optional arguments: one array of optional masks and if the output should be returned instead of printed on screen.
There are a couple of other methods that are available if you want to extend the {{Doctrine_Pager_Layout}} to create you custom layouter. We will see these methods in the next section.
{{Doctrine_Pager_Layout}} does a really good job, but sometimes it is not enough. Let's suppose a situation where you have to create a layout of pagination like this one:
Basic customization to generate this page links generation:
<< < 1 2 3 4 5 > >>
« ‹ 1 2 3 4 5 › »
Currently, it is impossible with raw {{Doctrine_Pager_Layout}}. But if you extend it and use the available methods, you can achieve it. The base Layout class provides you some methods that can be used to create your own implementation. They are:
<code type="php">
class PagerLayout extends Doctrine_Pager_Layout
{
public function initialize()
{
}
// $this refers to an instance of Doctrine_Pager_Layout
// Defines a mask replacement. When parsing template, it converts replacement
// masks into new ones (or values), allowing to change masks behavior on the fly
Until this place, the source you have is the same as the old {{Doctrine_Query}} object. The only difference is that now you have 2 new arguments. Your old query object plus these 2 arguments are now encapsulated by the {{Doctrine_Pager}} object.
At this stage, {{Doctrine_Pager}} already sent a dummy query to database to collect useful information to allow you to access them before even execute the real query. Let's say for example you want to know how many matches were found:
At this stage, {{Doctrine_Pager}} defines the basic data needed to control pagination. If you want to know that actual status of the pager, all you have to do is to check if it's already executed:
<code type="php">
echo 'Total of items found: ' . $pager->getNumResults();
$pager->getExecuted();
</code>
There are a couple of other interesting information that can be retrieved from pager before you execute the query. The API usage is listed at the end of this topic.
If you try to access any of the methods provided by Doctrine_Pager now, you'll experience {{Doctrine_Pager_Exception}} thrown, reporting you that Pager was not yet executed. When executed, {{Doctrine_Pager}} offer you powerful methods to retrieve information. The API usage is listed at the end of this topic.
To run the query, the process is similar to the current existent {{Doctrine_Query}} execute call. It even allow arguments the way you usually do it. Here is the PHP complete syntax, including the syntax of optional parameters:
...
...
@@ -31,9 +31,33 @@ To run the query, the process is similar to the current existent {{Doctrine_Quer
There are some special cases where the return records query differ of the counter query. To allow this situation, {{Doctrine_Pager}} has some methods that enable you to count and then to execute. The first thing you have to do is to define the count query:
<code type="php">
$pager->setCountQuery($query [, $params = null]);
// ...
$rs = $pager->execute();
</code>
The first param of {{setCountQuery}} can be either a valid {{Doctrine_Query}} object or a DQL string. The second argument you can define the optional parameters that may be sent in the counter query. If you do not define the params now, you're still able to define it later by calling the {{setCountQueryParams}}:
This method accepts 2 parameters. The first one is the params to be sent in count query and the second parameter is if the {{$params}} should be appended to the list or if it should override the list of count query parameters. The default behavior is to override the list.
One last thing to mention about count query is, if you do not define any parameter for count query, it will still send the parameters you define in {{$pager->execute()}} call.
Count query is always enabled to be accessed. If you do not define it and call {{$pager->getCountQuery()}}, it will return the "fetcher" query to you.
If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API:
<code type="php">
// Returns the check if Pager was already executed
$pager->getExecuted();
// Return the total number of itens found on query search
$pager->getNumResults();
...
...
@@ -46,7 +70,7 @@ $pager->getLastPage();
// Return the current page
$pager->getPage();
// Defines a new current page (automatically adjust offsets and values)
// Defines a new current page (need to call execute again to adjust offsets and values)
$pager->setPage($page);
// Return the next page
...
...
@@ -61,9 +85,24 @@ $pager->haveToPaginate();
// Return the maximum number of records per page
$pager->getMaxPerPage();
// Defined a new maximum number of records per page (automatically adjust offset and values)
// Defined a new maximum number of records per page (need to call execute again to adjust offset and values)
$pager->setMaxPerPage($maxPerPage);
// Returns the number of itens in current page
$pager->getResultsInPage();
// Returns the Doctrine_Query object that is used to make the count results to pager
$pager->getCountQuery();
// Defines the counter query to be used by pager
$pager->setCountQuery($query, $params = null);
// Returns the params to be used by counter Doctrine_Query (return $defaultParams if no param is defined)
