Jump to Table of Contents

Paginator

The Paginator utility allows you to display an item or a group of items depending on the number of items you wish to display at one time. This allows you to increase your applicatoin response time by displaying a limited number of items for easy viewing and giving the user the ability to request additional items when they are ready.

Getting Started

To include the source files for Paginator and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('paginator', function (Y) {
    // Paginator is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Creating a Paginator Object

A continuous paginator is one that has no number of items to display. This is created by simply instantiating a new paginator.

var continuous = new Y.Paginator();

If you know the total number of items you have avilable, you can create a paginator that can tell you the total number of pages and allow you to go to a specific page within that range.

var pg = new Y.Paginator({
    totalItems: 100
});

Creating a Paginator UI

It is important to remember that Paginator does not have any associated interface designs, so you will need to do this yourself. This could be as simple as having a list of numbers that adjust the paginator's page when they are clicked.

<ul class="spiffy-paging">
    <li><a href="?pg=1" data-page="1">1</a></li>
    <li><a href="?pg=2" data-page="2">2</a></li>
    <li><a href="?pg=3" data-page="3">3</a></li>
    <li><a href="?pg=4" data-page="4">4</a></li>
    <li><a href="?pg=5" data-page="5">5</a></li>
</ul>

<script>
YUI().use('paginator', 'node', function (Y) {
    var pageUI = Y.one('.spiffy-paging'),
        pg = new Y.Paginator({
            totalItems: 5,
            itemsPerPage: 1
        });

    pg.after('pageChange', function (e) {
        // fetch new page data
    });

    pageUI.delegate('click', function (e) {
        e.preventDefault();
        pg.set('page', parseInt(e.currentTarget.getData('page'), 10));
    }, 'a');
});
</script>

Understanding Paginator

Paginators are very useful when you have more information avialable than you wish to show at one time.

This could be something as simple as a slideshow, where you have a few panels but only wish to show one at a time, a table of the fifty states and their population displaying 10 at a time, or a search results page displaying 20 items of millions.

To get started, let's look at the attributes available to us that allow a paginator to work.

Y.Paginator: Attributes

Attribute Data type Description
itemsPerPage Number Maximum number of items per page. A value of negative one (-1) indicates all items on one page.
page Number Current page count. First page is 1.
totalItems Number Total number of items in all pages.
totalPages Number Read Only Total number of pages to display.

Y.Paginator: Methods

Paginator also comes with a few methods to help us traverse through the pages in order.

Method Returns Description
hasNextPage Boolean

True if there is a next page, otherwise false.

If totalItems isn't set, assume there is always next page.

hasPrevPage Boolean True if there is a previous page, otherwise false.
nextPage chainable Sets the page to the next page in the set, if there is a next page.
prevPage chainable Sets the page to the previous page in the set, if there is a previous page.

Paging URLs

Paginator also has the ability to format urls for you based on the given page number and a provided URL template.

To get these features, you need only use() 'paginator-url'. Adding 'paginator-url' to your use() statement will add the following attributes and methods:

Y.Paginator.Url: Attributes

Attribute Data type Description
pageUrl String

URL to return formatted with the page number. URL uses Y.Lang.sub for page number stubstitutions.

For example, if the page number is 3, setting the pageUrl to "?pg={page}", will result in "?pg=3"

Y.Paginator.Url: Methods

Method Returns Description
formatPageUrl String | null

Returns a formated URL for the provided page number.

You can provide a page number to format if you choose. If you do not provide a page number, the current page will be used.

nextPageUrl String | null Returns a formated URL for the next page.
prevPageUrl String | null Returns a formated URL for the previous page.