Yahoo! UI Library

paginator  2.8.0r4

Yahoo! UI Library > paginator > YAHOO.widget.Paginator
Search:
 
Filters

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)
Returns: void

_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
Returns: void

_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
Returns: void

_selfSubscribe

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

_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
Returns: void

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

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
Returns: void

Paginator.toNumber

static Paginator.toNumber ( n )
Return a number or null from input
Parameters:
n <Number|String> a number or numeric string

render

render ( )
Render the pagination controls per the format attribute into the specified container nodes.
Chainable: This method is chainable.

renderUIComponent

void 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: 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

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

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 © 2009 Yahoo! Inc. All rights reserved.