PaginatorHelper¶

Creating sort links¶

PaginatorHelper::sort($key, $title = null, $options = array())¶

Parameters:

• $key (string) – The name of the key that the recordset should be sorted.

• $title (string) – Title for the link. If $title is null $key will be used for the title and will be generated by inflection.

• $options (array) – Options for sorting link.

Generates a sorting link. Sets named or querystring parameters for the sort and direction. Links will default to sorting by asc. After the first click, links generated with sort() will handle direction switching automatically. Link sorting default by ‘asc’. If the resultset is sorted ‘asc’ by the specified key the returned link will sort by ‘desc’.

Accepted keys for $options:

• escape Whether you want the contents HTML entity encoded, defaults to true.

• model The model to use, defaults to PaginatorHelper::defaultModel().

• direction The default direction to use when this link isn’t active.

• lock Lock direction. Will only use the default direction then, defaults to false.

  New in version 2.5: You can now set the lock option to true in order to lock the sorting direction into the specified direction.

Assuming you are paginating some posts, and are on page one:

echo $this->Paginator->sort('user_id');

Output:

<a href="/posts/index/page:1/sort:user_id/direction:asc/">User Id</a>

You can use the title parameter to create custom text for your link:

echo $this->Paginator->sort('user_id', 'User account');

Output:

<a href="/posts/index/page:1/sort:user_id/direction:asc/">User account</a>

If you are using HTML like images in your links remember to set escaping off:

echo $this->Paginator->sort(
  'user_id',
  '<em>User account</em>',
  array('escape' => false)
);

Output:

<a href="/posts/index/page:1/sort:user_id/direction:asc/">
  <em>User account</em>
</a>

The direction option can be used to set the default direction for a link. Once a link is active, it will automatically switch directions like normal:

echo $this->Paginator->sort('user_id', null, array('direction' => 'desc'));

Output:

<a href="/posts/index/page:1/sort:user_id/direction:desc/">User Id</a>

The lock option can be used to lock sorting into the specified direction:

echo $this->Paginator->sort('user_id', null, array('direction' => 'asc', 'lock' => true));

PaginatorHelper::sortDir(string $model = null, mixed $options = array())¶

Gets the current direction the recordset is sorted.

PaginatorHelper::sortKey(string $model = null, mixed $options = array())¶

Gets the current key by which the recordset is sorted.

Creating page number links¶

PaginatorHelper::numbers($options = array())¶

Returns a set of numbers for the paged result set. Uses a modulus to decide how many numbers to show on each side of the current page By default 8 links on either side of the current page will be created if those pages exist. Links will not be generated for pages that do not exist. The current page is also not a link.

Supported options are:

• before Content to be inserted before the numbers.

• after Content to be inserted after the numbers.

• model Model to create numbers for, defaults to PaginatorHelper::defaultModel().

• modulus how many numbers to include on either side of the current page, defaults to 8.

• separator Separator content defaults to `` | ``

• tag The tag to wrap links in, defaults to ‘span’.

• first Whether you want first links generated, set to an integer to define the number of ‘first’ links to generate. Defaults to false. If a string is set a link to the first page will be generated with the value as the title:

  echo $this->Paginator->numbers(array('first' => 'First page'));
  

• last Whether you want last links generated, set to an integer to define the number of ‘last’ links to generate. Defaults to false. Follows the same logic as the first option. There is a last()` method to be used separately as well if you wish.

• ellipsis Ellipsis content, defaults to ‘…’

• class The class name used on the wrapping tag.

• currentClass The class name to use on the current/active link. Defaults to current.

• currentTag Tag to use for current page number, defaults to null. This allows you to generate for example Twitter Bootstrap like links with the current page number wrapped in extra ‘a’ or ‘span’ tag.

While this method allows a lot of customization for its output. It is also ok to just call the method without any params.

echo $this->Paginator->numbers();

Using the first and last options you can create links to the beginning and end of the page set. The following would create a set of page links that include links to the first 2 and last 2 pages in the paged results:

echo $this->Paginator->numbers(array('first' => 2, 'last' => 2));

Creating jump links¶

In addition to generating links that go directly to specific page numbers, you’ll often want links that go to the previous and next links, first and last pages in the paged data set.

PaginatorHelper::prev($title = '<< Previous', $options = array(), $disabledTitle = null, $disabledOptions = array())¶

Parameters:

• $title (string) – Title for the link.

• $options (mixed) – Options for pagination link.

• $disabledTitle (string) – Title when the link is disabled, as when you’re already on the first page, no previous page to go.

• $disabledOptions (mixed) – Options for the disabled pagination link.

Generates a link to the previous page in a set of paged records.

$options and $disabledOptions supports the following keys:

• tag The tag wrapping tag you want to use, defaults to ‘span’. Set this to false to disable this option.

• escape Whether you want the contents HTML entity encoded, defaults to true.

• model The model to use, defaults to PaginatorHelper::defaultModel().

• disabledTag Tag to use instead of A tag when there is no previous page

A simple example would be:

echo $this->Paginator->prev(
  '<< ' . __('previous'),
  array(),
  null,
  array('class' => 'prev disabled')
);

If you were currently on the second page of posts, you would get the following:

<span class="prev">
  <a rel="prev" href="/posts/index/page:1/sort:title/order:desc">
    &lt;&lt; previous
  </a>
</span>

If there were no previous pages you would get:

<span class="prev disabled">&lt;&lt; previous</span>

You can change the wrapping tag using the tag option:

echo $this->Paginator->prev(__('previous'), array('tag' => 'li'));

Output:

<li class="prev">
  <a rel="prev" href="/posts/index/page:1/sort:title/order:desc">
    previous
  </a>
</li>

You can also disable the wrapping tag:

echo $this->Paginator->prev(__('previous'), array('tag' => false));

Output:

<a class="prev" rel="prev"
  href="/posts/index/page:1/sort:title/order:desc">
  previous
</a>

PaginatorHelper::next($title = 'Next >>', $options = array(), $disabledTitle = null, $disabledOptions = array())¶

This method is identical to prev() with a few exceptions. It creates links pointing to the next page instead of the previous one. It also uses next as the rel attribute value instead of prev

PaginatorHelper::first($first = '<< first', $options = array())¶

Returns a first or set of numbers for the first pages. If a string is given, then only a link to the first page with the provided text will be created:

echo $this->Paginator->first('< first');

The above creates a single link for the first page. Will output nothing if you are on the first page. You can also use an integer to indicate how many first paging links you want generated:

echo $this->Paginator->first(3);

The above will create links for the first 3 pages, once you get to the third or greater page. Prior to that nothing will be output.

The options parameter accepts the following:

• tag The tag wrapping tag you want to use, defaults to ‘span’

• after Content to insert after the link/tag

• model The model to use defaults to PaginatorHelper::defaultModel()

• separator Content between the generated links, defaults to ‘ | ‘

• ellipsis Content for ellipsis, defaults to ‘…’

PaginatorHelper::last($last = 'last >>', $options = array())¶

This method works very much like the first() method. It has a few differences though. It will not generate any links if you are on the last page for a string values of $last. For an integer value of $last no links will be generated once the user is inside the range of last pages.

PaginatorHelper::current(string $model = null)¶

Gets the current page of the recordset for the given model:

// Our URL is: http://example.com/comments/view/page:3
echo $this->Paginator->current('Comment');
// Output is 3

PaginatorHelper::hasNext(string $model = null)¶

Returns true if the given result set is not at the last page.

PaginatorHelper::hasPrev(string $model = null)¶

Returns true if the given result set is not at the first page.

PaginatorHelper::hasPage(string $model = null, integer $page = 1)¶

Returns true if the given result set has the page number given by $page.

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().

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

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

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¶

PaginatorHelper::link($title, $url = array(), $options = array())¶

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
*/

PaginatorHelper::meta(array $options = array())¶

Outputs the meta-links for a paginated result set:

echo $this->Paginator->meta(); // Example output for page 5
/*
<link href="/?page=4" rel="prev" /><link href="/?page=6" rel="next" />
*/

You can also append the output of the meta function to the named block:

$this->Paginator->meta(array('block' => true));

If true is passed, the “meta” block is used.