doctrine2/manual/docs/en/utilities/pagination/advanced-layouts-with-pager.txt

Until now, we learned how to create paginations and how to retrieve ranges around the current page. To abstract the business logic involving the page links generation, there is a powerful component called {{Doctrine_Pager_Layout}}.
The main idea of this component is to abstract php logic and only leave HTML to be defined by Doctrine developer.

{{Doctrine_Pager_Layout}} accepts 3 obrigatory arguments: a {{Doctrine_Pager}} instance, a {{Doctrine_Pager_Range}} subclass instance and a string which is the URL to be assigned as {%url} mask in templates. As you may see, there are 2 types of "variables" in {{Doctrine_Pager_Layout}}:

++++ Mask

A piece of string that is defined inside template as replacements. They are defined as **{%mask_name}** and are replaced by what you define in options or what is defined internally by {{Doctrine_Pager_Layout}} component. Currently, these are the internal masks available:

* **{%page}** Holds the page number, exactly as page_number, but can be overwritable by {{addMaskReplacement()}} to behavior like another mask or value
* **{%page_number}** Stores the current page number, but cannot be overwritable
* **{%url}** Available only in {{setTemplate()}} and {{setSelectedTemplate()}} methods. Holds the processed URL, which was defined in constructor

++++ Template

As the name explains itself, it is the skeleton of HTML or any other resource that is applied to each page returned by {{Doctrine_Pager_Range::rangeAroundPage()}} subclasses. There are 3 distinct templates that can be defined:

* {{setTemplate()}} Defines the template that can be used in all pages returned by {{Doctrine_Pager_Range::rangeAroundPage()}} subclass call
* {{setSelectedTemplate()}} Template that is applied when it is the page to be processed is the current page you are. If nothing is defined (a blank string or no definition), the template you defined in {{setTemplate()}} is used
* {{setSeparatorTemplate()}} Separator template is the string that is applied between each processed page. It is not included before the first call and after the last one. The defined template of this method is not affected by options and also it cannot process masks


Now we know how to create the {{Doctrine_Pager_Layout}} and the types that are around this component, it is time to view the basic usage:

<code type="php">
// Creating pager layout
$pager_layout = new Doctrine_Pager_Layout(
    new Doctrine_Pager(
        Doctrine_Query::create()
            ->from( 'User u' )
            ->leftJoin( 'u.Group g' )
            ->orderby( 'u.username ASC' ),
        $currentPage,
        $resultsPerPage
    ),
    new Doctrine_Pager_Range_Sliding(array(
        'chunk' => 5
    )),
    'http://wwww.domain.com/app/User/list/page,{%page}'
);

// Assigning templates for page links creation
$pager_layout->setTemplate('[<a href="{%url}">{%page}</a>]');
$pager_layout->setSelectedTemplate('[{%page}]');

// Retrieving Doctrine_Pager instance
$pager = $pager_layout->getPager();

// Fetching users
$users = $pager->execute();

// Displaying page links
// Displays: [1][2][3][4][5]
// With links in all pages, except the $currentPage (our example, page 1)
$pager_layout->display();
</code>

Explaining this source, the first part creates the pager layout instance. Second, it defines the templates for all pages and for the current page. The last part, it retrieves the {{Doctrine_Pager}} object and executes the query, returning in variable {{$users}}. The last part calls the displar without any optional mask, which applies the template in all pagfes found by {{Doctrine_Pager_Range::rangeAroundPage()}} subclass call.

As you may see, there is no need to use other masks except the internals ones. Lets suppose we implement a new functionality to search for Users in our existent application, and we need to support this feature in pager layout too. To simplify our case, the search parameter is named "search" and is received through {{$_GET}} superglobal array.
The first change we need to do is tho adjust the {{Doctrine_Query}} object and also the URL, to allow it to be sent to other pages.

<code type="php">
// Creating pager layout
$pager_layout = new Doctrine_Pager_Layout(
    new Doctrine_Pager(
        Doctrine_Query::create()
            ->from( 'User u' )
            ->leftJoin( 'u.Group g' )
            ->where( 'LOWER(u.username) LIKE LOWER(?)', array( '%'.$_GET['search'].'%' ) )
            ->orderby( 'u.username ASC' ),
        $currentPage,
        $resultsPerPage
    ),
    new Doctrine_Pager_Range_Sliding(array(
        'chunk' => 5
    )),
    'http://wwww.domain.com/app/User/list/page,{%page}?search={%search}'
);
</code>

Check out the code and notice we added a new mask, called {{{%search}}}. We'll need to send it to template processment at a later stage.
We then assign the templates, just as defined before, without any change. And also, we do not need to change execution of query.

<code type="php">
// Assigning templates for page links creation
$pager_layout->setTemplate('[<a href="{%url}">{%page}</a>]');
$pager_layout->setSelectedTemplate('[{%page}]');

// Retrieving Doctrine_Pager instance
$pager = $pager_layout->getPager();

// Fetching users
$users = $pager->execute();
</code>

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.
In our case, we need to define a new mask, the {{{%search}}}, which is the search offset of {{$_GET}} superglobal array. Also, remember that since it'll be sent as URL, it needs to be encoded.
Custom masks are defined in key => value pairs. So all needed code is to define an array with the offset we desire and the value to be replaced:

<code type="php">
// Displaying page links
$pager_layout->display( array(
    'search' => urlencode($_GET['search'])
) );
</code>

{{Doctrine_Pager_Layout}} component offers accessors to defined resources. There is not need to define pager and pager range as variables and send to the pager layout. These instances can be retrieved by these accessors:

<code type="php">
// Return the Pager associated to the Pager_Layout
$pager_layout->getPager();

// Return the Pager_Range associated to the Pager_Layout
$pager_layout->getPagerRange();

// Return the URL mask associated to the Pager_Layout
$pager_layout->getUrlMask();

// Return the template associated to the Pager_Layout
$pager_layout->getTemplate();

// Return the current page template associated to the Pager_Layout
$pager_layout->getSelectedTemplate();

// Return the current page template associated to the Pager_Layout
$pager_layout->getSeparatorTemplate();
</code>