API: paginator YAHOO.widget.Paginator (YUI Library)

# Yahoo! UI Library

### paginator 2.9.0

Yahoo! UI Library > paginator > YAHOO.widget.Paginator
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.Paginator

Instantiate a Paginator, passing a configuration object to the contructor. The configuration object should contain the following properties:

- rowsPerPage : n (int)
- totalRecords : n (int or Paginator.VALUE_UNLIMITED)
- containers : id | el | arr (HTMLElement reference, its id, or an array of either)

### Constructor

YAHOO.widget.Paginator `( config )`

Parameters:
  `config <Object>` Object literal to set instance and ui component configuration.

### Properties

#### _batch - `protected boolean`

Flag used to indicate multiple attributes are being updated via setState

#### _containers - `private Array(HTMLElement)`

Array of nodes in which to render pagination controls. This is set via the "containers" attribute.

#### _pageChanged - `protected boolean`

Used by setState to indicate when a page change has occurred

#### _state - `protected Object`

Temporary state cache used by setState to keep track of the previous state for eventual pageChange event firing

#### Paginator.id - `private static number`

Incrementing index used to give instances unique ids.

#### Paginator.ID_BASE - `private static string`

Base of id strings used for ui components.

#### Paginator.TEMPLATE_DEFAULT - `static string`

Default template used by Paginator instances. Update this if you want all new Paginators to use a different default template.

#### Paginator.TEMPLATE_ROWS_PER_PAGE - `static string`

Common alternate pagination format, including page links, links for previous, next, first and last pages as well as a rows-per-page dropdown. Offered as a convenience.

#### Paginator.ui - `static object`

Storage object for UI Components

#### Paginator.VALUE_UNLIMITED - `static final number`

Used to identify unset, optional configurations, or used explicitly in the case of totalRecords to indicate unlimited pagination.

### Methods

#### _firePageChange

`protected void _firePageChange ( state )`
Fires a pageChange event in the form of a standard attribute change event with additional properties prevState and newState.

Parameters:
  `state <Object>` the result of getState(oldState)

#### _handleStateChange

`protected void _handleStateChange ( e )`
Fires the pageChange event when the state attributes have changed in such a way as to locate the current recordOffset on a new page.

Parameters:
  `e <Event>` the attribute change event

#### _renderTemplate

`protected void _renderTemplate ( container , template , id_base , hide )`
Creates the individual ui components and renders them into a container.

Parameters:
  `container <HTMLElement>` where to add the ui components
  `template <String>` the template to use as a guide for rendering
  `id_base <String>` id base for the container's ui components
  `hide <Boolean>` leave the container hidden after assembly

#### _selfSubscribe

`protected void _selfSubscribe ( )`
Subscribes to instance attribute change events to automate certain behaviors.

#### _syncRecordOffset

`protected void _syncRecordOffset ( e )`
Sets recordOffset to the starting index of the previous page when totalRecords is reduced below the current recordOffset.

Parameters:
  `e <Event>` totalRecordsChange event

#### destroy

`void destroy ( )`
Removes controls from the page and unhooks events.

#### getContainerNodes

`Array getContainerNodes ( )`
Get the configured container nodes

Returns: `Array`
  array of HTMLElement nodes

#### getCurrentPage

`number getCurrentPage ( )`
Get the page number corresponding to the current record offset.

#### getNextPage

`number getNextPage ( )`
Get the page number of the next page, or null if the current page is the last page.

#### getPageRecords

`Array getPageRecords ( page )`
Get the start and end record indexes of the specified page.

Parameters:
  `page <number>` (optional) The page (current page if not specified)

Returns: `Array`
  [start_index, end_index]

#### getPreviousPage

`number getPreviousPage ( )`
Get the page number of the previous page, or null if the current page is the first page.

#### getRowsPerPage

`number getRowsPerPage ( )`
Get the number of rows per page.

Returns: `number`
  the current setting of the rowsPerPage attribute

#### getStartIndex

`number getStartIndex ( )`
Get the index of the first record on the current page

Returns: `number`
  the index of the first record on the current page

#### getState

`object getState ( changes )`
Get an object literal describing the current state of the paginator. If an object literal of proposed values is passed, the proposed state will be returned as an object literal with the following keys:

- paginator - instance of the Paginator
- page - number
- totalRecords - number
- recordOffset - number
- rowsPerPage - number
- records - [ start_index, end_index ]
- before - (OPTIONAL) { state object literal for current state }

Parameters:
  `changes <object>` OPTIONAL object literal with proposed values Supported change keys include:
  - rowsPerPage
  - totalRecords
  - recordOffset OR
  - page

#### getTotalPages

`number getTotalPages ( )`
Get the total number of pages in the data set according to the current rowsPerPage and totalRecords values. If totalRecords is not set, or set to YAHOO.widget.Paginator.VALUE_UNLIMITED, returns YAHOO.widget.Paginator.VALUE_UNLIMITED.

#### getTotalRecords

`number getTotalRecords ( )`
Get the total number of records.

Returns: `number`
  the current setting of totalRecords attribute

#### hasNextPage

`boolean hasNextPage ( )`
Are there records on the next page?

#### hasPage

`boolean hasPage ( page )`
Does the requested page have any records?

Parameters:
  `page <number>` the page in question

#### hasPreviousPage

`boolean hasPreviousPage ( )`
Is there a page before the current page?

#### initConfig

`private void initConfig ( )`
Initialize the Paginator's attributes (see YAHOO.util.Element class AttributeProvider).

#### initEvents

`private void initEvents ( )`
Initialize this instance's CustomEvents.

#### initUIComponents

`private void initUIComponents ( )`
Initialize registered ui components onto this instance.

#### Paginator.isNumeric

`static void Paginator.isNumeric ( v )`
Similar to YAHOO.lang.isNumber, but allows numeric strings. This is is used for attribute validation in conjunction with getters that return numbers.

Parameters:
  `v <Number|String>` value to be checked for number or numeric string

#### Paginator.toNumber

`static Paginator.toNumber ( n )`
Return a number or null from input

Parameters:
  `n <Number|String>` a number or numeric string

Returns: ``
  Number

#### render

`render ( )`
Render the pagination controls per the format attribute into the specified container nodes.

Returns: ``
  the Paginator instance

Chainable: This method is chainable.

#### renderUIComponent

`renderUIComponent ( marker , id_base )`
Replaces a marker node with a rendered UI component, determined by the yui-pg-ui-(UI component class name) in the marker's className. e.g. yui-pg-ui-PageLinks => new YAHOO.widget.Paginator.ui.PageLinks(this)

Parameters:
  `marker <HTMLElement>` the marker node to replace
  `id_base <String>` string base the component's generated id

Returns: ``
  the Paginator instance

Chainable: This method is chainable.

#### setPage

`void setPage ( newPage , silent )`
Set the current page to the provided page number if possible.

Parameters:
  `newPage <number>` the new page number
  `silent <boolean>` whether to forcibly avoid firing the changeRequest event

#### setRowsPerPage

`void setRowsPerPage ( rpp , silent )`
Set the number of rows per page.

Parameters:
  `rpp <number>` the new number of rows per page
  `silent <boolean>` whether to forcibly avoid firing the changeRequest event

#### setStartIndex

`void setStartIndex ( offset , silent )`
Move the record offset to a new starting index. This will likely cause the calculated current page to change. You should probably use setPage.

Parameters:
  `offset <number>` the new record offset
  `silent <boolean>` whether to forcibly avoid firing the changeRequest event

#### setState

`void setState ( state )`
Convenience method to facilitate setting state attributes rowsPerPage, totalRecords, recordOffset in batch. Also supports calculating recordOffset from state.page if state.recordOffset is not provided. Fires only a single pageChange event, if appropriate. This will not fire a changeRequest event.

Parameters:
  `state <Object>` Object literal of attribute:value pairs to set

#### setTotalRecords

`void setTotalRecords ( total , silent )`
Set the total number of records.

Parameters:
  `total <number>` the new total number of records
  `silent <boolean>` whether to forcibly avoid firing the changeRequest event

#### updateVisibility

`void updateVisibility ( )`
Hides the containers if there is only one page of data and attribute alwaysVisible is false. Conversely, it displays the containers if either there is more than one page worth of data or alwaysVisible is turned on.

### Events

#### alwaysVisibleChange

`alwaysVisibleChange ( event )`
Fires when the value for the configuration attribute 'alwaysVisible' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeAlwaysVisibleChange

`beforeAlwaysVisibleChange ( event )`
Fires before the value for the configuration attribute 'alwaysVisible' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeContainerClassChange

`beforeContainerClassChange ( event )`
Fires before the value for the configuration attribute 'containerClass' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeContainersChange

`beforeContainersChange ( event )`
Fires before the value for the configuration attribute 'containers' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeDestroy

`beforeDestroy ( )`
Event that fires before the destroy event.

#### beforeIdChange

`beforeIdChange ( event )`
Fires before the value for the configuration attribute 'id' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeInitialPageChange

`beforeInitialPageChange ( event )`
Fires before the value for the configuration attribute 'initialPage' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeRecordOffsetChange

`beforeRecordOffsetChange ( event )`
Fires before the value for the configuration attribute 'recordOffset' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeRenderedChange

`beforeRenderedChange ( event )`
Fires before the value for the configuration attribute 'rendered' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeRowsPerPageChange

`beforeRowsPerPageChange ( event )`
Fires before the value for the configuration attribute 'rowsPerPage' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeTemplateChange

`beforeTemplateChange ( event )`
Fires before the value for the configuration attribute 'template' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeTotalRecordsChange

`beforeTotalRecordsChange ( event )`
Fires before the value for the configuration attribute 'totalRecords' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### beforeUpdateOnChangeChange

`beforeUpdateOnChangeChange ( event )`
Fires before the value for the configuration attribute 'updateOnChange' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### changeRequest

`changeRequest ( )`
Event fired when a change in pagination values is requested, either by interacting with the various ui components or via the setStartIndex(n) etc APIs. Subscribers will receive the proposed state as the first parameter. The proposed state object will contain the following keys:

- paginator - the Paginator instance
- page
- totalRecords
- recordOffset - index of the first record on the new page
- rowsPerPage
- records - array containing [start index, end index] for the records on the new page
- before - object literal with all these keys for the current state

#### containerClassChange

`containerClassChange ( event )`
Fires when the value for the configuration attribute 'containerClass' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### containersChange

`containersChange ( event )`
Fires when the value for the configuration attribute 'containers' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### destroy

`destroy ( )`
Event used to trigger cleanup of ui components

#### idChange

`idChange ( event )`
Fires when the value for the configuration attribute 'id' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### initialPageChange

`initialPageChange ( event )`
Fires when the value for the configuration attribute 'initialPage' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### pageChange

`pageChange ( )`
Event fired when attribute changes have resulted in the calculated current page changing.

#### recordOffsetChange

`recordOffsetChange ( event )`
Fires when the value for the configuration attribute 'recordOffset' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### render

`render ( )`
Event fired when the Paginator is initially rendered

#### rendered

`rendered ( )`
Event fired when the Paginator is initially rendered
Deprecated use render event

#### renderedChange

`renderedChange ( event )`
Fires when the value for the configuration attribute 'rendered' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### rowsPerPageChange

`rowsPerPageChange ( event )`
Fires when the value for the configuration attribute 'rowsPerPage' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### templateChange

`templateChange ( event )`
Fires when the value for the configuration attribute 'template' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### totalRecordsChange

`totalRecordsChange ( event )`
Fires when the value for the configuration attribute 'totalRecords' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### updateOnChangeChange

`updateOnChangeChange ( event )`
Fires when the value for the configuration attribute 'updateOnChange' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

### Configuration Attributes

#### alwaysVisible `- boolean`

Display pagination controls even when there is only one page. Set to false to forgo rendering and/or hide the containers when there is only one page of data. Note if you are using the rowsPerPage dropdown ui component, visibility will be maintained as long as the number of records exceeds the smallest page size.
Default Value: true

#### containerClass `- string`

Class assigned to the element(s) containing pagination controls.
Default Value: 'yui-pg-container'

#### containers `- {string|HTMLElement|Array(string|HTMLElement)}`

REQUIRED. Node references or ids of nodes in which to render the pagination controls.

#### id `- readonly integer`

Unique id assigned to this instance

#### initialPage `- integer`

Page to display on initial paint
Default Value: 1

#### recordOffset `- integer`

Zero based index of the record considered first on the current page. For page based interactions, don't modify this attribute directly; use setPage(n).
Default Value: 0

#### rendered `- readonly boolean`

Indicator of whether the DOM nodes have been initially created

#### rowsPerPage `- integer`

REQUIRED. Number of records constituting a "page"

#### template `- string`

Template used to render controls. The string will be used as innerHTML on all specified container nodes. Bracketed keys (e.g. {pageLinks}) in the string will be replaced with an instance of the so named ui component.

#### totalRecords `- integer`

Total number of records to paginate through
Default Value: 0

#### updateOnChange `- boolean`

Update the UI immediately upon interaction. If false, changeRequest subscribers or other external code will need to explicitly set the new values in the paginator to trigger repaint.
Deprecated use changeRequest listener that calls setState
Default Value: false

Copyright © 2011 Yahoo! Inc. All rights reserved.