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 page: {JumpToPageDropdown}</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	firstPageLinkTitle : "First Page", // default
96
97	// Options for LastPageLink component
98	lastPageLinkLabel : ">>",
99	lastPageLinkClass : "yui-pg-last", // default
100	lastPageLinkTitle : "Last Page", // default
101
102	// Options for PreviousPageLink component
103	previousPageLinkLabel : "< previous",
104	previousPageLinkClass : "yui-pg-previous", // default
105	previousPageLinkTitle : "Previous Page", // default
106
107	// Options for NextPageLink component
108	nextPageLinkLabel : "next >",
109	nextPageLinkClass : "yui-pg-next", // default
110	nextPageLinkTitle : "Next Page", // default
111
112	// Options for PageLinks component
113	pageLinksContainerClass : 'yui-pg-pages', // default
114	pageLinkClass : 'yui-pg-page', // default
115	currentPageClass : 'yui-pg-current-page', // default
116
117	// Display a maximum of X page links. Use
118	// YAHOO.widget.Paginator.VALUE_UNLIMITED to show all page links
119	pageLinks : YAHOO.widget.Paginator.VALUE_UNLIMITED,
120
121	// Create custom page link labels
122	pageLabelBuilder : function (page,paginator) {
123	return Ex.buildPageLabel(paginator.getPageRecords(page));
124	},
125
126	// Create custom page link titles (for accessibility)
127	pageTitleBuilder : function (page, paginator) {
128	return "Show content for page " + page;
129	},
130
131	// Options for RowsPerPageDropdown component
132	rowsPerPageDropdownClass : "yui-pg-rpp-options", // default
133	rowsPerPageOptions : [
134	{ value : 20, text : "small" },
135	{ value : 40, text : "medium" },
136	{ value : 100, text : "large" }
137	],
138
139	// Options for CurrentPageReport component
140	pageReportClass : 'yui-pg-current', // default
141
142	// Provide a key:value map for use by the pageReportTemplate.
143	// Unlikely this will need to be customized; see API docs for the
144	// template keys made available by the default value generator
145	pageReportValueGenerator : function (paginator) {
146	var recs = paginator.getPageRecords();
147
148	return {
149	start : Ex.data.areacodes[recs[0]].state,
150	end : Ex.data.areacodes[recs[1]].state
151	};
152	},
153
154	// How to render the notification of the Paginator's current state
155	pageReportTemplate : '{start} - {end}'
156	};
157
158	// Create the Paginator for our DataTable to use
159	Ex.paginator = new YAHOO.widget.Paginator(Ex.config);
160
161
162	// Normal DataTable configuration
163	Ex.tableCols = [ {key:"state", label:"State", minWidth: 150},
164	{key:"areacode", label:"Code", width: 30}];
165
166	Ex.dataSource = new YAHOO.util.DataSource(Ex.data.areacodes, {
167	responseType : YAHOO.util.DataSource.TYPE_JSARRAY,
168	responseSchema : {
169	fields : ["state","areacode"]
170	}
171	});
172
173	// Pass the Paginator in the DataTable config
174	Ex.tableConfig = {
175	paginator : Ex.paginator,
176	caption : 'Area Codes by State'
177	};
178
179	Ex.dataTable = new YAHOO.widget.DataTable('tbl',
180	Ex.tableCols, Ex.dataSource, Ex.tableConfig);
181
182	});
	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 page: {JumpToPageDropdown}</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
    firstPageLinkTitle : "First Page",   // default

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

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

// Options for NextPageLink component
    nextPageLinkLabel : "next >",
    nextPageLinkClass : "yui-pg-next", // default
    nextPageLinkTitle : "Next Page",   // 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));
    },

// Create custom page link titles (for accessibility)
    pageTitleBuilder        : function (page, paginator) {
        return "Show content for page " + 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 Library Examples: Paginator: Configuring the Paginator

Content in a DataTable

Add Pagination

Create the DataTable and render

Full Code Listing

JavaScript

CSS

Configuration for This Example

YUI Logger Output:

Logger Console

Paginator Examples:

More Paginator Resources:

YUI Library Examples: Paginator: Configuring the Paginator

Paginator: Configuring the Paginator

Now showing page: 1234567891011121314151617

Directory

Content in a DataTable

Add Pagination

Create the DataTable and render

Full Code Listing

JavaScript

CSS

Configuration for This Example

YUI Logger Output:

Logger Console

Paginator Examples:

More Paginator Resources:

Now showing page: