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="#">&gt;</a>';
		case 'prev': // <
			return '<a href="#">&lt;</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 onSelect precedure (see examples/onclick.html)
onFormat: Called for every format directive. See Format
refresh: timeout and url to 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.

joev1 / jQuery-Paging