Developer Network Home - Help

Yahoo! UI Library: Paginator

Yahoo! UI Library: Paginator

The Paginator Control allows you to reduce the page size and render time of your site or web application by breaking up large data sets into discreet pages. Paginator addresses the navigation aspect of chunked content, offering a set of controls that it can render into your UI to allow users to navigate through logical sections of local or remote data.

The Paginator Control was introduced with DataTable in version 2.5.0, but it has been broken out for general use as of version 2.6.0.

Getting Started

To use Paginator, include the following source files in the web page:

Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Paginator Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is paginator. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers; see "Serving YUI Files from Yahoo!" for important information about this service. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Basic HTML Setup

Paginator does not have to render any controls, but it is likely that you will want to. All you need in your markup are container nodes into which the Paginator can render its controls. One Paginator instance can render controls into any number of containers.

Currently, it is not strictly required that the container elements be included in the live DOM, but that may become necessary for future or custom UI components.

Initializing Paginator

The Paginator class is located at YAHOO.widget.Paginator. The constructor takes a single argument, an object literal containing configuration values.

Configuration can be omitted at construction, but these attributes must be set before the Paginator is render()ed.

By default, Paginator will render controls into each specified container like this:

A screenshot of the default set and orientation of Paginator controls with YUI Sam skin applied

Using the Paginator

This section describes how to customize the Paginator and includes:

Attaching Paginator to Your Data

Paginator does not directly modify your content. The key to wiring up Paginator to work with your page, application, or widget is to subscribe to its changeRequest event.

When users interact with any of the Paginator's controls (or calls are made to the Paginator's public API methods) the Paginator does not immediately update its state and UI. Instead, it broadcasts its changeRequest event to all subscribers, passing an object describing the requested pagination state.

As a subscriber, your app is then responsible for collecting and displaying the data or content appropriate for that state, then updating the Paginator's state accordingly. The Paginator's UI updates automatically when it's state is changed.

diagram of the workflow of an application that consumes Paginator

Pagination State

The object provided to changeRequest subscribers is the output from the Paginator's getState method. Called without input, getState returns an object literal in the following form:

If passed an object literal with proposed values for any of these properties (except paginator and records), the returned state will contain the full calculated state given the provided modifications and an additional property, before. The value assigned to before will be the current state.

Paginator does not store transitional states. When users interact with the UI, the changeRequest event is fired with the proposed state object and immediately forgotten. Until the subscriber directly updates the Paginator's state, the Paginator will remain in its current state.

Public API methods

Some of the more useful methods in Paginator's API are:

render()
Creates the content for the configured template in the specified containers.
getCurrentPage()
Returns the current page number.
getPageRecords(n)
Returns an array with two values: the index/offset associated with the first and last record on the current page or page supplied as an input parameter.
getTotalPages()
Returns the number of pages available for paging given the current totalRecords and rowsPerPage configuration.
getState(o)
Returns an object representing the current or proposed state, depending on the input. See Pagination State.
hasPage(n)
Returns true if the input page is available to navigate to.
setPage(n)
Fires a changeRequest with the proposed page.
setRowsPerPage(n)
Fires a changeRequest with the proposed rowsPerPage.
setTotalRecords(n)
Fires a changeRequest with the proposed totalRecords.
setState(o)
Applies state information to the Paginator's attributes in batch, triggering a UI update if necessary.

Note: the Paginator's state is maintained in its attributes recordOffset, totalRecords, and rowsPerPage. Calling set directly on these attributes will cause the UI to update if necessary. It will not trigger a changeRequest.

Paginator Configuration

A full list of configuration options is included in the API docs. The most common configurations passed at construction are:

rowsPerPage
Number of records associated with a single "page". (required).
totalRecords
The number of records to paginate through. Set to YAHOO.widget.Paginator.VALUE_UNLIMITED if there is no logical limit to the set. (required).
containers
Where to render the pagination UI. (required).
template
An HTML string including UI Component placeholders that will be used to populate the configured container elements. See Templates and UI Components.
alwaysVisible
Set to false, the configured containers will be hidden unless there is enough data for at least two pages. true by default.

Additionally, UI Components add their configuration options onto the host Paginator, so their configuration can be done during construction as well.

Paginator Events

In addition to the de facto change events emitted when its attributes are modified (e.g. totalRecordsChange), Paginator broadcasts the following interesting moments:

changeRequest
Fired when a user interacts with the Paginator UI, or calls are made to certain API methods. See Attaching Paginator to Your Data.
pageChange
Fired when an attribute change results in the current page changing.

Templates and UI Components

This section describes how the Paginator's UI is constructed and configured.

About UI Components

Paginator is built on a core model and a UI Component framework. The core (Paginator) is responsible for state calculations, and the UI Components are responsible for appropriately representing that state in the DOM. Each UI Component is its own class, built to handle a specific function. Included with the current Paginator release are the following UI Components:

The Paginator's template configuration attribute

The link between the Paginator core and the UI components is the Paginator's template configuration attribute.

The template attribute contains a string of markup mixed with placeholders identifying where in the markup each UI component should reside.

this would render something like this:

screen capture of a Paginator UI generated from a custom template

If multiple containers are specified, the same markup will be generated into each container, so avoid including any elements with an id attribute in your template.

Common UI Component Configurations

Each UI Component comes with its own set of configuration attributes for added flexibility. These attributes are added to the host Paginator, allowing configuration during the Paginator's construction. For a full list of available configuration attributes, check the respective class definitions in the API docs or the configuration example.

Some more common UI Component configurations are:

Rendering UI Components Manually

The template mechanism is convenient for common cases, but it is possible to manually place individual UI Components on the page. Each UI Component has a render(id) method that returns the generated DOM structure for that component. Coupling this with the DOM methods insertBefore or appendChild, you can have complete control of where and how many UI Components are added to your page.

Notice the containers configuration is not used, and the Paginator is not render()ed. When placing UI Components manually, neither is necessary.

Creating new UI Components

The Paginator core and UI Component architecture makes it easy to create new pagination controls. When render()ing its template, Pagintor looks for UI Component classes in the YAHOO.widget.Paginator.ui namespace matching any bracketed placeholders.

New Paginator UI Components should follow some basic guidelines:

  1. The class must live in the YAHOO.widget.Paginator.ui namespace.
  2. Include static method init(paginator) to add any configurations to the Paginator instance.
  3. Include an instance method render(id_base) to create and return the control's DOM structure.
  4. Do only one thing.
  5. Respect the separation of duties. The component's job is to read the Paginator's state and display it. It can request state modifications, but it should not directly modify the Paginator state.
  6. Be mindful that each component's render method will be called once for every configured container, so don't create duplicate ids (the id_base is to help avoid this).

Here is a starting template for new Paginator UI Components. And don't forget to share your new components on ydn-javascript or even submit a feature request to have your work added to the core build!

Paginator and DataTable

Paginator started its life in the DataTable widget in version 2.5.0. Beyond feature enhancements and bug fixes, Paginator has remained the same. It can be used with DataTable in the same fashion now as then.

YUI on Mobile: Using Paginator Control with "A-Grade" Mobile Browsers

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

There are no known issues with the rendering or operation of the Paginator on mobile devices.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

YUI Paginator on del.icio.us:

Copyright © 2009 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings