CakeFest 2014
Improve this Doc

Paginator

class PaginatorHelper(View $view, array $settings = array())

The Pagination helper is used to output pagination controls such as page numbers and next/previous links. It works in tandem with PaginatorComponent.

See also Pagination for information on how to create paginated datasets and do paginated queries.

Creating a page counter

PaginatorHelper::counter($options = array())

Returns a counter string for the paged result set. Using a provided format string and a number of options you can create localized and application specific indicators of where a user is in the paged data set.

There are a number of options for counter(). The supported ones are:

  • format Format of the counter. Supported formats are ‘range’, ‘pages’ and custom. Defaults to pages which would output like ‘1 of 10’. In the custom mode the supplied string is parsed and tokens are replaced with actual values. The available tokens are:

    • {:page} - the current page displayed.
    • {:pages} - total number of pages.
    • {:current} - current number of records being shown.
    • {:count} - the total number of records in the result set.
    • {:start} - number of the first record being displayed.
    • {:end} - number of the last record being displayed.
    • {:model} - The pluralized human form of the model name. If your model was ‘RecipePage’, {:model} would be ‘recipe pages’. This option was added in 2.0.

    You could also supply only a string to the counter method using the tokens available. For example:

    echo $this->Paginator->counter(
        'Page {:page} of {:pages}, showing {:current} records out of
         {:count} total, starting on record {:start}, ending on {:end}'
    );
    

    Setting ‘format’ to range would output like ‘1 - 3 of 13’:

    echo $this->Paginator->counter(array(
        'format' => 'range'
    ));
    
  • separator The separator between the actual page and the number of pages. Defaults to ‘ of ‘. This is used in conjunction with ‘format’ = ‘pages’ which is ‘format’ default value:

    echo $this->Paginator->counter(array(
        'separator' => ' of a total of '
    ));
    
  • model The name of the model being paginated, defaults to PaginatorHelper::defaultModel(). This is used in conjunction with the custom string on ‘format’ option.

Modifying the options PaginatorHelper uses

PaginatorHelper::options($options = array())
Parameters:
  • $options (mixed) – Default options for pagination links. If a string is supplied - it is used as the DOM id element to update.

Sets all the options for the Paginator Helper. Supported options are:

  • url The URL of the paginating action. ‘url’ has a few sub options as well:

    • sort The key that the records are sorted by.
    • direction The direction of the sorting. Defaults to ‘ASC’.
    • page The page number to display.

    The above mentioned options can be used to force particular pages/directions. You can also append additional URL content into all URLs generated in the helper:

    $this->Paginator->options(array(
        'url' => array(
            'sort' => 'email', 'direction' => 'desc', 'page' => 6,
            'lang' => 'en'
        )
    ));
    

    The above adds the en route parameter to all links the helper will generate. It will also create links with specific sort, direction and page values. By default PaginatorHelper will merge in all of the current pass and named parameters. So you don’t have to do that in each view file.

  • escape Defines if the title field for links should be HTML escaped. Defaults to true.

  • update The CSS selector of the element to update with the results of AJAX pagination calls. If not specified, regular links will be created:

    $this->Paginator->options(array('update' => '#content'));
    

    This is useful when doing AJAX Pagination. Keep in mind that the value of update can be any valid CSS selector, but most often is simpler to use an id selector.

  • model The name of the model being paginated, defaults to PaginatorHelper::defaultModel().

Using GET parameters for pagination

Normally Pagination in CakePHP uses Named Parameters. There are times you want to use GET parameters instead. While the main configuration option for this feature is in PaginatorComponent, you have some additional control in the view. You can use options() to indicate that you want other named parameters to be converted:

$this->Paginator->options(array(
  'convertKeys' => array('your', 'keys', 'here')
));

Configuring the PaginatorHelper to use a JavaScript helper

By default the PaginatorHelper uses JsHelper to do AJAX features. However, if you don’t want that and want to use a custom helper for AJAX links, you can do so by changing the $helpers array in your controller. After running paginate() do the following:

// In your controller action.
$this->set('posts', $this->paginate());
$this->helpers['Paginator'] = array('ajax' => 'CustomJs');

Will change the PaginatorHelper to use the CustomJs for AJAX operations. You could also set the ‘ajax’ key to be any helper, as long as that class implements a link() method that behaves like HtmlHelper::link()

Pagination in Views

It’s up to you to decide how to show records to the user, but most often this will be done inside HTML tables. The examples below assume a tabular layout, but the PaginatorHelper available in views doesn’t always need to be restricted as such.

See the details on PaginatorHelper in the API. As mentioned, the PaginatorHelper also offers sorting features which can be easily integrated into your table column headers:

// app/View/Posts/index.ctp
<table>
    <tr>
        <th><?php echo $this->Paginator->sort('id', 'ID'); ?></th>
        <th><?php echo $this->Paginator->sort('title', 'Title'); ?></th>
    </tr>
       <?php foreach ($data as $recipe): ?>
    <tr>
        <td><?php echo $recipe['Recipe']['id']; ?> </td>
        <td><?php echo h($recipe['Recipe']['title']); ?> </td>
    </tr>
    <?php endforeach; ?>
</table>

The links output from the sort() method of the PaginatorHelper allow users to click on table headers to toggle the sorting of the data by a given field.

It is also possible to sort a column based on associations:

<table>
    <tr>
        <th><?php echo $this->Paginator->sort('title', 'Title'); ?></th>
        <th><?php echo $this->Paginator->sort('Author.name', 'Author'); ?></th>
    </tr>
       <?php foreach ($data as $recipe): ?>
    <tr>
        <td><?php echo h($recipe['Recipe']['title']); ?> </td>
        <td><?php echo h($recipe['Author']['name']); ?> </td>
    </tr>
    <?php endforeach; ?>
</table>

The final ingredient to pagination display in views is the addition of page navigation, also supplied by the PaginationHelper:

// Shows the page numbers
echo $this->Paginator->numbers();

// Shows the next and previous links
echo $this->Paginator->prev(
  '« Previous',
  null,
  null,
  array('class' => 'disabled')
);
echo $this->Paginator->next(
  'Next »',
  null,
  null,
  array('class' => 'disabled')
);

// prints X of Y, where X is current page and Y is number of pages
echo $this->Paginator->counter();

The wording output by the counter() method can also be customized using special markers:

echo $this->Paginator->counter(array(
    'format' => 'Page {:page} of {:pages}, showing {:current} records out of
             {:count} total, starting on record {:start}, ending on {:end}'
));

Other Methods

Parameters:
  • $title (string) – Title for the link.
  • $url (mixed) – Url for the action. See Router::url()
  • $options (array) – Options for the link. See options() for list of keys.

Accepted keys for $options:

  • update The Id of the DOM element you wish to update. Creates AJAX enabled links.
  • escape Whether you want the contents HTML entity encoded, defaults to true.
  • model The model to use, defaults to PaginatorHelper::defaultModel().

Creates a regular or AJAX link with pagination parameters:

echo $this->Paginator->link('Sort by title on page 5',
        array('sort' => 'title', 'page' => 5, 'direction' => 'desc'));

If created in the view for /posts/index Would create a link pointing at ‘/posts/index/page:5/sort:title/direction:desc’

PaginatorHelper::url($options = array(), $asArray = false, $model = null)
Parameters:
  • $options (array) – Pagination/URL options array. As used on options() or link() method.
  • $asArray (boolean) – Return the URL as an array, or a URI string. Defaults to false.
  • $model (string) – Which model to paginate on

By default returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript).:

echo $this->Paginator->url(array('sort' => 'title'), true);
PaginatorHelper::defaultModel()

Gets the default model of the paged sets or null if pagination is not initialized.

PaginatorHelper::params(string $model = null)

Gets the current paging parameters from the resultset for the given model:

debug($this->Paginator->params());
/*
Array
(
    [page] => 2
    [current] => 2
    [count] => 43
    [prevPage] => 1
    [nextPage] => 3
    [pageCount] => 3
    [order] =>
    [limit] => 20
    [options] => Array
        (
            [page] => 2
            [conditions] => Array
                (
                )
        )
    [paramType] => named
)
*/
PaginatorHelper::param(string $key, string $model = null)

Gets the specific paging parameter from the resultset for the given model:

debug($this->Paginator->param('count'));
/*
(int)43
*/

New in version 2.4: The param() method was added in 2.4.