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
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();
The callback function data object
All callback functions are passed the following object as an argument:
{
"totalRows":[the table's total rowcount],
"currentPage":[the current page],
"rowsPerPage":[the number of rows per page],
"visibleRows":[an array of currently visible rows]
}
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.
Localisation
Should you wish to change the language used by the script when creating the title attribute of each pagination link (it defaults to English), just call the A.P.I. method changeTranslations, passing in an array of new translations to use; for example:
// change the language used by translating
// the following array values...
tablePaginater.changeTranslations([
"First Page",
"Previous Page (Page %p)",
"Next Page (Page %p)",
"Last Page (Page %t)",
"Page %p of %t"]);
Additionally, all occurances of %p get replaced with the appropriate page number and %t replaced with the total number of pages.
Creating a “Showing page X of Y” message
The script does not attempt to display any “textual” message – it just creates the pagination links. In order to show a message like the common “Showing page X of Y”, you will have to write a small JavaScript callback function that does the job for you.
The demo shows how this might be achieved – just look at the page source code to see the gory details.
The License
The script is released under a creative commons Attribution-Share Alike 3.0 Unported 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. If you need a dual license, just ask me politely.
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), download the 24k uncompressed JavaScript source code or the 12k YUI minified JavaScript source code
21/10/2008 (v2.0):
- Complete rewrite of the source code
- Callback functions now called using method.apply
- Callback functions now recieve a data object
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
Previous Comments ~
This is wonderful, Thank you.
This really works well with your table sort script and is a great concept for use with other tables as well.
@ Don: Hi Don, glad you like the script. I’ve rewritten the pagination algorithm since your comment was posted so you might like to take another look at the demo.
Regards,
Brian.
Brian,
I’m working on implementing some of your table scripts into a commercial project which required full A-grade browser support so I fixed the issue that was causing your table sort script to fail on Safari 2.
The parse error Safari was complaining about is likely affecting compatibility with all your scripts. I tried to find your email address on the site (and Google) like the closed comments form indicates, but couldn’t, so I’ll leave it here (it’s likely somewhat on-topic here anyway).
The basic problem is with your Object Notation.
Where you had:
addEvent: function addEvent(obj, type, fn, tmp) { ...
}
Safari (IMO, rightly) expects:
addEvent: function(obj, type, fn, tmp) { ...
}
The change had to be implemented for every function declared, but the script worked without any other change. There’s also a validation issue on the table itself (tfoot belongs below thead, not tbody; something I would never have expected, personally), which is an easy fix.
Feel free to email me if you want any further explanation with this/Safari checking of other scripts. I’m a big fan of the scripts; they’re saving me a tonne of effort, so I figured I’d repay the favour with Safari 2 compatibility :)
@ Kit Grose: Kit, you are a star! I can’t believe that Safari2 won’t accept named functions (it’s way better for debugging if the functions are named). I’ll have to do a lot of editing this weekend to make the scripts Safari2 compatible! As per usual, there’s a pint of Guinness in the virtual keg waiting for you…
Regards & many thanks,
Brian
No sweat. Glad I could help.
Means I feel slightly less guilty now if my boss can’t get a donation to you for the tablesort functions!
Hi,
thanks for this great stuff. My table ist sometimes reloaded from an tajax-request. If so, the pagination drop off and the hole table is displayed again.
If i type in the firebug-console “tablePaginater.init()” it is ok again. But the call of this init-funktion in my ajax-javascript don’t work. any ideas?
thanks in advance
@ Kit: Hi Kit, don’t feel guilty my man, you nailed the error and thats just fine with me…
@ Tribun: Hi Tribun, if your using Ajax then you shouldn’t require a client-side pagination script. What errors are you getting if you call the init method from the Ajax code?
I want to add a filter on the table. When a filter reduces the number of results, the pagination isn’t updated because rows are hidden and that’s ok. Is it possible to add a class on rows that won’t be “visible” for pagination instead of removing them ? (I want a sorter and a filter on this table). Thank you for these great scripts!!!
Hi Brian,
just wanted to let you know that i just uploaded your extremlly nice script as a TYPO3 extension in the TYPO3 Extension Repository:
http://typo3.org/extensions/repository/view/bm_tablesort/0.1.0/
write me a mail if you want me to do any changes…
thanks for the script,
seb
Brian, I haven’t visited you since our last contact about making the table sort 508 accessible. WOW, have you taken off on your table sort! Great job.
@ Aurélien: Hi Aurélien, I’m currently working on this (in fact, the code’s finished but I’m still testing it). The script assumes that hidden/filtered rows have been given the className “invisibleRow” and takes them into account when redrawing the pagination list…
@ Seb: Hi Seb and thanks for the inclusion in the typo projet!
@ Pat: Hi Pat, good to see ya back and I’m glad you like the script…
Regards,
Brian.
I found a little problem with the sorter and pagination. If the table has a table in a cell (without sorting and pagination), the sorter and the pagination don’t work well.
I thought about a class for every row in order to flag rows that are inclded in pagination calculation and sorting.
Have you encountered this bug?
Can you fix it or I have to do it by myself ?
Thank you
@ Aurelien: Hi Aurelien, I specifically haven’t tested for embedded tables as the tableSort was written with data tables in mind i.e. a flat table containing simple data. It takes too many clock cycles to test if a row is part of another table (even if testing if a certain className is present) and so I’ve not included it.
Update: I’ve changed the scripts to use the available rows/cells array which means it should be possible to use an embedded table.
Regards,
Brian
Hi Brian, happy to write back to you after a while (I am the one who fixed a bug in your stickies script, and then adapted it to make browser stickies in Opera, hope you can remember me).
Looking to your Client-Side Table Pagination Script, I had an idea: it would be very cool (and really useful) making a piece of code integrating a classic server-side/Ajax technique with your client-side script: I mean, in some parameter it should be possible to define “how many pages to store client-side” (say 5 pages), and show them with your script; but, when the user clicks on a page which is out of the range of the 5 pages loaded (or click-click-clicks on arrows until the page to show is out of the range of the 5) a “please wait while loading data…” message appears (with the classic loading “wheel”) and goes away when the needed 5 pages have been loaded (via Ajax).
I hope I’ve been clear enough: it would be nice if someone succeeds in making this sort of thing (if it does not already exist: cannot be sure, but I think not).
Hi,
newbie to css I don’t understand whot you mean with create a wrapper div for positionning de pagination list (ex. bottom)
Helpful example are welcome
Thanks
@ Antonio: hi Antonio, the guys over at particleTree have code for paginating tables.
@ Semiyi: Hi Semiyi, if I have a table whose id is “fd” then I can position both lists by creating two divs, one with an id of “fd-paginationListWrapTop” and another with an id of “fd-paginationListWrapBottom” (these divs can be positioned anywhere on the page) and the pagination lists will be created within the divs in question, not just above and below the associated table.
Brilliant script. Can’t thank you enough.
Hi,
These scripts are amazing. appreciate all the work you are doing here. i got the tablesort.js to work without a problem.
now i trying to incoporate the paginate.js. the sceipt creates the number for pagination, but they show up vertical instead of horizontal on my table.
@ Nuno: Hi Nuno, glad you like the script.
@ Rajan: Hi Rajan, it must be a problem with the CSS. Have you remembered to add the IE specific stuff using conditional comments?
Hi, I have a setup where a user can move a mouse over a marker on a map and the the related table entry is highlighted. The problem is that when you combine your tablesort + pagination scripts, you don’t know what page your entry will be on, as sorting will shuffle table rows around. To work around this issue I wrote the following function that will find and display the right page of a table row with a specified ID:
findAndShowPage: function(tblId, findId) { if(!(tblId in tablePaginater.tableInfo)) { return; }; var trs = tablePaginater.tableInfo[tblId].hook.rows; var cnt = 0; var reg = /(^|\s)invisibleRow(\s|$)/; for(var i = 0, tr; tr = trs[i]; i++) { if(tr.getElementsByTagName(“th”).length || (tr.parentNode && tr.parentNode.tagName.toLowerCase().search(/thead|tfoot/) != -1)) continue; if(tr.className.search(reg) == -1) { cnt++; }; if (tr.id == findId) { tablePaginater.tableInfo[tblId].currentPage = Math.ceil(cnt / tablePaginater.tableInfo[tblId].rowsPerPage); return tablePaginater.showPage(tblId); } }; }p.s. sorry about the formatting, not sure how to display the code properly w/o html
This may sound little dumb… but what needs to go into tableInfo as the parameter, because I have the requirement where I have more than table and I need to provide pagination for a specific table and which function should be called from client side(javascript) to initiate the pagination….pls let me know thanks , as other wise this is an excellent script
@ Yaseen: Hi Yaseen, you shouldn’t need to call anything as the script will initiate itself “onload”. If your dynamically rendering the table, just call:
tablePaginater.init(“yourTableId”)
To initiate the pagination for a specific table.
Regards,
Brian
I’m using the pagination script with ajax. With each update I use:
fdTableSort.init(‘table_name’);
tablePaginater.init(‘table_name’);
I’m finding that if I set pagination to say 20, and there are more than 20 records then pagination works.
If I update and the new recordset has > 1 record then all is good, the pagination buttons are correct for < 20 and more than 20 i.e. they disappear and re appear correctly.
The problem comes after an update with reveals a recordset of 0 rows. The next search which has a recordset of > 20 displays the buttons. But the table is blank. If I click on one of the pagination buttons, then the table appears once more.
If a table has > 1 and < 20 after a 0 recordset nothing is shown, and there is no way of getting the table to appear.
The thead is always visible, the bug only effects the tbody.
Any ideas?
If however I then update, but this time the table has no records then the pagination fails.
Thank you so much for this, it makes my life so much easier. Got to implement it along with your sorting script without much problem.
Does this script work with table TD , my assumption is it works only with TH elements, wish I can make it work with TD!! Can you let me know if I need to make any tweaks to suit this requirement…..
Thank you muchly for this! It works great.
However, is it also possible to “remember” a page and sorting method when you (for example) click on a button an the page reloads? I’m not sure how to do this.
Thanks for your script!
Now i use you pagenatetale in my project ,but recently i found after queryed some datarows it could not show “totle rows”,i want to know if you script has the function to show how many rows.
Thank you!
a friend from china
how do you bring across the ‘displaying page X of X number of pages’?...like the ones near your comments pagination links.
@ Frances: Hi Frances, glad you like the script.
@ saraswati : Hi saraswati, the script xpects a “properly formed” table i.e. a THEAD containing TH cells and a TBODY containing TD cells.
@ Jaap: Hi Jaap, you need to write your own method that remembers the page number using a cookie.
@ philichio & Sonu: Hi guys, the new version passes the information you require to the callback function.
how to insert the page?
Ex: Showing items xx to xx xx of all items
@ Eduardo: Hi Eduardo, I’ve just answered that in the previous comment. Anyway, I’ve updated the demo to show you how it can be done.
Is there a way to set the column widths constant in the code? I see that you did it in your demo by adding classes to all the td tags. Did you do this by hand?
@ Mat: Hi Mat, I was over zealous and placed the same class on multiple TD’s when, in fact, I should have set a single class on the associated column’s TH.
The code doesn’t deal with column size as I think this is more of a CSS issue.
I’ll try to update the demo to remove the classes from the TD tags.
Regards,
Brian
Hi, this is great great great script, thank you very much for sharing it with all us!
Is there any chance in the near future that you’ll implement an example on how to make a server-side pagination? Because I have +5000 records in the database and it really slows down the load… :/
I know you said before the guys at particleTree have code for it, but I really don’t know how to mix it with your excellent tablesort script since their code already draw its own table thing…
Can you help me?
Thank you again.
Hi I have used pagination script in my application it works well. I want to use browser button (forward and backward) to navigate to certain table records (as like that of previous and next button in the pagination script) how can I achieve this? Is there any code in script to perform this?
[I put this comment on your tablesort page by mistake, I see that it should have gone here, sorry about the double post]
Is there anyway to make the pagination skip to a specific page on loading? I have been using the script to display a multipage table where each row has a form action, and it would be nice if I could get the result of the form be the updated table on the same page that it was on before.
For example, the user pages through to page 5, clicks a button, fills in a form and submits it. Right now the result page is the updated table but it is on page 1; I’d like it to go page 5.
@ Paul: Hi Paul, try replacing the original line of code (within the “init” method) that starts with:
with the following updated version (typed live into the comment box so it’s as yet untested):
This should enable you to set the className startpage-X where “X” represents the integer value of the initial page you wish to display.
@ Luis: Hi Luis, I haven’t got the time to try to get the particleTree code working with the tablesort code (but it should be nothing more than recalling the tablesort script’s “init” method after the new table has been drawn – but don’t quote me on that). Sorry I can’t be more help.
@ shaddy: Hi shaddy, don’t mess with the browser back/forward buttons – it’s a huge UX NO-NO... and almost impossible to catch unless using a hidden iframe etc. There’s no code in the script that can help you with this I’m afraid.
@ FrequencyDecoder – thanks for the code, worked right out of the box. Awesome!!
Hi,
This is very good and works well on client side with 100-500 rows, any more than that it is really slow.
How can this be implemented with server side pagination. Pagination part seems to be easy on the server side the difficult part is to filter dynamically and restructure the table accordingly.
Anybody has any ideas which is the best way to accomplish this?
Thanks
How can this be implemented with server side pagination. Pagination part seems to be easy on the server side the difficult part is to filter dynamically and restructure the table accordingly.
Anybody has any ideas which is the best way to accomplish this?
Thanks
Hi Frequency decoder
This is truly amazing, awesome, thanks a million!
Btw, I’m in the middle of adding an itunes-like search widget to my own application for filtering stuff, if there’s interest I’d be happy to share once – it’s a bit more stable, that is.
@ Paul Sanders: Hi Paul, glad the code worked for you. I’ll add it to the official release during the next update.
@ John: Hi John, if the pagination is achieved server-side then the filter will also have to be achieved server-side in order to work properly.
@ Thierry: Hi Thierry, post the link, I’d be interested in seeing your filter script.
Hi FC,
Would it be possible to implement the paginate.js on a list of items instead of a table? I can sorta see that you’ve done that in your comments area, but not sure where to begin.
any help would be much appreciated.
@ Caleb: Hi Caleb, you will have to rewrite the script to look for UL and/or OL tags (instead of TABLE’s) and their associated child LI’s (instead of TR’s) – I haven’t got the time to code the changes for you but it shouldn’t take long (if your Javascript savvy that is). apologies I can’t help more!
Regards,
Brian
In IE7 I had a problem with the alignment of the paginater (the number-buttons were listed in a column and not in a row) I added float:left; to fix that problem.
ul.fdtablePaginater li { display:table-cell; padding-right:4px; color:#666; list-style:none; -moz-user-select:none; -khtml-user-select:none; float:left; }
@ Jens: Hi Jens, you haven’t remembered to use the IE specific CSS (passed using conditional comments within the demo) which is why your columns are “stacking”. Adding the float rule means that the list will never center i.e. always be left aligned.
Well, as advertised, everything works and works extremely well!
Here’s my request of the Master:
Is there an obvious way of incorporating the pagination into a print utility?
Sure – pop open a new window, put the data from the old div (by way of reading the elements) into the new div. Print.
Now the hard parts –
1): I’ve got a viewable page size different than the print size
2): I’d like to sequentially print all the pages required.
3): Some fool allowed the rows to be sorted… That would be me.
Does turning off the pagination via the stopEvent make sense? Re-Init it with the new page length and send each page via the current page number (pointer) to the printer? Undo everything and set the view back to the first page, or save the current page…, and reload for the user?
Not entirely sure of my footing here, but am trying the above in liu of your thoughts.
Regards,
Brian
I’m not savvy with CSS yet, so when I implemented the code I got ugly results. It wasn’t until I copied the CSS from the demo’s source code that it looked nice enough to use. You might want to include a note somewhere (perhaps I missed it??) that says the web developer needs to style his pagination links or else it’ll be ugly. Looking great, thanks so much!
Sorry, not speak english, please, help me :( , put this http://www.frequency-decoder.com/demo/table-sort-revisited/js/paginate.js in script WCDDL.
http://warezcoders.com/code/WCDDL.zip
Thanks
Hi FC,
First, i want to say how incredible is your script! Thanks a lot for all the job.
Just a question anyway : Is it possible to remove (/add) pagination by a javascript script. I try to use tablePaginater.init() function or change the table classname without success … ?
Best regards.
Hi, i wanna say thanks for your script it was very helpful for me… in the pastebin code block i modify the function simulateFilter, to be a filter by text, like a searchbox, actually it can search on the first td of every tr, excuse me for my english because is not my native language… i just wanna contribute with something :)
http://pastebin.com/m202273e0
nice work!
Gabriel.
First off sweet paging very useful. I am using this for an incredibly busy page that will never show more than 100 results (but results can vary greatly) so it really helps keep the table realestate constant on the page.
The values of this table are updated via ajax each time calling the init method after the table is updated. So If I scroll to the third page of results and then the table is updated the content of the table is updated but we remain on the third page. I see this is because the init method is maintaining the page number if the table is in the array of tables already.
So perhaps in a future release have a separate method to call when updating in this fashion or an option to reset the page number.
Its cool Thansk a lot where is the entire code i need to implement in jsp
This is a great Javascript that I can actually reuse. Two thumbs up for your efforts. I am planning to use it in our intranet/internet site.
There is one small request. Can you make the page retain the column sorting selection and the page selection during refresh? If it is straight forward fix, I would appreciate your feedback. If it is some work on your part, I do not mind “donating” for the nice work you would be doing for me.