Client-Side Table Pagination Script

Why the need for a client-side solution?

There are times when a server-side/Ajax based table pagination solution isn’t possible (for example, if using static HTML pages or if you just don’t have access to the server-side scripting language). This script attempts to fill the need for a pagination solution in these “worst case scenarios”.

At a glance…

• Unobtrusive and nameSpace friendly
• Supports the pagination of multiple tables on the same page
• No JavaScript knowledge required, all parameters are passed within the table’s className
• Two pagination lists created for each table, the first positioned above the table and the second positioned below
• If required, the pagination lists can be positioned within a wrapper element of your choice
• A JavaScript callback function (or Object.method) can be declared, called immediately after a new page is shown by the script
• It’s keyboard accessible

What this is not…

This is not an excuse to push a 5000 line table to the client! As noted earlier, the script was developed for “worst case scenarios” and if at all possible, you should use an Ajax or simple server-side pagination solution instead.

The pagination algorithm

The pagination system attempts to adhere to the “rules of good pagination” detailed within KuraFire’s pagination 101 article.

In brief…

• First and Last links created where applicable
• Next and Previous links created where applicable
• The current page is intelligently centered
• The current page is easily identifiable
• Large clickable areas used (although this is more a styling issue)
• No underlines used (again, more of a styling issue)
• First and Last links positioned on the outside of the list

Configuration parameters

There are three configuration parameters that can defined within the table’s className; the first being “paginate-N”, where N represents an integer value that tells the script how many table rows make up a “page” – this is a compulsory class as without it, no pagination list is created.

The second (optional) parameter is “max-pages-N”, where N represents an integer value that tells the script the maximum number of numbered pagination buttons to show on screen.

The third and final parameter, used should you wish to Zebra-Stripe the table, is “rowstyle-X”; where X represents a className to give to each alternate row within each page. For example, the className “rowstyle-alt” will mean each alternate table row is given the className “alt”.

Not declaring the “max-pages-N” parameter

In this case, all of the numbered buttons will be shown on screen at once and so the first/last buttons are not created as logically, they are not required.

Positioning the lists

By default, the lists are inserted directly before and directly after the table within the DOM. Should you wish to have the lists positioned elsewhere, create a wrapper DIV for the list you wish to position and give the DIV an id of the form “X-paginationListWrapTop” or “X-paginationListWrapBottom”, where X represents the ID of the associated table.

The callback function

Should the function “paginationCallback” exist, it is called after a new page is displayed by the script; with the ID of the table passed in as an argument.

Stipulating Object.methods or bespoke JavaScript functions as a callback

You may wish to use an Object.method or a bespoke JavaScript function as a callback, to do this, just add the following class to the table’s className:

The className paginationcallback-XXX stipulates a function that will be called after the pagination gets redrawn, where XXX should be replaced with the name of the function in question.

Object.methods can be stipulated by converting the “dots” (i.e. the full-stops) to minus signs (-); for example, the className “paginationcallback-myObject-myMethod” will tell the script to call the “myMethod” method of the JavaScript Object “myObject” e.g. myObject.myMethod();

Filtering the table data

Should you be using a function to filter the table data i.e. to remove table rows that do not fall within the filter rules; just make sure your filter script adds the className “invisibleRow” to each hidden TR node and then call the tablePaginater.init method, passing in the ID of the table just filtered.

The script will then recalculate and redraw the pagination list for the table in question.

An example of this can be viewed within the pagination demo.

HTML structure

The script creates HTML of the following format:

  
 <div className=“fdtablePaginaterWrap”>
   <ul id=“theAssociatedTableId-tablePaginater[Clone]”>
     <li><a … ><span>«</span></a></li>
     <li><a … ><span>‹</span></a></li>
     <li><a … ><span>1</span></a></li>
     <li><a … ><span>2</span></a></li>

     ...     

     <li><a … ><span>N</span></a></li>
     <li><a … ><span>&rsaquo</span></a></li>
     <li><div … ><span>»</span></div></li>
   </ul>
 </div>
  
  

Note: I understand that some of you may question the use of the extra SPAN element created as a child of each link but it’s there in order to give you one more hook in which to style the list.

List styling

The lists have been styled using display:table and display:table-cell for the demo, with alternative styles passed to Internet Explorer using conditional comments. This means I was able to center the pagination “buttons” without resorting to the use of negative margins on the wrapper DIV (which can cause scrollbar and overflow problems under certain conditions).

I’ve tested the demo styles in Internet Explorer 6 & 7, FireFox 2, Opera 9 and Safari 3 (Windows).

Keyboard accessibility

As the list is recreated each time a new page is called, the “focus” on the current button is lost (as the element is removed from the DOM and a new element created). The script attempts to programmatically refocus on the appropriate button as soon as the new list is created (and I’m hoping that screen-readers etc are clever enough to indicate the new focus event to the user).

I would appreciate some real-world screen-reader testing though so, If anyone has access to a screen-reader and can confirm that the refocus event is indicated to the user, I would be much obliged.

The License

The script is released under a creative commons Attribution-ShareAlike 2.5 license. Should you use the script within a commercial context please think about clicking the payPal donate button – it’s certainly not an obligation but it would most certainly put a smile on my face.

Demo, downloads and updates

Tested in Internet Explorer 6, Opera 9.01, Safari 3.0.3 (Windows) and Firefox 2.

View the pagination demo (which also demos the tablesort script) or download the 11k uncompressed JavaScript source code (you can compress the script down to a 6k by using Dean Edwards Packer if the size is an issue).

27/12/2007 (v1.6):

• Embedded table support
• Demo changed to use callback function

19/12/2007 (v1.5):

• Refactored the script to take bespoke filter functions into account i.e. the “invisibleRow” className
• Better integration with the tablesort script

15/11/2007 (v1.4):

• Fixed a Safari2 bug

23/10/2007 (v1.3):

• Rewrote the pagination algorithm
• Added code to refocus on the appropriate button
• Made the show/hide portion of the code only show/hide the necessary table rows (without traversing through the entire table)

19/10/2007 (v1.2):

• Added the Callback functionality
• Added the Next/Previous buttons to each pagination list
• Added support for multiple tables on the same page
• Added the ability to position each of the pagination lists within a predefined wrapper element