The WebApp Wizard Web development made magical

Documentation

Usage

JS

To create a paginated list, just do the following:

$('.my_list').universalPaginate(options);

You can also call some methods using the following syntax:

$('.my_list').universalPaginate('methodName', options);

HTML

Just any container that will receive your items. That includes div, ul, dl, table... Just anything!

CSS

A default CSS is given to make it a bit easier on the eyes, but there's no magic, if you want to integrate it nicely, you will probably have to customize it a little.

JSON

Universal Paginate expects your server to send him some JSON formatted data. You probably wonder what your server-side script should return. You will find a helper class in the package which will take care of this formatting for you. You can use it as provided or copy-paste the code bits you are interested in.
The JSON output should look like this (assuming that you requested items starting at index 20, with 10 items by page):

{
   "startIndex": "20",
   "nbItemsByPage": "5",
   "nbTotalItems": "145",
   "data": [
      {"id":"first object id","other_property":"other value"},
      {"id":"second object id","other_property":"other value"},
      {"id":"third object id","other_property":"other value"},
      {"id":"fourth object id","other_property":"other value"},
      {"id":"fifth object id","other_property":"other value"},
   ]
}

The nbTotalItems is the total number of items in your data set (not restricted to the page you requested). It is used to produce the pagination links, amongst others.

Options

The plugin provides several options so that you can make it work the way you want. Here there are:

  • nbItemsByPage: 10
    The number of items by page
  • nbPagesDisplayed: 10
    The number of page links to display before the clipping occurs
  • itemTemplate: '<li>${value}</li>'
    Probably the most important part, this is the template for your items. It supports the jQuery Templates plugin syntax
  • dataUrl: null
    The URL to fetch the data from
  • nbPreloadedPages: 2
    The number of pages to pre-load, before and after the current page. For instance, with the default value (2) loading page 4 will also load pages 2, 3, 5 and 6. A great speed improvement can be achieved.
  • refreshInterval: null
    In milliseconds, the time elapsed between two data refreshes. null means no refresh at all.
  • universalPaginateClass: 'universal_paginate'
    The default prefix for Universal Paginate specific classes and other things
  • controlsPosition: ['top', 'bottom']
    The position where the controls (number of items by page and page links) will be appended. Top or bottom of the list
  • paginationNavigationArrows: [true, false]
    Whether or not to display "prev" and "next" arrows for page navigation
  • allowItemsByPageChange: [true, false]
    Whether to give the user or not the ability to change the number of items to display on each page
  • displayItemsByPageSelector: [true, false]
    Whether to display or not a selector to allow the user to change the number of items by page
  • itemsByPageText: 'Items by page'
    The default text displayed in front of the items by page selector
  • pageText: 'Page'
    The default text displayed in front of the page links list
  • nbItemsByPageOptions: [5, 10, 15, 20, 30, 60, 100]
    The possible options given to the user to customize the number of items displayed by page
  • headerElement: null
    If you want to append the controls (page links and number of items by page) to an existent element, just give a selector, DOM element or jQuery object of this element
  • noDataText: '<div>No data to display</div>'
    The text to display when there is no data to display
  • ajaxOptions: {}
    Some options that will be used in the get or post request when querying the server for data. The hash is the same as the one you would use with $.ajax() or $.ajaxSetup(). It will override the defaults that UP uses in the ajax requests. Allows, among others, to switch from get to post request.
  • onDataUpdate: function(data) {}
    This callback is triggered every time the plugin has fetched new data from the data source. The data is passed as a parameter

Methods

  • .universalPaginate('goToPage', pageId): go to a specific page. Page numbers (ids) start at 1
  • .universalPaginate('refresh', options): refresh the data. Options is a hash with two keys. The first, reInit (true or false) is to re-initialize the list completely. The display will return to page 1. The second key, data (hash), allows you to pass additional data to the get / post request that will query the server for data.
  • .universalPaginate('changeItemTemplate', newItemTemplate): allows you to change the template that will be used to render the data on-the-fly. It can be a selector or a jQuery object (same as for the plugin initialization).
Comments (13) Trackbacks (0)
  1. Your pagination plugin is the best. Simple and faster, the next week I give you the website to view your creation y action. Sorry for mi bad english…bye!!

  2. Must be more documentation about how data on server must be json formated before return.

  3. Hi Ksaveras,

    You’re right, there is a lack of documentation on this plugin, I should fix it. In the meanwhile, you can download it and have a look at the contents of the package : I included a PHP helper in the last version which will take care of the JSON formating for you.

  4. I like preload pages function, but if I set value to 0 on first page load, universal paginate makes 2 requests. then going between pages one request is done. Checked with firebug console

  5. Yes, that’s a normal behavior. In fact, the first request fetches only the first page (the page to be displayed), while the second one fetches several pages, based on the nbPreloadedPages setting.
    As a result, the first request is as fast as possible, providing the first set of data to the user really quickly, while the surrounding pages are fetched in the background.
    This allows pre-loading feature without speed loss on the first request (if we decide to load 5 pages at a time, the response will indeed be slower than if we ask only for 1 page).

  6. I had in mind that if I set nbPreloadedPages:0 (disable page preloading) first two requests are exactly same and not necesary to repeat same request because result will be the same.

  7. Feature request: would be handy to have controls (pagination at least) on top and on bottom

  8. Yep, that could be a great idea, especially when a large amount of items are displayed on a page. I’ll try to think about it on the next release.

  9. I’m having a massive problem with pagination refresh in IE7 & IE8. Any things I should be on the look out for in my code?

  10. That’s strange, I use this plugin on a website that is mainly used by IE7/IE8 users, and it works quite well.

    What do you mean by “massive problem with pagination refresh”? Are the pages refreshed or not, do they behave in a weird way? Or maybe it is just the navigation links?

  11. Hm, is there any way to hide the page selector as long as there’s only one page?

  12. Hi Phil,
    it’s not coded yet, but that would be a great idea. Unfortunately, I don’t think I’ll have time for this in the near future…
    But you can fork it on github and try to implement this.


Leave a comment

(required)

You can use basic HTML to enlighten your comments. If you want to post some code, please use the <pre> tag. You can also use syntax coloring by adding class="syntax [language]". <pre class="syntax js"> will color your code as if it was JS code for instance.

No trackbacks yet.