Class PaginatorHelper

Pagination Helper class for easy generation of pagination links.

PaginationHelper encloses all methods needed when working with pagination.

Namespace: Cake\View\Helper

Properties summary

  • $Form public
    \Cake\View\Helper\FormHelper
  • $Html public
    \Cake\View\Helper\HtmlHelper
  • $Number public
    \Cake\View\Helper\NumberHelper
  • $Url public
    \Cake\View\Helper\UrlHelper
  • $_View protected
    \Cake\View\View

    The View instance this helper is attached to

  • $_config protected
    array

    Runtime config

  • bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Default config for this class

  • $_defaultModel protected
    string|null

    Default model of the paged sets

  • $_helperMap protected
    array

    A helper lookup table used to lazy load helper objects.

  • $_templater protected
    \Cake\View\StringTemplate

    StringTemplate instance.

  • $helpers public
    array

    List of helpers used by this helper

Method Summary

  • __call() public

    Provide non fatal errors on missing method calls.

  • __construct() public

    Constructor. Overridden to merge passed args with URL options.

  • __debugInfo() public

    Returns an array that can be used to describe the internal state of this object.

  • __get() public

    Lazy loads helpers.

  • _configDelete() protected

    Deletes a single config key.

  • _configRead() protected

    Reads a config key.

  • _configWrite() protected

    Writes a config key.

  • _confirm() protected

    Returns a string to be used as onclick handler for confirm dialogs.

  • _firstNumber() protected

    Generates the first number for the paginator numbers() method.

  • _formatNumber() protected

    Formats a number for the paginator number output.

  • _getNumbersStartAndEnd() protected

    Calculates the start and end for the pagination numbers.

  • _hasPage() protected

    Does $model have $page in its range?

  • _lastNumber() protected

    Generates the last number for the paginator numbers() method.

  • _modulusNumbers() protected

    Generates the numbers for the paginator numbers() method.

  • _numbers() protected

    Generates the numbers for the paginator numbers() method.

  • _removeAlias() protected

    Remove alias if needed.

  • _toggledLink() protected

    Generate an active/inactive link for next/prev methods.

  • addClass() public

    Adds the given class to the element options

  • configShallow() public

    Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

  • counter() public

    Returns a counter string for the paged result set.

  • current() public

    Gets the current page of the recordset for the given model

  • defaultModel() public

    Gets or sets the default model of the paged sets

  • first() public

    Returns a first or set of numbers for the first pages.

  • formatTemplate() public

    Formats a template string with $data

  • generateUrl() public

    Merges passed URL options with current pagination state to generate a pagination URL.

  • generateUrlParams() public

    Merges passed URL options with current pagination state to generate a pagination URL.

  • getConfig() public

    Returns the config.

  • getConfigOrFail() public

    Returns the config for this specific key.

  • getTemplates() public

    Gets templates to use or a specific template.

  • getView() public

    Get the view instance this helper is bound to.

  • hasNext() public

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

  • hasPage() public

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

  • hasPrev() public

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

  • implementedEvents() public

    Event listeners.

  • initialize() public

    Constructor hook method.

  • last() public

    Returns a last or set of numbers for the last pages.

  • limitControl() public

    Dropdown select for pagination limit.

  • meta() public

    Returns the meta-links for a paginated result set.

  • next() public

    Generates a "next" link for a set of paged records

  • numbers() public

    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 (default: 8).

  • options() public

    Sets default options for all pagination links

  • param() public

    Convenience access to any of the paginator params.

  • params() public

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

  • prev() public

    Generates a "previous" link for a set of paged records

  • setConfig() public

    Sets the config.

  • setTemplates() public

    Sets templates to use.

  • sort() public

    Generates a sorting link. Sets named parameters for the sort and direction. Handles direction switching automatically.

  • sortDir() public

    Gets the current direction the recordset is sorted

  • sortKey() public

    Gets the current key by which the recordset is sorted

  • templater() public

    Returns the templater instance.

  • total() public

    Gets the total number of pages in the recordset for the given model.

Method Detail

__call() public

__call(string $method, array $params)

Provide non fatal errors on missing method calls.

Parameters

string $method

Method to invoke

array $params

Array of params for the method.

Returns

mixed|void

__construct() public

__construct(\Cake\View\View $view, array $config)

Constructor. Overridden to merge passed args with URL options.

Parameters

\Cake\View\View $view

The View this helper is being attached to.

array $config optional

Configuration settings for the helper.

__debugInfo() public

__debugInfo()

Returns an array that can be used to describe the internal state of this object.

Returns

array

__get() public

__get(string $name)

Lazy loads helpers.

Parameters

string $name

Name of the property being accessed.

Returns

\Cake\View\Helper|null|void

Helper instance if helper with provided name exists

_configDelete() protected

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_confirm() protected

_confirm(string $okCode, string $cancelCode)

Returns a string to be used as onclick handler for confirm dialogs.

Parameters

string $okCode

Code to be executed after user chose 'OK'

string $cancelCode

Code to be executed after user chose 'Cancel'

Returns

string

"onclick" JS code

_firstNumber() protected

_firstNumber(string $ellipsis, array $params, int $start, array $options)

Generates the first number for the paginator numbers() method.

Parameters

string $ellipsis

Ellipsis character.

array $params

Params from the numbers() method.

int $start

Start number.

array $options

Options from the numbers() method.

Returns

string

Markup output.

_formatNumber() protected

_formatNumber(\Cake\View\StringTemplate $templater, array $options)

Formats a number for the paginator number output.

Parameters

\Cake\View\StringTemplate $templater

StringTemplate instance.

array $options

Options from the numbers() method.

Returns

string

_getNumbersStartAndEnd() protected

_getNumbersStartAndEnd(array $params, array $options)

Calculates the start and end for the pagination numbers.

Parameters

array $params

Params from the numbers() method.

array $options

Options from the numbers() method.

Returns

array

An array with the start and end numbers.

_hasPage() protected

_hasPage(?string $model, string $dir)

Does $model have $page in its range?

Parameters

string|null $model

Model name to get parameters for.

string $dir

Direction

Returns

bool

Whether model has $dir

_lastNumber() protected

_lastNumber(string $ellipsis, array $params, int $end, array $options)

Generates the last number for the paginator numbers() method.

Parameters

string $ellipsis

Ellipsis character.

array $params

Params from the numbers() method.

int $end

End number.

array $options

Options from the numbers() method.

Returns

string

Markup output.

_modulusNumbers() protected

_modulusNumbers(\Cake\View\StringTemplate $templater, array $params, array $options)

Generates the numbers for the paginator numbers() method.

Parameters

\Cake\View\StringTemplate $templater

StringTemplate instance.

array $params

Params from the numbers() method.

array $options

Options from the numbers() method.

Returns

string

Markup output.

_numbers() protected

_numbers(\Cake\View\StringTemplate $templater, array $params, array $options)

Generates the numbers for the paginator numbers() method.

Parameters

\Cake\View\StringTemplate $templater

StringTemplate instance.

array $params

Params from the numbers() method.

array $options

Options from the numbers() method.

Returns

string

Markup output.

_removeAlias() protected

_removeAlias(string $field, ?string $model)

Remove alias if needed.

Parameters

string $field

Current field

string|null $model optional

Current model alias

Returns

string

Unaliased field if applicable

_toggledLink(mixed $text, mixed $enabled, mixed $options, mixed $templates)

Generate an active/inactive link for next/prev methods.

Parameters

string|false $text

The enabled text for the link.

bool $enabled

Whether or not the enabled/disabled version should be created.

array $options

An array of options from the calling method.

array $templates

An array of templates with the 'active' and 'disabled' keys.

Returns

string

Generated HTML

addClass() public

addClass(array $options, string $class, string $key)

Adds the given class to the element options

Parameters

array $options

Array options/attributes to add a class to

string $class

The class name being added.

string $key optional

the key to use for class. Defaults to 'class'.

Returns

array

Array of options with $key set.

configShallow() public

configShallow(mixed $key, mixed $value)

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns

$this

counter() public

counter(string $format, array $options)

Returns a counter string for the paged result set.

Options

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

Parameters

string $format optional

The format string you want to use, defaults to 'pages' Which generates output like '1 of 5' set to 'range' to generate output like '1 - 3 of 13'. Can also be set to a custom string, containing the following placeholders {{page}}, {{pages}}, {{current}}, {{count}}, {{model}}, {{start}}, {{end}} and any custom content you would like.

array $options optional

Options for the counter string. See #options for list of keys. If string it will be used as format.

Returns

string

Counter string.

Links

current() public

current(?string $model)

Gets the current page of the recordset for the given model

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

int

The current page number of the recordset.

Links

defaultModel() public

defaultModel(?string $model)

Gets or sets the default model of the paged sets

Parameters

string|null $model optional

Model name to set

Returns

string|null

Model name or null if the pagination isn't initialized.

first() public

first(mixed $first, array $options)

Returns a first or set of numbers for the first pages.

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

Creates a single link for the first page. Will output nothing if you are on the first page.

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

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

Options:

  • model The model to use defaults to PaginatorHelper::defaultModel()
  • escape Whether or not to HTML escape the text.
  • url An array of additional URL options to use for link generation.

Parameters

string|int $first optional

if string use as label for the link. If numeric, the number of page links you want at the beginning of the range.

array $options optional

An array of options.

Returns

string

Numbers string.

Links

formatTemplate() public

formatTemplate(string $name, array $data)

Formats a template string with $data

Parameters

string $name

The template name.

array $data

The data to insert.

Returns

string

generateUrl() public

generateUrl(array $options, ?string $model, array $url, array $urlOptions)

Merges passed URL options with current pagination state to generate a pagination URL.

Url options:

  • escape: If false, the URL will be returned unescaped, do only use if it is manually escaped afterwards before being displayed.
  • fullBase: If true, the full base URL will be prepended to the result

Parameters

array $options optional

Pagination options.

string|null $model optional

Which model to paginate on

array $url optional

URL.

array $urlOptions optional

Array of options

Returns

string

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

Links

generateUrlParams() public

generateUrlParams(array $options, ?string $model, array $url)

Merges passed URL options with current pagination state to generate a pagination URL.

Parameters

array $options optional

Pagination/URL options array

string|null $model optional

Which model to paginate on

array $url optional

URL.

Returns

array

An array of URL parameters

getConfig() public

getConfig(?string $key, mixed $default)

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional

The key to get or null for the whole config.

mixed $default optional

The return value when the key does not exist.

Returns

mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public

getConfigOrFail(string $key)

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key

The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getTemplates() public

getTemplates(?string $template)

Gets templates to use or a specific template.

Parameters

string|null $template optional

String for reading a specific template, null for all.

Returns

string|array

getView() public

getView()

Get the view instance this helper is bound to.

Returns

\Cake\View\View

The bound view instance.

hasNext() public

hasNext(?string $model)

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

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

bool

True if the result set is not at the last page.

Links

hasPage() public

hasPage(int $page, ?string $model)

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

Parameters

int $page optional

The page number - if not set defaults to 1.

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

bool

True if the given result set has the specified page number.

Throws

InvalidArgumentException

Links

hasPrev() public

hasPrev(?string $model)

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

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

bool

True if the result set is not at the first page.

Links

implementedEvents() public

implementedEvents()

Event listeners.

Returns

array

initialize() public

initialize(array $config)

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array $config

The configuration settings provided to this helper.

last() public

last(mixed $last, array $options)

Returns a last or set of numbers for the last pages.

echo $this->Paginator->last('last >');

Creates a single link for the last page. Will output nothing if you are on the last page.

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

Will create links for the last 3 pages. Once you enter the page range, no output will be created.

Options:

  • model The model to use defaults to PaginatorHelper::defaultModel()
  • escape Whether or not to HTML escape the text.
  • url An array of additional URL options to use for link generation.

Parameters

string|int $last optional

if string use as label for the link, if numeric print page numbers

array $options optional

Array of options

Returns

string

Numbers string.

Links

limitControl() public

limitControl(array $limits, ?int $default, array $options)

Dropdown select for pagination limit.

This will generate a wrapping form.

Parameters

array $limits optional

The options array.

int|null $default optional

Default option for pagination limit. Defaults to $this->param('perPage').

array $options optional

Options for Select tag attributes like class, id or event

Returns

string

html output.

meta() public

meta(array $options)

Returns the meta-links for a paginated result set.

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

Echos the links directly, will output nothing if there is neither a previous nor next page.

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

Will append the output of the meta function to the named block - if true is passed the "meta" block is used.

Options:

  • model The model to use defaults to PaginatorHelper::defaultModel()
  • block The block name to append the output to, or false/absent to return as a string
  • prev (default True) True to generate meta for previous page
  • next (default True) True to generate meta for next page
  • first (default False) True to generate meta for first page
  • last (default False) True to generate meta for last page

Parameters

array $options optional

Array of options

Returns

string|null

Meta links

next() public

next(string $title, array $options)

Generates a "next" link for a set of paged records

Options:

  • disabledTitle The text to used when the link is disabled. This defaults to the same text at the active link. Setting to false will cause this method to return ''.
  • escape Whether you want the contents html entity encoded, defaults to true
  • model The model to use, defaults to PaginatorHelper::defaultModel()
  • url An array of additional URL options to use for link generation.
  • templates An array of templates, or template file name containing the templates you'd like to use when generating the link for next page. The helper's original templates will be restored once next() is done.

Parameters

string $title optional

Title for the link. Defaults to 'Next >>'.

array $options optional

Options for pagination link. See above for list of keys.

Returns

string

A "next" link or $disabledTitle text if the link is disabled.

Links

numbers() public

numbers(array $options)

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 (default: 8).

$this->Paginator->numbers(['first' => 2, 'last' => 2]);

Using the first and last options you can create links to the beginning and end of the page set.

Options

  • before Content to be inserted before the numbers, but after the first links.
  • after Content to be inserted after the numbers, but before the last links.
  • 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. Set to false to disable and to show all numbers.
  • first Whether you want first links generated, set to an integer to define the number of 'first' links to generate. If a string is set a link to the first page will be generated with the value as the title.
  • last Whether you want last links generated, set to an integer to define the number of 'last' links to generate. If a string is set a link to the last page will be generated with the value as the title.
  • templates An array of templates, or template file name containing the templates you'd like to use when generating the numbers. The helper's original templates will be restored once numbers() is done.
  • url An array of additional URL options to use for link generation.

The generated number links will include the 'ellipsis' template when the first and last options and the number of pages exceed the modulus. For example if you have 25 pages, and use the first/last options and a modulus of 8, ellipsis content will be inserted after the first and last link sets.

Parameters

array $options optional

Options for the numbers.

Returns

string

Numbers string.

Links

options() public

options(array $options)

Sets default options for all pagination links

Parameters

array $options optional

Default options for pagination links. See PaginatorHelper::$options for list of keys.

param() public

param(string $key, ?string $model)

Convenience access to any of the paginator params.

Parameters

string $key

Key of the paginator params array to retrieve.

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

mixed

Content of the requested param.

params() public

params(?string $model)

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

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

array

The array of paging parameters for the paginated resultset.

prev() public

prev(string $title, array $options)

Generates a "previous" link for a set of paged records

Options:

  • disabledTitle The text to used when the link is disabled. This defaults to the same text at the active link. Setting to false will cause this method to return ''.
  • escape Whether you want the contents html entity encoded, defaults to true
  • model The model to use, defaults to PaginatorHelper::defaultModel()
  • url An array of additional URL options to use for link generation.
  • templates An array of templates, or template file name containing the templates you'd like to use when generating the link for previous page. The helper's original templates will be restored once prev() is done.

Parameters

string $title optional

Title for the link. Defaults to '<< Previous'.

array $options optional

Options for pagination link. See above for list of keys.

Returns

string

A "previous" link or a disabled link.

Links

setConfig() public

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

setTemplates() public

setTemplates(array $templates)

Sets templates to use.

Parameters

string[] $templates

Templates to be added.

Returns

$this

sort() public

sort(string $key, mixed $title, array $options)

Generates a sorting link. Sets named parameters for the sort and direction. Handles direction switching automatically.

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.

Parameters

string $key

The name of the key that the recordset should be sorted.

string|array|null $title optional

Title for the link. If $title is null $key will be used for the title and will be generated by inflection. It can also be an array with keys asc and desc for specifying separate titles based on the direction.

array $options optional

Options for sorting link. See above for list of keys.

Returns

string

A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified key the returned link will sort by 'desc'.

Links

sortDir() public

sortDir(?string $model, array $options)

Gets the current direction the recordset is sorted

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

array $options optional

Options for pagination links.

Returns

string

The direction by which the recordset is being sorted, or null if the results are not currently sorted.

Links

sortKey() public

sortKey(?string $model, array $options)

Gets the current key by which the recordset is sorted

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

array $options optional

Options for pagination links.

Returns

string|null

The name of the key by which the recordset is being sorted, or null if the results are not currently sorted.

Links

templater() public

templater()

Returns the templater instance.

Returns

\Cake\View\StringTemplate

total() public

total(?string $model)

Gets the total number of pages in the recordset for the given model.

Parameters

string|null $model optional

Optional model name. Uses the default if none is specified.

Returns

int

The total pages for the recordset.

Property Detail

$Form public

Type

\Cake\View\Helper\FormHelper

$Html public

Type

\Cake\View\Helper\HtmlHelper

$Number public

Type

\Cake\View\Helper\NumberHelper

$Url public

Type

\Cake\View\Helper\UrlHelper

$_View protected

The View instance this helper is attached to

Type

\Cake\View\View

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Default config for this class

Options: Holds the default options for pagination links

The values that may be specified are:

  • url Url of the action. See Router::url()
  • url['?']['sort'] the key that the recordset is sorted.
  • url['?']['direction'] Direction of the sorting (default: 'asc').
  • url['?']['page'] Page number to use in links.
  • model The name of the model.
  • escape Defines if the title field for the link should be escaped (default: true).
  • routePlaceholders An array specifying which paging params should be passed as route placeholders instead of query string parameters. The array can have values 'sort', 'direction', 'page'.

Templates: the templates used by this class

Type

array

$_defaultModel protected

Default model of the paged sets

Type

string|null

$_helperMap protected

A helper lookup table used to lazy load helper objects.

Type

array

$_templater protected

StringTemplate instance.

Type

\Cake\View\StringTemplate

$helpers public

List of helpers used by this helper

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.View.Helper.PaginatorHelper.html