Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updating doc blocks for paginator helper.

  • Loading branch information...
commit 6b043c6c57da5d2d3f0538170e8aa964b2789039 1 parent 9d2628f
Mark Story markstory authored
Showing with 103 additions and 43 deletions.
  1. +103 −43 cake/libs/view/helpers/paginator.php
146 cake/libs/view/helpers/paginator.php
View
@@ -48,20 +48,20 @@ 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
*/
@@ -69,7 +69,7 @@ class PaginatorHelper extends AppHelper {
/**
* 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()) {
Please sign in to comment.
Something went wrong with that request. Please try again.