A tutorial for service.paginator.jquery - Pagination / Paginator Component

November 14, 2014

Overview

service.paginator.jquery is a lightweight javascript plugin (under 6 kB minified) that allows pagination for all sorts of lists. It is different from a lot of other pagination/paginator plugins as it only deals with the presentation aspects of the pagination controls (the 'next', 'previous' and 'page' elements within a paginator, providing a callback when a user clicks on one of them. It is intentionally not involved in the actual rendering of the list items. That is left over (through a callback) to another javascript service which the programmer has to implement itself or can get from service.itemslist.jquery (a jquery plugin to present an AJAX-invoked server-side list).

You can customize the presentation of the paginator in a number of ways:

• The number of 'page number' elements which the user can click/touch can be specified.
• The visual presentation of the 'Next', 'Previous' and 'Page' elements is customizable through CSS.
• You can put the paginator at any place in the DOM (it doesn't need to be underneath the list it serves).

The plugin belongs to a family of other small-weight plugins I developped that intentionally only provide a well-bounded minimum set of services. Putting them together one however can have a very customizable platform that can be used in a variety of projects. From my experience the one-does-it-all type of plugin actually never gives me exactly what I want; it needs modifications, it is hard to customize, very difficult to style, etc. So, I like to reduce a plugin to its bare minimum and hook up other, again mini-service plugins to the overall solution.

Demo

2 demo's are provided:

• A paginator for a client-side list. Click here for this demo.
• A paginator for a server-side list (using AJAX to retrieve list items). Click here for the demo.

Download

You can download the latest version of the plugin at GitHub.

Usage

To use the plugin start with adding the following in your header section:

<link rel="stylesheet" type="text/css" href="~/Content/lib/jquery.services.paginator-1.0.0/jquery.services.paginator.css" />
<script src="~/Content/lib/jquery.services.ontouchclick-1.0.0/jquery.services.ontouchclick.min.js"></script>
<script src="~/Content/lib/jquery.services.paginator-1.0.0/jquery.services.paginator.min.js"></script>

In your html, add the following at the place where you want the paginator to appear. If you take the .css files that comes with the paginator then the paginator fills the parent block width a width of 100%.

<div id="items">
<!-- Here comes the list -->
</div>
<div id="itemsPaginator">
<!-- Here comes the paginator -->
</div>

Finaly, write some javascript to assign the plugin to the html element as shown next:

<script type="text/javascript">

  var _maxItems = 100;
  var _maxPages = 5;
  var _itemsCount = 500;
  var _skipCount = 0;
  // Execute on page load
  $(function () {
    // Initialize paginator plugin
    $('#itemsPaginator').paginator({
      itemsPerPage: _maxItems,
      itemsCount: _itemsCount,
      activePageIdx: _skipCount / _maxItems,
      maxPagesShown: _maxPages,
      onPageRequest: function (el, pageIdx) {
        // Tell 'itemslist' plugin to load the page items
        $('#items').itemslist('getItems', { skipCount: pageIdx * _maxItems, initPaginator: false });
      }
    });
  });

</script>

Apart from some initialization parameters (like: itemsPerPage, itemsCount, etc.) the key callback function for which you will have to provide an implementation is onPageRequest. This callback is called when the user presses/touches the paginator's Next, Previous or one of the Page controls that are shown in the middle of the paginator. You have to provide some Javascript code to retrieve the list items that correspond with the requested page (indicated by pageIdx). As you can see in the code above, the example works for this with the service.itemslist.jquery plugin that is told to retrieve and insert the requested page server-side using AJAX.

API

Initialization method

[jqObject(s)].paginator(options)

The options argument is a javascript associative array (an object with key/value pairs) that allows you to initialize the plugin with property values that are different from the default values assigned by the plugin itself.

Properties

itemsCount

Type: Integer
Default: 0
Specifies the total number of items in the list for which the plugin must do pagination.
The count can be re-defined at any time by calling the paginator's "reInit" method.

---

activePageIdx

Type: Integer
Default: 0
Specifies the page that is to be made active. It is defined using an index; i.e. 0 is page 1, 1 is page 2, etc.
The index can be re-defined at any time by calling the paginator's "reInit" method

---

maxPagesShown

Type: Integer
Default: 5
This parameter specifies how many page 'numbers' have to be shown on the paginator. Note that the first and last page will allways be shown. So, if 'maxPagesShown' is set to 7 and you have 20 pages and the active page is 10, then the page numbers show up as follows: 1 .. 8 9 10 11 12 .. 20.

---

itemsPerPage

Type: Integer
Default: 5
The maximum number of items that must be shown within each page of the list.

---

allowKeyNavigation

Type: Boolean
Default: true
When set to true the paginator will also request the next/previous page when the user presses the right/left navigation keys on the keyboard.

---

onPageRequest

Signature: onPageRequest: function (el, pageIdx) { }
el: The paginator's jquery plugin object
pageIdx: An integer denoting the index number of the requested page.
This callback is called when the user selects a given page or clicks/touches the 'Next' and 'Previous' elements.
You must write some Javascript code here to replace the current items in the list with a new set of items (associated with the page that is defined by pageIdx).

Other methods

reInit

Signature: [jqObject(s)].paginator('reInit', { itemsCount: count, activePageIdx: index });
itemsCount: count - Count must be an integer specifying the overall size of the items list.
activePageIdx: index - An integer value defining the index number of the active page.
You can invoke this method when you want to re-initialize the paginator with an updated value for the size of the list and/or force the paginator to change the active page.

Comments

comments powered by Disqus