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
- Cake\View\Helper\PaginatorHelper uses Cake\View\StringTemplateTrait
Link: https://book.cakephp.org/3.0/en/views/helpers/paginator.html
Location: View/Helper/PaginatorHelper.php
Properties summary
-
$_defaultConfig
protectedarray
Default config for this class -
$_defaultModel
protectedstring
Default model of the paged sets -
$helpers
publicarray
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. -
_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. -
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. -
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. -
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. -
last() public
Returns a last or set of numbers for the last pages. -
limitControl() public
Dropdown select for pagination limit. This will generate a wrapping form.
-
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() 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
_firstNumber() protected ¶
_firstNumber( string $ellipsis , array $params , integer $start , array $options )
Generates the first number for the paginator numbers() method.
Parameters
- string $ellipsis
- Ellipsis character.
- array $params
- Params from the numbers() method.
- integer $start
- Start number.
- array $options
- Options from the numbers() method.
Returns
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
_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
An array with the start and end numbers.
_hasPage() 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
Whether model has $page
_lastNumber() protected ¶
_lastNumber( string $ellipsis , array $params , integer $end , array $options )
Generates the last number for the paginator numbers() method.
Parameters
- string $ellipsis
- Ellipsis character.
- array $params
- Params from the numbers() method.
- integer $end
- End number.
- array $options
- Options from the numbers() method.
Returns
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
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
Markup output.
_removeAlias() protected ¶
_removeAlias( string $field , string|null $model null )
Remove alias if needed.
Parameters
- string $field
- Current field
- string|null $model optional null
- Current model alias
Returns
Unaliased field if applicable
_toggledLink() protected ¶
_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
Generated HTML
counter() 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
Counter string.
Link
current() 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
The current page number of the recordset.
Link
defaultModel() 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
Model name or null if the pagination isn't initialized.
first() 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
Numbers string.
Link
generateUrl() public ¶
generateUrl( array $options [] , string|null $model null , 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/URL options array
- string|null $model optional null
- Which model to paginate on
- array $urlOptions optional []
Array of options The bool version of this argument is deprecated and will be removed in 4.0.0
Returns
By default, returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript)
Link
generateUrlParams() 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
An array of URL parameters
hasNext() 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
True if the result set is not at the last page.
Link
hasPage() 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
True if the given result set has the specified page number.
Link
hasPrev() 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
True if the result set is not at the first page.
Link
last() 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
Numbers string.
Link
limitControl() public ¶
limitControl( array $limits [] , integer|null $default null , array $options [] )
Dropdown select for pagination limit. This will generate a wrapping form.
Parameters
- array $limits optional []
- The options array.
- integer|null $default optional null
- Default option for pagination limit. Defaults to
$this->param('perPage')
. - array $options optional []
- Options for Select tag attributes like class, id or event
Returns
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 stringprev
(default True) True to generate meta for previous pagenext
(default True) True to generate meta for next pagefirst
(default False) True to generate meta for first pagelast
(default False) True to generate meta for last page
Parameters
- array $options optional []
- Array of options
Returns
Meta links
next() 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 truemodel
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
A "next" link or $disabledTitle text if the link is disabled.
Link
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 tofalse
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
Numbers string.
Link
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|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
Content of the requested param.
params() 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
The array of paging parameters for the paginated resultset.
prev() 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 truemodel
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
A "previous" link or a disabled link.
Link
sort() 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
A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified key the returned link will sort by 'desc'.
Link
sortDir() 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
The direction by which the recordset is being sorted, or null if the results are not currently sorted.
Link
sortKey() 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
The name of the key by which the recordset is being sorted, or null if the results are not currently sorted.
Link
Methods inherited from Cake\View\Helper
__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.
__debugInfo() public ¶
__debugInfo( )
Returns an array that can be used to describe the internal state of this object.
Returns
__get() public ¶
__get( string $name )
Lazy loads helpers.
Parameters
- string $name
- Name of the property being accessed.
Returns
__set() public ¶
__set( string $name , mixed $value )
Magic setter for removed properties.
Parameters
- string $name
- Property name.
- mixed $value
- Value to set.
_cleanConfirmMessage() protected ¶
_cleanConfirmMessage( string $message )
Returns a string read to be used in confirm()
Parameters
- string $message
- The message to clean
Returns
_confirm() 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
onclick JS code
addClass() 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 of options with $key set.
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.
Methods used from Cake\View\StringTemplateTrait
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
getTemplates() 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
setTemplates() public ¶
setTemplates( array $templates )
Sets templates to use.
Parameters
- array $templates
- Templates to be added.
Returns
$this
templates() public ¶
templates( string|null|array $templates null )
Gets/sets templates to use.
Deprecated
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() protected ¶
_configDelete( string $key )
Deletes a single config key.
Parameters
- string $key
- Key to delete.
Throws
_configRead() protected ¶
_configRead( string|null $key )
Reads a config key.
Parameters
- string|null $key
- Key to read.
Returns
_configWrite() 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
config() 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
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
Config value being read, or the object itself on write operations.
Throws
configShallow() 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->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 null
- The value to set.
Returns
$this
getConfig() public ¶
getConfig( string|null $key null , mixed $default 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');
Reading with default value:
$this->getConfig('some-key', 'default-value');
Parameters
- string|null $key optional null
- The key to get or null for the whole config.
- mixed $default optional null
- The return value when the key does not exist.
Returns
Config value being read.
setConfig() 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
Properties detail
$_defaultConfig ¶
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">…</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>', ] ]