Skip to content
Permalink
Browse files

Updating doc blocks for paginator helper.

  • Loading branch information...
markstory committed Nov 3, 2009
1 parent 9d2628f commit 6b043c6c57da5d2d3f0538170e8aa964b2789039
Showing with 103 additions and 43 deletions.
  1. +103 −43 cake/libs/view/helpers/paginator.php
@@ -48,28 +48,28 @@ class PaginatorHelper extends AppHelper {
*
* The values that may be specified are:
*
* - <i>$options['format']</i> Format of the counter. Supported formats are 'range' and 'pages'
* and custom (default). In the default mode the supplied string is parsed and constants are replaced
* by their actual values.
* Constants: %page%, %pages%, %current%, %count%, %start%, %end% .
* - <i>$options['separator']</i> The separator of the actual page and number of pages (default: ' of ').
* - <i>$options['url']</i> Url of the action. See Router::url()
* - <i>$options['url']['sort']</i> the key that the recordset is sorted.
* - <i>$options['url']['direction']</i> Direction of the sorting (default: 'asc').
* - <i>$options['url']['page']</i> Page # to display.
* - <i>$options['model']</i> The name of the model.
* - <i>$options['escape']</i> Defines if the title field for the link should be escaped (default: true).
* - <i>$options['update']</i> DOM id of the element updated with the results of the AJAX call.
* If this key isn't specified Paginator will use plain HTML links.
* - <i>$options['indicator']</i> DOM id of the element that will be shown when doing AJAX requests.
* - `$options['format']` Format of the counter. Supported formats are 'range' and 'pages'
* and custom (default). In the default mode the supplied string is parsed and constants are replaced
* by their actual values.
* Constants: %page%, %pages%, %current%, %count%, %start%, %end% .
* - `$options['separator']` The separator of the actual page and number of pages (default: ' of ').
* - `$options['url']` Url of the action. See Router::url()
* - `$options['url']['sort']` the key that the recordset is sorted.
* - `$options['url']['direction']` Direction of the sorting (default: 'asc').
* - `$options['url']['page']` Page # to display.
* - `$options['model']` The name of the model.
* - `$options['escape']` Defines if the title field for the link should be escaped (default: true).
* - `$options['update']` DOM id of the element updated with the results of the AJAX call.
* If this key isn't specified Paginator will use plain HTML links.
* - `$options['indicator']` DOM id of the element that will be shown when doing AJAX requests.
*
* @var array
*/
var $options = array();
/**
* Gets the current paging parameters from the resultset for the given model
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param string $model Optional model name. Uses the default if none is specified.
* @return array The array of paging parameters for the paginated resultset.
*/
function params($model = null) {
@@ -84,7 +84,7 @@ function params($model = null) {
/**
* Sets default options for all pagination links
*
* @param mixed $options Default options for pagination links. If a string is supplied - it
* @param mixed $options Default options for pagination links. If a string is supplied - it
* is used as the DOM id element to update. See #options for list of keys.
*/
function options($options = array()) {
@@ -113,7 +113,7 @@ function options($options = array()) {
/**
* Gets the current page of the recordset for the given model
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param string $model Optional model name. Uses the default if none is specified.
* @return string The current page number of the recordset.
*/
function current($model = null) {
@@ -127,8 +127,8 @@ function current($model = null) {
/**
* Gets the current key by which the recordset is sorted
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param mixed $options Options for pagination links. See #options for list of keys.
* @param string $model Optional model name. Uses the default if none is specified.
* @param mixed $options Options for pagination links. See #options for list of keys.
* @return string The name of the key by which the recordset is being sorted, or
* null if the results are not currently sorted.
*/
@@ -158,8 +158,8 @@ function sortKey($model = null, $options = array()) {
/**
* Gets the current direction the recordset is sorted
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param mixed $options Options for pagination links. See #options for list of keys.
* @param string $model Optional model name. Uses the default if none is specified.
* @param mixed $options Options for pagination links. See #options for list of keys.
* @return string The direction by which the recordset is being sorted, or
* null if the results are not currently sorted.
*/
@@ -185,6 +185,12 @@ function sortDir($model = null, $options = array()) {
/**
* Generates a "previous" link for a set of paged records
*
* Options:
*
* - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `escape` Whether you want the contents html entity encoded, defaults to true
* - `model` The model to use, defaults to PaginatorHelper::defaultModel()
*
* @param string $title Title for the link. Defaults to '<< Previous'.
* @param mixed $options Options for pagination link. See #options for list of keys.
* @param string $disabledTitle Title when the link is disabled.
@@ -197,10 +203,16 @@ function prev($title = '<< Previous', $options = array(), $disabledTitle = null,
/**
* Generates a "next" link for a set of paged records
*
* @param string $title Title for the link. Defaults to 'Next >>'.
* @param mixed $options Options for pagination link. See #options for list of keys.
* @param string $disabledTitle Title when the link is disabled.
* @param mixed $disabledOptions Options for the disabled pagination link. See #options for list of keys.
* Options:
*
* - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `escape` Whether you want the contents html entity encoded, defaults to true
* - `model` The model to use, defaults to PaginatorHelper::defaultModel()
*
* @param string $title Title for the link. Defaults to 'Next >>'.
* @param mixed $options Options for pagination link. See above for list of keys.
* @param string $disabledTitle Title when the link is disabled.
* @param mixed $disabledOptions Options for the disabled pagination link. See above for list of keys.
* @return string A "next" link or or $disabledTitle text if the link is disabled.
*/
function next($title = 'Next >>', $options = array(), $disabledTitle = null, $disabledOptions = array()) {
@@ -210,10 +222,15 @@ function next($title = 'Next >>', $options = array(), $disabledTitle = null, $di
* 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()
*
* @param string $title Title for the link.
* @param string $key The name of the key that the recordset should be sorted. If $key is null
* $title will be used for the key, and a title will be generated by inflection.
* @param array $options Options for sorting link. See #options for list of keys.
* @param array $options Options for sorting link. See above for list of keys.
* @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified
* key the returned link will sort by 'desc'.
*/
@@ -244,9 +261,16 @@ function sort($title, $key = null, $options = array()) {
/**
* Generates a plain or Ajax link with pagination parameters
*
* @param string $title Title for the link.
* @param mixed $url Url for the action. See Router::url()
* @param array $options Options for the link. See #options for list of keys.
* Options
*
* - `update` The Id of the DOM element you wish to update. Creates Ajax enabled links
* with the AjaxHelper.
* - `escape` Whether you want the contents html entity encoded, defaults to true
* - `model` The model to use, defaults to PaginatorHelper::defaultModel()
*
* @param string $title Title for the link.
* @param mixed $url Url for the action. See Router::url()
* @param array $options Options for the link. See #options for list of keys.
* @return string A link with pagination parameters.
*/
function link($title, $url = array(), $options = array()) {
@@ -271,9 +295,9 @@ function link($title, $url = array(), $options = array()) {
/**
* Merges passed URL options with current pagination state to generate a pagination URL.
*
* @param array $options Pagination/URL options array
* @param boolean $asArray
* @param string $model Which model to paginate on
* @param array $options Pagination/URL options array
* @param boolean $asArray Return the url as an array, or a URI string
* @param string $model Which model to paginate on
* @return mixed By default, returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript)
*/
function url($options = array(), $asArray = false, $model = null) {
@@ -328,7 +352,7 @@ function __pagingLink($which, $title = null, $options = array(), $disabledTitle
/**
* Returns true if the given result set is not at the first page
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param string $model Optional model name. Uses the default if none is specified.
* @return boolean True if the result set is not at the first page.
*/
function hasPrev($model = null) {
@@ -346,8 +370,8 @@ function hasNext($model = null) {
/**
* Returns true if the given result set has the page number given by $page
*
* @param string $model Optional model name. Uses the default if none is specified.
* @param int $page The page number - if not set defaults to 1.
* @param string $model Optional model name. Uses the default if none is specified.
* @param int $page The page number - if not set defaults to 1.
* @return boolean True if the given result set has the specified page number.
*/
function hasPage($model = null, $page = 1) {
@@ -389,7 +413,16 @@ function defaultModel() {
/**
* Returns a counter string for the paged result set
*
* @param mixed $options Options for the counter string. See #options for list of keys.
* 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%`, `%start%`, `%end%` and any
* custom content you would like.
* - `separator` The separator string to use, default to ' of '
*
* @param mixed $options Options for the counter string. See #options for list of keys.
* @return string Counter string.
*/
function counter($options = array()) {
@@ -400,8 +433,8 @@ function counter($options = array()) {
$options = array_merge(
array(
'model' => $this->defaultModel(),
'format' => 'pages',
'separator' => ' of '
'format' => 'pages'
'separator' => __(' of ', true)
),
$options);
@@ -446,7 +479,20 @@ function counter($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 (default: 8)
*
* @param mixed $options Options for the numbers, (before, after, model, modulus, separator)
* Options
*
* - `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
* - `last` Whether you want last links generated, set to an integer to define the number of 'last'
* links to generate
*
* @param mixed $options Options for the numbers, (before, after, model, modulus, separator)
* @return string numbers string.
*/
function numbers($options = array()) {
@@ -555,8 +601,15 @@ function numbers($options = array()) {
/**
* Returns a first or set of numbers for the first pages
*
* @param mixed $first if string use as label for the link, if numeric print page numbers
* @param mixed $options
* Options:
*
* - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `before` Content to insert before the link/tag
* - `model` The model to use defaults to PaginatorHelper::defaultModel()
* - `separator` Content between the generated links, defaults to ' | '
*
* @param mixed $first if string use as label for the link, if numeric print page numbers
* @param mixed $options
* @return string numbers string.
*/
function first($first = '<< first', $options = array()) {
@@ -599,8 +652,15 @@ function first($first = '<< first', $options = array()) {
/**
* Returns a last or set of numbers for the last pages
*
* @param mixed $last if string use as label for the link, if numeric print page numbers
* @param mixed $options
* Options:
*
* - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `before` Content to insert before the link/tag
* - `model` The model to use defaults to PaginatorHelper::defaultModel()
* - `separator` Content between the generated links, defaults to ' | '
*
* @param mixed $last if string use as label for the link, if numeric print page numbers
* @param mixed $options Array of options
* @return string numbers string.
*/
function last($last = 'last >>', $options = array()) {

0 comments on commit 6b043c6

Please sign in to comment.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.