jQuery Pagination Plugin
Description
The jQuery Paging plugin aims to be as simple as possible by a native callback design, which in turn allows to design a pagination navigation in almost every feasible variation.
Usage
Include the jquery.paging.min.js in your website and start working. There are no styles shipped with the library, it all depends on your needs and the library only does the link calculations and event management for you, plus a few extra things.
In order to use the Paging plugin, you're done by defining the following simple snippet:
$(".pagination").paging(1337, { // make 1337 elements navigatable format: '[< ncnnn! >]', // define how the navigation should look like and in which order onFormat() get's called perpage: 10, // show 10 elements per page lapping: 0, // don't overlap pages for the moment page: 1, // start at page, can also be "null" or negative onSelect: function (page) { // add code which gets executed when user selects a page, how about $.ajax() or $(...).slice()? console.log(this); }, onFormat: function (type) { // Gets called for each character of "format" and returns a HTML representation switch (type) { case 'block': // n and c return '<a href="#">' + this.value + '</a>'; case 'next': // > return '<a href="#">></a>'; case 'prev': // < return '<a href="#"><</a>'; case 'first': // [ return '<a href="#">first</a>'; case 'last': // ] return '<a href="#">last</a>'; } } });The strength of the library is that every parameter you would need is pre calculated and accessable via the this-object inside the callbacks. The most important part is the nncnn-block.
Options
- perpage: The number of elements per page
- page: The current page to start on
- format: A format string, look at Format
- lock: Boolean to lock/disable the pager for a while (see examples/lock.html)
- lapping: The number of elements to overlap over the coming pages, see.
- circular: Boolean if next/prev buttons are allowed to go circular
- stepwidth: Number of steps prev/next has to go. Default=1. =0 Gives blockwise steps
- onClick: Raw callback to be called instead of the
onSelectprecedure (see examples/onclick.html) - onFormat: Called for every
formatdirective. See Format - refresh:
timeoutandurlto be called periodically for updates. - onRefresh: Callback to be called for every refresh interval. (see jquery.paging.js)
onSelect Callback
Every onSelect callback gets a lot of pre-calculated information on the this object:
- number: The number of elements, configured
- lapping: The number of elements overlapping, configured
- pages: Number of pages
- perpage: Number of elements per page
- page: Current page on
- slice: Two element array with bounds to slice elements on the current page (see examples/slice.html)
The return code of onSelect indicates if the link of the clicked format element should be followed (otherwise only the click-event is used)
Format
The "format"-parameter defines how the layout should look like. The string is processed character by character from left to right. For each character, the onFormat-callback is called and a final output string is generated and applied to the selected container.
n = number c = current
A string "nncnn!" handles several definitions at once: How many digits to show? 5 by the length of the block. Where to show the currrent page in the set? Always at the beginning? "cnnnn". Always at the end? "nnc". Always in the middle? "nncnn". The exclamation mark in the initial example means that always 5 digits will be printed. All inactive elements have a "this.active" set to false.
Additionally, there are other format-tokens like "<" and ">" for prev and next, "[" and "]" for first and last, "." and "-" for simple text replacements and "q" and "p" in order to build previous and next-blocks. A more of examples can be found on my blog (link below).
Build your own paginator!
jQuery paging is just a small framework. You can use it as the calculation base of your own paginator. In the file easy-paging.html you'll find a small example plugin, which uses jQuery Paging to make a typical HTML based paginator work:
<ol id="paging"> <li>Prev</li> <li>Page #n</li> <li>Page #n</li> <li>Page #c</li> <!-- current element will be here --> <li>Page #n</li> <li>Page #n</li> <li>Page #n</li> <li>Page #n</li> <li>Next</li> </ol> $("#paging").easyPaging(1000, { onSelect: function(page) { console.log("You are on page " + page + " and you will select elements "+(this.slice[0]+1) + "-" + this.slice[1]+"!!!"); } });Ajax Select Callback
function onSelectCB(page) { $.ajax({ "url": '/data.php?start=' + this.slice[0] + '&end=' + this.slice[1] + '&page=' + page, "success": function(data) { // content replace } }); }Slice Select Callback
function onSelectCB(page) { var data = this.slice; content.slice(prev[0], prev[1]).css('display', 'none'); content.slice(data[0], data[1]).css('display', 'block'); prev = data; }Using cookies
$(".pagination").paging(1337, { format: '[< ncnnn! >]', perpage: 10, page: getCookie("current") || 1, onSelect: function (page) { setCookie("current", page) console.log(this); }, onFormat: onFormatCB });Lock the pager
It's sometimes necessary to lock the pagination, because you want to disable the navigation. You can use setOptions to disable the navigation like this:
var paging = $(".pagination").paging(1337, { format: '[< ncnnn! >]', onSelect: function (page) { // onSelect is called for locked pagers as well, but nothing happens, except this: if (page === 0) { console.log("Pager was clicked, while it is disabled!"); return; } // ... rest }, onFormat: onFormatCB }); // Lock the pager paging.setOptions({lock: true}); // Unlock the pager paging.setOptions({lock: false}); Further examples and documentation
For further details and code examples take a look at the demonstration and documentation page on:
http://www.xarg.org/2011/09/jquery-pagination-revised/
Build
The library is aggressively size optimized and works best with Closure-Compiler Advanced mode.
License
Copyright (c) 2013, Robert Eisele Dual licensed under the MIT or GPL Version 2 licenses.
