YUI Library Examples: DataTable Control: Configuring the Paginator

Yahoo! recommends YUI 3. Learn about YUI 3 on YUILibrary.com.

Customizing pagination

Besides the normal configurations for pagination, we'll demonstrate the use of the other Paginator configuration options. Most notably, we'll use the template and pageLabelBuilder options to render the pagination controls in a custom layout with more descriptive page links.

Markup

CSS

Code

We'll start by making sure our data is in order, then define the function that we'll use to populate the page links.

YAHOO.util.Event.onDOMReady(function () {

// Sort our data by state, then area code
    var Data = YAHOO.example.Data.areacodes;
    Data.sort(function (a,b) {
        return YAHOO.util.Sort.compare(a.state,b.state) ||
               YAHOO.util.Sort.compare(a.areacode,b.areacode);
    });

// Custom function we'll use to create the page links
    var buildPageLabel = function (recs) {
        var start = recs[0],
            end   = recs[1];

// Nested function to find the smallest substring
        // to indicate how two strings differ
        var diffNames = function (a,b) {
            var aa = a.state.toLowerCase(),
                bb = b.state.toLowerCase();

for (var i = 0, len = aa.length; i < len; ++i) {
                if (aa.charAt(i) !== bb.charAt(i)) {
                    return a.state.substr(0,i+1);
                }
            }

return a.state + ' ('+a.areacode+')';
        };

// Build label as "A - C" or "Abc - Def"
        var label = '';
        if (!start) {
            label = Data[0].state.substr(0,2) + ' - ';
        } else {
            label = diffNames(Data[start], Data[start-1]) + ' - ';
        }

if (Data[end+1]) {
            label += diffNames(Data[end], Data[end+1]);
        } else {
            label += diffNames(Data[end], Data[start]);
        }

return label;
    };

We'll assign something to every available Paginator configuration key, if even the default value, just for illustration.

// Paginator configurations
    var myPaginatorConfig = {
        // REQUIRED
        rowsPerPage : 20,

// REQUIRED, but DataTable will default if not provided
        containers  : 'pag',

// If not provided, there is no last page or total pages.
        // DataTable will set this in the DataSource callback, so this is
        // redundant.
        totalRecords : Data.length,

// page to activate at load
        initialPage : 3,

// Class the element(s) that will contain the controls
        containerClass : 'yui-pg-container', // default

// Define the innerHTML of the container(s) using placeholders
        // to identify where the controls will be located
        template :
            '<h3>Now showing:</h3>' +
            '<p>{CurrentPageReport}</p>' +
            '<p class="pg-nav">' +
                '{FirstPageLink} {PreviousPageLink} ' +
                '{NextPageLink} {LastPageLink}' +
            '</p>' +
            '<label>Page size: {RowsPerPageDropdown}</label>' +
            '<h3>Directory</h3>' +
            '{PageLinks}',

// If there is less data than would display on one page, pagination
        // controls can be omitted by setting this to false.
        alwaysVisible : true, // default

// Override setPage (et al) to immediately update internal values
        // and update the pagination controls in response to user actions.
        // Default is false; requests are delegated through the changeRequest
        // event subscriber.
        updateOnChange : false, // default

// Options for FirstPageLink component
        firstPageLinkLabel : "&lt;&lt;",
        firstPageLinkClass : "yui-pg-first", // default

// Options for LastPageLink component
        lastPageLinkLabel : "&gt;&gt;",
        lastPageLinkClass : "yui-pg-last", // default

// Options for PreviousPageLink component
        previousPageLinkLabel : "&lt; previous",
        previousPageLinkClass : "yui-pg-previous", // default

// Options for NextPageLink component
        nextPageLinkLabel : "next &gt;", // default
        nextPageLinkClass : "yui-pg-next", // default

// Options for PageLinks component
        pageLinksContainerClass : 'yui-pg-pages',        // default
        pageLinkClass           : 'yui-pg-page',         // default
        currentPageClass        : 'yui-pg-current-page', // default

// Display a maximum of X page links at a time.  Use
        // YAHOO.widget.Paginator.VALUE_UNLIMITED to show all page links
        pageLinks               : YAHOO.widget.Paginator.VALUE_UNLIMITED,

// Create custom page link labels
        pageLabelBuilder        : function (page,paginator) {
            return buildPageLabel(paginator.getPageRecords(page));
        },

// Options for RowsPerPageDropdown component
        rowsPerPageDropdownClass : "yui-pg-rpp-options", // default
        rowsPerPageOptions       : [
            { value : 20, text : "small" },
            { value : 40, text : "medium" },
            { value : 100, text : "large" }
        ],

// Options for CurrentPageReport component
        pageReportClass : 'yui-pg-current', // default

// Provide a key:value map for use by the pageReportTemplate.
        // Unlikely this will need to be customized; see API docs for the
        // template keys made available by the default value generator
        pageReportValueGenerator : function (paginator) {
            var recs  = paginator.getPageRecords();

return {
                start     : Data[recs[0]].state,
                end       : Data[recs[1]].state
            };
        },

// How to render the notification of the Paginator's current state
        pageReportTemplate : '{start} - {end}'
    };

// Create the Paginator for our DataTable to use
    var myPaginator = new YAHOO.widget.Paginator(myPaginatorConfig);

Beyond this, it's simply a matter of creating your DataTable as normal.

YUI Logger Output:

Note: Logging and debugging is currently turned off for this example.

Reload with logging
and debugging enabled.

More DataTable Control Resources:

All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.