W3cubDocs

/CakePHP 3.4

Class PaginatorHelper

Pagination Helper class for easy generation of pagination links.

PaginationHelper encloses all methods needed when working with pagination.

Cake\View\Helper implements Cake\Event\EventListenerInterface uses Cake\Core\InstanceConfigTrait
Extended by Cake\View\Helper\PaginatorHelper uses Cake\View\StringTemplateTrait

Properties summary

  • $_defaultConfig protected
    array
    Default config for this class
  • $_defaultModel protected
    string
    Default model of the paged sets
  • $helpers public
    array
    List of helpers used by this helper

Magic properties summary

Inherited Properties

Method Summary

  • __construct() public
    Constructor. Overridden to merge passed args with URL options.
  • _firstNumber() protected
    Generates the first number for the paginator numbers() method.
  • _formatNumber() protected
    Formats a number for the paginator number output.
  • 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.
  • _toggledLink() protected
    Generate an active/inactive link for next/prev methods.
  • counter() public
    Returns a counter string for the paged result set
  • current() public
    Gets the current page of the recordset for the given model
  • Gets or sets the default model of the paged sets
  • first() public
    Returns a first or set of numbers for the first pages.
  • generateUrl() public
    Merges passed URL options with current pagination state to generate a pagination URL.
  • Merges passed URL options with current pagination state to generate a pagination URL.
  • 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
  • Event listeners.
  • last() public
    Returns a last or set of numbers for the last pages.
  • 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
  • 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
  • total() public
    Gets the total number of pages in the recordset for the given model.

Method Detail

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

Overrides

Cake\View\Helper::__construct()

_firstNumber()source protected

_firstNumber( Cake\View\StringTemplate $ellipsis , array $params , integer $start , array $options )

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

Parameters

Cake\View\StringTemplate $ellipsis
StringTemplate instance.
array $params
Params from the numbers() method.
integer $start
Start number.
array $options
Options from the numbers() method.

Returns

string
Markup output.

_formatNumber()source 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()source 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()source protected

_hasPage( string $model , integer $page )

Does $model have $page in its range?

Parameters

string $model
Model name to get parameters for.
integer $page
Page number you are checking.

Returns

boolean
Whether model has $page

_lastNumber()source protected

_lastNumber( Cake\View\StringTemplate $ellipsis , array $params , integer $end , array $options )

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

Parameters

Cake\View\StringTemplate $ellipsis
StringTemplate instance.
array $params
Params from the numbers() method.
integer $end
End number.
array $options
Options from the numbers() method.

Returns

string
Markup output.

_modulusNumbers()source 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()source 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.
_toggledLink( string|boolean $text , boolean $enabled , array $options , array $templates )

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

Parameters

string|boolean $text
The enabled text for the link.
boolean $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

counter()source public

counter( string|array $options [] )

Returns a counter string for the paged result set

Options

  • model The model to use, defaults to PaginatorHelper::defaultModel();
  • format 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.

Parameters

string|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.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-a-page-counter

current()source public

current( string|null $model null )

Gets the current page of the recordset for the given model

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

integer
The current page number of the recordset.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#checking-the-pagination-state

defaultModel()source public

defaultModel( string|null $model null )

Gets or sets the default model of the paged sets

Parameters

string|null $model optional null
Model name to set

Returns

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

first()source public

first( string|integer $first '<< 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|integer $first optional '<< first'

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|false
Numbers string.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-jump-links

generateUrl()source public

generateUrl( array $options [] , string|null $model null , array|boolean $urlOptions false )

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/URL options array
string|null $model optional null
Which model to paginate on
array|boolean $urlOptions optional false
Array of options or bool fullBase for BC reasons.

Returns

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

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#generating-pagination-urls

generateUrlParams()source public

generateUrlParams( array $options [] , string|null $model null )

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 null
Which model to paginate on

Returns

array
An array of URL parameters

hasNext()source public

hasNext( string|null $model null )

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

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

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

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#checking-the-pagination-state

hasPage()source public

hasPage( string|null $model null , integer $page 1 )

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

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.
integer $page optional 1
The page number - if not set defaults to 1.

Returns

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

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#checking-the-pagination-state

hasPrev()source public

hasPrev( string|null $model null )

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

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

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

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#checking-the-pagination-state

implementedEvents()source public

implementedEvents( )

Event listeners.

Returns

array

Overrides

Cake\View\Helper::implementedEvents()

last()source public

last( string|integer $last '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|integer $last optional 'last >>'
if string use as label for the link, if numeric print page numbers
array $options optional []
Array of options

Returns

string|false
Numbers string.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-jump-links

meta()source 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()source public

next( string $title 'Next >>' , 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 'Next >>'
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.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-jump-links

numbers()source 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|false
Numbers string.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-page-number-links

options()source 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()source public

param( string $key , string|null $model null )

Convenience access to any of the paginator params.

Parameters

string $key
Key of the paginator params array to retrieve.
string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

mixed
Content of the requested param.

params()source public

params( string|null $model null )

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

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

array
The array of paging parameters for the paginated resultset.

prev()source public

prev( string $title '<< Previous' , 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 '<< Previous'
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.

Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-jump-links

sort()source public

sort( string $key , string|null $title null , 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|null $title optional null

Title for the link. If $title is null $key will be used for the title and will be generated by inflection.

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'.


Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-sort-links

sortDir()source public

sortDir( string|null $model null , array $options [] )

Gets the current direction the recordset is sorted

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.
array $options optional []
Options for pagination links. See #options for list of keys.

Returns

string

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


Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-sort-links

sortKey()source public

sortKey( string|null $model null , array $options [] )

Gets the current key by which the recordset is sorted

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.
array $options optional []
Options for pagination links. See #options for list of keys.

Returns

string|null

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


Link

http://book.cakephp.org/3.0/en/views/helpers/paginator.html#creating-sort-links

total()source public

total( string|null $model null )

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

Parameters

string|null $model optional null
Optional model name. Uses the default if none is specified.

Returns

integer
The total pages for the recordset.

Methods inherited from Cake\View\Helper

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

__debugInfo()source public

__debugInfo( )

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

Returns

array

__get()source public

__get( string $name )

Lazy loads helpers.

Parameters

string $name
Name of the property being accessed.

Returns

Cake\View\Helper|null
Helper instance if helper with provided name exists

_confirm()source protected

_confirm( string $message , string $okCode , string $cancelCode '' , array $options [] )

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

Parameters

string $message
Message to be displayed
string $okCode
Code to be executed after user chose 'OK'
string $cancelCode optional ''
Code to be executed after user chose 'Cancel'
array $options optional []
Array of options

Returns

string
onclick JS code

addClass()source public

addClass( array $options [] , string|null $class null , string $key 'class' )

Adds the given class to the element options

Parameters

array $options optional []
Array options/attributes to add a class to
string|null $class optional null
The class name being added.
string $key optional 'class'
the key to use for class.

Returns

array
Array of options with $key set.

getView()source public

getView( )

Get the view instance this helper is bound to.

Returns

Cake\View\View
The bound view instance.

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

Methods used from Cake\View\StringTemplateTrait

formatTemplate()source 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

getTemplates()source public

getTemplates( string|null $template null )

Gets templates to use or a specific template.

Parameters

string|null $template optional null
String for reading a specific template, null for all.

Returns

string|array

setTemplates()source public

setTemplates( array $templates )

Sets templates to use.

Parameters

array $templates
Templates to be added.

Returns


$this

templater()source public

templater( )

Returns the templater instance.

Returns

Cake\View\StringTemplate

templates()source public

templates( string|null|array $templates null )

Gets/sets templates to use.

Deprecated

3.4.0 Use setTemplates()/getTemplates() instead.

Parameters

string|null|array $templates optional null

null or string allow reading templates. An array allows templates to be added.

Returns


$this|string|array

Methods used from Cake\Core\InstanceConfigTrait

_configDelete()source 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()source protected

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key
Key to read.

Returns

mixed

_configWrite()source protected

_configWrite( string|array $key , mixed $value , boolean|string $merge false )

Writes a config key.

Parameters

string|array $key
Key to write to.
mixed $value
Value to write.
boolean|string $merge optional false

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

config()source public

config( string|array|null $key null , mixed|null $value null , boolean $merge true )

Gets/Sets the config.

Usage

Reading the whole config:

$this->config();

Reading a specific value:

$this->config('key');

Reading a nested value:

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

Setting a specific value:

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

Setting a nested value:

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

Updating multiple config settings at the same time:

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

Deprecated

3.4.0 use setConfig()/getConfig() instead.

Parameters

string|array|null $key optional null
The key to get/set, or a complete array of configs.
mixed|null $value optional null
The value to set.
boolean $merge optional true
Whether to recursively merge or overwrite existing config, defaults to true.

Returns

mixed
Config value being read, or the object itself on write operations.

Throws

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

configShallow()source public

configShallow( string|array $key , mixed|null $value null )

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->config('key', $value);

Setting a nested value:

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

Updating multiple config settings at the same time:

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

Parameters

string|array $key
The key to set, or a complete array of configs.
mixed|null $value optional null
The value to set.

Returns


$this

getConfig()source public

getConfig( string|null $key null )

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');

Parameters

string|null $key optional null
The key to get or null for the whole config.

Returns

mixed
Config value being read.

setConfig()source public

setConfig( string|array $key , mixed|null $value null , boolean $merge true )

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 null
The value to set.
boolean $merge optional true
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.

Properties detail

$_defaultConfigsource

protected array

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

Templates: the templates used by this class

[
    'options' => [],
    'templates' => [
        'nextActive' => '<li class="next"><a rel="next" href="{{url}}">{{text}}</a></li>',
        'nextDisabled' => '<li class="next disabled"><a href="" onclick="return false;">{{text}}</a></li>',
        'prevActive' => '<li class="prev"><a rel="prev" href="{{url}}">{{text}}</a></li>',
        'prevDisabled' => '<li class="prev disabled"><a href="" onclick="return false;">{{text}}</a></li>',
        'counterRange' => '{{start}} - {{end}} of {{count}}',
        'counterPages' => '{{page}} of {{pages}}',
        'first' => '<li class="first"><a href="{{url}}">{{text}}</a></li>',
        'last' => '<li class="last"><a href="{{url}}">{{text}}</a></li>',
        'number' => '<li><a href="{{url}}">{{text}}</a></li>',
        'current' => '<li class="active"><a href="">{{text}}</a></li>',
        'ellipsis' => '<li class="ellipsis">&hellip;</li>',
        'sort' => '<a href="{{url}}">{{text}}</a>',
        'sortAsc' => '<a class="asc" href="{{url}}">{{text}}</a>',
        'sortDesc' => '<a class="desc" href="{{url}}">{{text}}</a>',
        'sortAscLocked' => '<a class="asc locked" href="{{url}}">{{text}}</a>',
        'sortDescLocked' => '<a class="desc locked" href="{{url}}">{{text}}</a>',
    ]
]

$_defaultModelsource

protected string

Default model of the paged sets

$helperssource

public array

List of helpers used by this helper

['Url', 'Number', 'Html']

Magic properties detail

© 2005–2017 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/3.4/class-Cake.View.Helper.PaginatorHelper.html