YUI Library Examples: Paginator: Configuring the Paginator

Paginator: Configuring the Paginator

In this example we'll demonstrate the use of all of Paginator's configuration options, including the options added by the bundled UI Components. Most notably, we'll use the template and pageLabelBuilder options to render the pagination controls in a custom layout with more descriptive page links. All content in the left column is generated by the Paginator.

View example in new window.

Area Codes by State
State	Code
Loading...
California	714
California	760
California	805
California	818
California	831
California	858
California	909
California	916
California	925
California	949
Cayman Islands	345
CNMI	670
Colorado	303
Colorado	719
Colorado	720
Colorado	970
Connecticut	203
Connecticut	475
Connecticut	860
Connecticut	959

Content in a DataTable

We'll use a DataTable instance to handle the content display. We'll use a single container for the Paginator controls, so the starting markup consists of two empty <div>s.


1	<div id="demo">
2	<div id="pag"></div>
3	<div id="tbl"></div>
4	</div>
	view plain \| print \| ?

Add Pagination

Create some functions that will be passed to some Paginator configuration attributes. Then create the Paginator using configuration entries for everything under the sun, providing default values in many cases.


1	YAHOO.util.Event.onDOMReady(function () {
2
3	var Ex = YAHOO.namespace('example');
4
5	// Custom function we'll use for the page links
6	Ex.buildPageLabel = function (recs) { ... };
7
8	// Paginator configurations
9	Ex.config = {
10	// REQUIRED
11	rowsPerPage : 20,
12
13	// REQUIRED, but DataTable will default if not provided
14	containers : 'pag',
15
16	// If not provided, there is no last page or total pages.
17	// DataTable will set this in the DataSource callback, so this is
18	// redundant.
19	totalRecords : Ex.data.areacodes.length,
20
21	// page to activate at load
22	initialPage : 3,
23
24	// Class the element(s) that will contain the controls
25	containerClass : 'yui-pg-container', // default
26
27	// etc, etc. See full code listing for all configuration
28	...
29	};
30
31	// Create the Paginator for our DataTable to use
32	Ex.paginator = new YAHOO.widget.Paginator(Ex.config);
	view plain \| print \| ?

Create the DataTable and render

Create the DataSource and DataTable by typical means. DataTable will call the Paginator's render method from within its own.


1	// Normal DataTable configuration
2	Ex.tableCols = [ {key:"state", label:"State", minWidth: 150},
3	{key:"areacode", label:"Code", width: 30}];
4
5	Ex.dataSource = new YAHOO.util.DataSource(Ex.data.areacodes, {
6	responseType : YAHOO.util.DataSource.TYPE_JSARRAY;
7	responseSchema : {
8	fields : ["state","areacode"]
9	}
10	});
11
12	// Pass the Paginator in the DataTable config
13	Ex.tableConfig = {
14	paginator : Ex.paginator,
15	caption : 'Area Codes by State'
16	};
17
18	Ex.dataTable = new YAHOO.widget.DataTable('tbl',
19	Ex.tableCols, Ex.dataSource, Ex.tableConfig);
	view plain \| print \| ?

Full Code Listing

JavaScript


1	YAHOO.util.Event.onDOMReady(function () {
2
3	var Ex = YAHOO.namespace('example');
4
5	// Sort our data by state, then area code
6	Ex.data.areacodes.sort(function (a,b) {
7	return YAHOO.util.Sort.compare(a.state,b.state) \|\|
8	YAHOO.util.Sort.compare(a.areacode,b.areacode);
9	});
10
11	// Custom function we'll use for the page links
12	Ex.buildPageLabel = function (recs) {
13	var data = Ex.data.areacodes,
14	start = recs[0],
15	end = recs[1];
16
17	// Nested function to find the smallest substring
18	// to indicate how two strings differ
19	var diffNames = function (a,b) {
20	var aa = a.state.toLowerCase(),
21	bb = b.state.toLowerCase();
22
23	for (var i = 0, len = aa.length; i < len; ++i) {
24	if (aa.charAt(i) !== bb.charAt(i)) {
25	return a.state.substr(0,i+1);
26	}
27	}
28
29	return a.state + ' ('+a.areacode+')';
30	};
31
32	// Build label as "A - C" or "Abc - Def"
33	var label = '';
34	if (!start) {
35	label = data[0].state.substr(0,2) + ' - ';
36	} else {
37	label = diffNames(data[start], data[start-1]) + ' - ';
38	}
39
40	if (data[end+1]) {
41	label += diffNames(data[end], data[end+1]);
42	} else {
43	label += diffNames(data[end], data[start]);
44	}
45
46	return label;
47	};
48
49
50	// Paginator configurations
51	Ex.config = {
52	// REQUIRED
53	rowsPerPage : 20,
54
55	// REQUIRED, but DataTable will default if not provided
56	containers : 'pag',
57
58	// If not provided, there is no last page or total pages.
59	// DataTable will set this in the DataSource callback, so this is
60	// redundant.
61	totalRecords : Ex.data.areacodes.length,
62
63	// page to activate at load
64	initialPage : 3,
65
66	// Class the element(s) that will contain the controls
67	containerClass : 'yui-pg-container', // default
68
69	// Define the innerHTML of the container(s) using placeholders
70	// to identify where the controls will be located
71	template :
72	'<h3>Now showing:</h3>' +
73	'<p>{CurrentPageReport}</p>' +
74	'<p class="pg-nav">' +
75	'{FirstPageLink} {PreviousPageLink} ' +
76	'{NextPageLink} {LastPageLink}' +
77	'</p>' +
78	'<label>Page size: {RowsPerPageDropdown}</label>' +
79	'<h3>Directory</h3>' +
80	'{PageLinks}',
81
82	// If there is less data than would display on one page, pagination
83	// controls can be omitted by setting this to false.
84	alwaysVisible : true, // default
85
86	// Override setPage (et al) to immediately update internal values
87	// and update the pagination controls in response to user actions.
88	// Default is false; requests are delegated through the changeRequest
89	// event subscriber.
90	updateOnChange : false, // default
91
92	// Options for FirstPageLink component
93	firstPageLinkLabel : "<<",
94	firstPageLinkClass : "yui-pg-first", // default
95
96	// Options for LastPageLink component
97	lastPageLinkLabel : ">>",
98	lastPageLinkClass : "yui-pg-last", // default
99
100	// Options for PreviousPageLink component
101	previousPageLinkLabel : "< previous",
102	previousPageLinkClass : "yui-pg-previous", // default
103
104	// Options for NextPageLink component
105	nextPageLinkLabel : "next >", // default
106	nextPageLinkClass : "yui-pg-next", // default
107
108	// Options for PageLinks component
109	pageLinksContainerClass : 'yui-pg-pages', // default
110	pageLinkClass : 'yui-pg-page', // default
111	currentPageClass : 'yui-pg-current-page', // default
112
113	// Display a maximum of X page links. Use
114	// YAHOO.widget.Paginator.VALUE_UNLIMITED to show all page links
115	pageLinks : YAHOO.widget.Paginator.VALUE_UNLIMITED,
116
117	// Create custom page link labels
118	pageLabelBuilder : function (page,paginator) {
119	return Ex.buildPageLabel(paginator.getPageRecords(page));
120	},
121
122	// Options for RowsPerPageDropdown component
123	rowsPerPageDropdownClass : "yui-pg-rpp-options", // default
124	rowsPerPageOptions : [
125	{ value : 20, text : "small" },
126	{ value : 40, text : "medium" },
127	{ value : 100, text : "large" }
128	],
129
130	// Options for CurrentPageReport component
131	pageReportClass : 'yui-pg-current', // default
132
133	// Provide a key:value map for use by the pageReportTemplate.
134	// Unlikely this will need to be customized; see API docs for the
135	// template keys made available by the default value generator
136	pageReportValueGenerator : function (paginator) {
137	var recs = paginator.getPageRecords();
138
139	return {
140	start : Ex.data.areacodes[recs[0]].state,
141	end : Ex.data.areacodes[recs[1]].state
142	};
143	},
144
145	// How to render the notification of the Paginator's current state
146	pageReportTemplate : '{start} - {end}'
147	};
148
149	// Create the Paginator for our DataTable to use
150	Ex.paginator = new YAHOO.widget.Paginator(Ex.config);
151
152
153	// Normal DataTable configuration
154	Ex.tableCols = [ {key:"state", label:"State", minWidth: 150},
155	{key:"areacode", label:"Code", width: 30}];
156
157	Ex.dataSource = new YAHOO.util.DataSource(Ex.data.areacodes, {
158	responseType : YAHOO.util.DataSource.TYPE_JSARRAY,
159	responseSchema : {
160	fields : ["state","areacode"]
161	}
162	});
163
164	// Pass the Paginator in the DataTable config
165	Ex.tableConfig = {
166	paginator : Ex.paginator,
167	caption : 'Area Codes by State'
168	};
169
170	Ex.dataTable = new YAHOO.widget.DataTable('tbl',
171	Ex.tableCols, Ex.dataSource, Ex.tableConfig);
172
173	});
	view plain \| print \| ?

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

var Ex = YAHOO.namespace('example');

// Sort our data by state, then area code
Ex.data.areacodes.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 for the page links
Ex.buildPageLabel = function (recs) {
    var data  = Ex.data.areacodes,
        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;
};

// Paginator configurations
Ex.config = {
    // 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 : Ex.data.areacodes.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 : "<<",
    firstPageLinkClass : "yui-pg-first", // default

// Options for LastPageLink component
    lastPageLinkLabel : ">>",
    lastPageLinkClass : "yui-pg-last", // default

// Options for PreviousPageLink component
    previousPageLinkLabel : "< previous",
    previousPageLinkClass : "yui-pg-previous", // default

// Options for NextPageLink component
    nextPageLinkLabel : "next >", // 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.  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 Ex.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     : Ex.data.areacodes[recs[0]].state,
            end       : Ex.data.areacodes[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
Ex.paginator = new YAHOO.widget.Paginator(Ex.config);

// Normal DataTable configuration
Ex.tableCols = [ {key:"state",    label:"State", minWidth: 150},
                 {key:"areacode", label:"Code",  width: 30}];

Ex.dataSource = new YAHOO.util.DataSource(Ex.data.areacodes, {
    responseType   : YAHOO.util.DataSource.TYPE_JSARRAY,
    responseSchema : {
        fields : ["state","areacode"]
    }
});

// Pass the Paginator in the DataTable config
Ex.tableConfig = {
    paginator : Ex.paginator,
    caption   : 'Area Codes by State'
};

Ex.dataTable = new YAHOO.widget.DataTable('tbl',
    Ex.tableCols, Ex.dataSource, Ex.tableConfig);

});

CSS


1	#demo {
2	width: 525px;
3	}
4	#pag {
5	display: inline;
6	float: left;
7	width: 250px;
8	margin-top: 0;
9	}
10	#pag a {
11	color: #0000de;
12	text-decoration: underline;
13	padding: .5ex 0;
14	}
15	#pag label {
16	display: block;
17	margin: 1ex 0;
18	}
19	#pag p {
20	margin: .25ex 0;
21	}
22
23	.yui-skin-sam #pag .yui-pg-pages {
24	display: block;
25	}
26	.yui-skin-sam #pag .yui-pg-page {
27	display: block;
28	background-color: #f1f6f7;
29	background: transparent;
30	border: none;
31	white-space: normal;
32	}
33	.yui-skin-sam #pag .yui-pg-current-page {
34	padding: .5ex 0;
35	background-color: #ffe;
36	font-style: italic;
37	}
38	.yui-skin-sam #pag .yui-pg-current {
39	margin: 0;
40	white-space: normal;
41	font-weight: bold;
42	font-size: 113%;
43	}
44	.yui-skin-sam #demo .yui-dt caption {
45	margin: 0.2em 0 0;
46	color: #e76300;
47	font-weight: bold;
48	}
	view plain \| print \| ?

Configuration for This Example

You can load the necessary JavaScript and CSS for this example from Yahoo's servers. Click here to load the YUI Dependency Configurator with all of this example's dependencies preconfigured.

YUI Logger Output:

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

Reload with logging
and debugging enabled.

Paginator Examples:

More Paginator Resources:

User's Guide (external)
API Documentation