# Yahoo! UI Library

### DataTable Widget 2.5.1

Yahoo! UI Library > datatable > YAHOO.widget.Paginator

Show Private Show Protected

## Class YAHOO.widget.Paginator - uses YAHOO.util.EventProvider, YAHOO.util.AttributeProvider

The Paginator widget provides a set of controls to navigate through paged data.

### Constructor

YAHOO.widget.Paginator `( config )`

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

### Properties

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

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

#### id `- private static number`

Incrementing index used to give instances unique ids.

#### ID_BASE `- private static string`

Base of id strings used for ui components.

#### TEMPLATE_DEFAULT `- static string`

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

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

#### VALUE_UNLIMITED `- static final number`

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

#### Properties inherited from YAHOO.util.AttributeProvider:

`_configs`

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### destroy

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

Returns: `void`

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

Returns: `number`

#### getNextPage

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

Returns: `number`

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

Returns: `number`

#### 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

Returns: `object`

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

Returns: `number`

#### 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?

Returns: `boolean`

#### hasPage

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

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

Returns: `boolean`

#### hasPreviousPage

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

Returns: `boolean`

#### initConfig

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

Returns: `void`

#### initEvents

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

Returns: `void`

#### initUIComponents

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

Returns: `void`

#### render

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

Returns: `void`

#### 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

Returns: `void`

#### 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

Returns: `void`

#### 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

Returns: `void`

#### 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

Returns: `void`

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

Returns: `void`

#### Methods inherited from YAHOO.util.AttributeProvider:

`configureAttribute, fireBeforeChangeEvent, fireChangeEvent, get, getAttributeConfig, getAttributeKeys, refresh, register, resetAttributeConfig, resetValue, set, setAttributeConfig, setAttributes`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### alwaysVisibleChange

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

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

#### beforeAlwaysVisibleChange

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

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

#### beforeContainerClassChange

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

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

#### beforeContainersChange

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

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

#### beforeIdChange

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

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

#### beforeInitialPageChange

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

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

#### beforeRecordOffsetChange

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

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

#### beforeRenderedChange

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

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

#### beforeRowsPerPageChange

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

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

#### beforeTemplateChange

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

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

#### beforeTotalRecordsChange

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

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

#### beforeUpdateOnChangeChange

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

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

#### containerClassChange

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

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

#### containersChange

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

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

#### idChange

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

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

#### initialPageChange

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

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

#### recordOffsetChange

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

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

#### renderedChange

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

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

#### rowsPerPageChange

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

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

#### templateChange

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

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

#### totalRecordsChange

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

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

#### updateOnChangeChange

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

Parameters:
  `eventInfo <{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.
Default Value: false

Copyright © 2007 Yahoo! Inc. All rights reserved.