The Pagination jQuery Plugin allows users to easily create generic pagination elements, which allows the end user to create grouped sets of pagination controls, regardless of the content they're controlling. The benefit is that you can easily swap between different sets of data without having to regenerate the pagination controls. The downside is that the pagination controller doesn't contain code to automatically render your data. You will still need to implement your own display functionality. This is covered in the Rendering article of these documents.
Each page needs to have two basic things to create pagination controllers:
<body>
<div id="my-controller"></div>
<div id="my-content-area"></div>
</body>
Then, we need to set up our pagination controller and a callback to render content.
// Some demo content to seed in
var content = [
'Some article text...',
'More article text...',
'Last article text'
];
// Then, we need to set up the controller
jQuery('#my-controller').pagination('some-arbitrary-group-name', {pages: content.length},
// And a callback
function (group){
group; // "some-arbitrary-group-name"
this; // The current 0 based page number for the content. (0 is the first page, 1 is the second, etc).
jQuery('#my-content-area').html( content[this] );
}
)
The Pagination plugin provides a single interface with jQuery for creating and managing any given pagination controller.
jQuery( '.pagination-controller' ).pagination( ... );
The following options can be set on a controller by controller basis, or, their default values can be updated to make the user-defined settings the basline for all controllers.
// Edit Defaults
jQuery.pagination.defaults[ param ] = value;
// Set for Group
jQuery( '.pagination-controller' ).pagination( 'somegroup', {param: value} );
pagination( group, options, [ callback] )| Option | Type | Description | Default |
|---|---|---|---|
| pages | Integer | The total number of pages to paginate over. | 0 |
| current | Integer | The current page. | 0 |
| numPaddingDigits | Integer | If you want to always display certain digits to the left and right of the controls, you must set how many digits you want on either side of the controls. | 0 |
| Example: 1 2 ... 5 6 7 8 ... 19 20 | |||
| maxDigits | Integer | Maximum number of digits to display in the controller at any given time. | 8 |
| Example: ... 3 4 5 6 7 8 9 10 ... | |||
| text | Object | The text to use for the arrows and spacers. | Below |
| Defaults: |
text: {
first: '<<',
last: '>>',
next: '>',
previous: '<',
spacer: '...'
}
|
||
| templates | Object | The HTML Snippets which form the controls. | Below |
| Defaults: |
templates: {
first: '<a class="ui-pagination-control ui-pagination-decrement ui-pagination-first" href="#"></a>',
last: '<a class="ui-pagination-control ui-pagination-increment ui-pagination-last" href="#"></a>',
next: '<a class="ui-pagination-control ui-pagination-increment ui-pagination-next" href="#"></a>',
previous: '<a class="ui-pagination-control ui-pagination-decrement ui-pagination-last" href="#"></a>',
number: '<a class="ui-pagination-control ui-pagination-digit" href="#"></a>',
spacer: '<span class="ui-pagination-spacer"></span>'
}
|
||
pagination( 'renumber', options, [ group] )During a renumber operation, passing in {page: numOfPages} will renumber the controls, and display the new number of pages which can be paged through.
If the current page is out of bounds after a renumber (current page is 10, renumber is 5 pages total), the current page will be set to the last page in the set.
pagination( 'callback', callback, [ group] )Allows the user to define a new callback to be triggered when a page is selected.
If the controller group has a callback already, it will be replaced.
pagination( 'force-change', options, [ group] )During a force-change, passing in {current: newCurrentPage} will set the current page to the provided value.
If the force-change page is out of range of the provided value, it will default to the first or last page in the set (depending if the number is lower than zero or greater than the total number of pages, respectively).
The pagination plugin doesn't handle the rendering of content, as there are a number of sources and methods by which content can be provided. Instead, the plugin merely renders the controls for the number of pages, and fires a callback event, which must be user defined. This is to allow the plugin to function seamlessly, regardless of what content is provided.
function(group){
group; // The group currently firing the callback
this; // The current page number
}
These examples are meant to illustrate some choices the developer has for fetching and rendering content. These are, by no means, the only ways to seed content, but rather, some common methods.
var content = [ ... ];
function myCallback(group){
jQuery('#my-content-area').html( content[ this ] );
}
jQuery('.my-selector').pagination('group-name', options, myCallback);
function myCallback(group){
jQuery.get('/path/to/url.php', {page: this}, function(data){
jQuery('#my-content-area').html( data );
}, 'html')
}
jQuery('.my-selector').pagination('group-name', options, myCallback);
There are a number of display options available to help you style the pagination controls to match your site. Through the use of plugin options and CSS, the ways to render the pagination plugin are nearly endless.
The Pagination controls can be tweaked a number of different ways. This is a quick explanation of how the display system works to create the pagination controls, from left to right.
| Type | Description | Default Characters/Example |
|---|---|---|
| First Arrow | An arrow which sets the current page number to 0.<< | |
| Previous Arrow | An arrow which decrements the current page number by 1. | < |
| Padding Digits | If a number of padding digits are specified, they will be created here. Padding digits are always visible, regardless of what the current page number is. (Note, if you set the number of padding digits to "2", there will be 2 padding digits on the left, and two on the right). The numbers in brackets are the padding digits. | [1] [2] ... 6 7 8 ... [14] [15] |
| Spacer | When the current page is farther away from the left-end of the pages, a spacer is displayed to indicate the the bounds extend past what is visible. (Example, if you have a 4 digit display max, and you're on page 5 of 10, you would see the following.) The ellipses in the brackets are the spacers. | [...] 5 6 7 8 [...] |
| Display Digits | Displays the maximum number of digits possible, or the entire set of pages, if the max is greater than or equal to the number of pages. (Example, if you have a 4 digit display max, and 3 pages of content, you would only see 3 digits. If you have a 4 digit display max, and 10 pages of content, the closest digits would be show.) The number in the brackets are the display digits. | ... [3] [4] [5] [6] ... |
| Spacer | When the current page is farther away from the right-end of the pages, a spacer is displayed to indicate the the bounds extend past what is visible. (Example, if you have a 4 digit display max, and you're on page 5 of 10, you would see the following.) The ellipses in the brackets are the spacers. | [...] 5 6 7 8 [...] |
| Padding Digits | If a number of padding digits are specified, they will be created here. Padding digits are always visible, regardless of what the current page number is. (Note, if you set the number of padding digits to "2", there will be 2 padding digits on the left, and two on the right). The numbers in brackets are the padding digits. | [1] [2] ... 6 7 8 ... [14] [15] |
| Next Arrow | An arrow which increments the current page number by 1. | > |
| Last Arrow | An arrow which sets the current page number to the final page in the set. | >> |
Every HTML component rendered by the plugin has some default CSS classes. If you change the templates which the plugin uses to render these components, you can add custom classes, overwrite the default classes, etc. These are the default classes used, and what components they're associated with.
| Class | Description |
|---|---|
| ui-pagination | Automatically applied to the container for the controls. If this class does not exist on an element, a new pagination control can be created within it. However, if the element already contains this class, it's assume it already contains a pagination control, and thus will prevent creation of a new controller. |
| ui-pagination-anchor | Automatically applied to any digits on the left or right of the controls created as padding digits. |
| ui-state-disabled | Applied to the currently selected page, and the first/previous arrows when on the first page, as well as the next/last arrows when on the last page. |
| ui-pagination-spacer | The default class applied to a <span></span> tag for the spacer between displayed digits and extended content. |
| ui-pagination-control | This class must be present on any links/buttons which can be clicked to trigger a page change event. This class is used as a live() event trigger for an onClick callback. If this class is not applied to your HTML snippets, the plugin will not function properly. |
| ui-pagination-digit | This class should be present on any HTML snippet which will display a clickable number representing a page. |
| ui-pagination-decrement | This class indicates that the element is a decrementer control, such as the first/previous arrows, and should decrement the current page number by one, or set it to zero. |
| ui-pagination-increment | This class indicates that the element is an incrementer control, such as the next/last arrows, and should increment the current page number by one, or set it to the last page in the set. |
| ui-pagination-first | This class indicates that the element should set the current page number to 0. |
| ui-pagination-previous | This class indicates that the element should decrement the current page number by 1. |
| ui-pagination-last | This class indicates that the element should set the current page number to the last page in the set. |
| ui-pagination-next | This class indicates that the element should increment the current page number by 1. |
The class structures are designed to facilitate easy modification of the display. For instance if you want to hide both the first/previous arrows and the last arrow, you could set:
.ui-pagination-decrement, .ui-pagination-last { display: none; }
One feature of the Pagination plugin is the ability to use a single set of controllers to handle multiple groups of content without needing to recreate controls for each set. Lets say, for example, you needed to create a pagination content area where you pull in news articles from AJAX. Take the following HTML:
<div class="article-menu">
<a id="load-article-one" href="#" title="Load the first article, with 4 pages">Article 1</a>
<a id="load-article-two" href="#" title="Load the first article, with 2 pages">Article 2</a>
<a id="load-article-three" href="#" title="Load the first article, with 1 pages">Article 3</a>
<a id="load-article-four" href="#" title="Load the first article, with 8 pages">Article 4</a>
</div>
<div class="pagination-controls"></div>
<div id="pagination-content"></div>
<div class="pagination-controls"></div>
If we apply this Javascript, we can easily use this one content area to display the paginated articles in pieces, without regenerating the controls.
jQuery(function(){
var articlePages = [4, 2, 1, 8],
currentArticle = 0,
controls = jQuery('.pagination-controls'),
content = jQuery('#pagination-content');
// Set up the article onClicks
jQuery('#load-article-one').click(function(){ useArticle(1); })
...
jQuery('#load-article-four').click(function(){ useArticle(4); })
// Set up the pagination callback
function myCallback(){
jQuery.get('article.php', {page: this, article: currentArticle}, function(data){
content.html( data );
}, 'html');
}
// Set up the useArticle Callback
function useArticle(num){
currentArticle = num;
controls.pagination('renumber', {pages: articlePages[ currentArticle], current: 0});
}
// Finally, create the controls
controls.pagination('my-article-group', {pages: articlePages[ currentArticle]}, myCallback);
})
The pagination plugin uses a set of 3 live() events to handle all it's internal logic. Each of these events are bound to a ui-pagination-control css class. The events triggered are:
| Event | Description |
|---|---|
| disable | Applies the CSS class ui-state-disabled to the control, preventing it from being clicked. This is applied to the page we're currently displaying, or the first/previous next/last arrows when the current page is the first, or last, respectively. |
| enable | Removes the CSS class ui-state-disabled from the control, allowing it to be clicked. This is triggered when the page changes, and fired on the previous page. |
| click | Processes the logic to determine what kind of control was clicked. Checks the elements .data('pagination-type') property, which should either be a digit representing a page number, or the words "first","last","next", or "previous". |
Please visit: http://eric.garside.name/demo.html?p=pagination
The current version of the Pagination plugin can be downloaded from Google Code
You can also checkout the subversion repository for the plugin with the following command:
svn checkout http://jquery-curator.googlecode.com/svn/trunk/ jquery-curator-read-only