Yahoo! UI Library

DataTable Widget  2.5.2

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:

Methods

_syncRecordOffset

private void _syncRecordOffset ( v )
Setting totalRecords to a value lower than the current recordOffset will result in the recordOffset being adjusted to the starting index of the previous page. Called from totalRecords attribute method.
Parameters:
v <int> new value for totalRecords
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

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

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.