tradpaginator

Description

With this jQuery plugin you can easily generate active pagination controllers for your pages as easy as this:

$("#mypaginationdiv").tradpaginator('init', {
  curpage:4,
  totalpagesonresultset:18,
submitionmethod:'url',
getMethodOptions:{
pageinputvarname: 'page'
}
});

and you get something like this appended on the selected div (mypaginationdiv):

License

Released under the WTFPL license

Compatibility and Dependencies

Browser support

• Internet Explorer 6+
• Mozilla Firefox 1.5+
• Safari 3+
• Opera 9.5+ (9.01+ as of 1.10)
• Google Chrome 1.0+
• iOS 2.0+
• Opera Mini (to a certain degree)

Dependencies

• underscore.js
• jQuery

What the plugin does

How many times have you found yourself coding again and again a pagination controls section for a project of yours?
Decide which is the page range that should be illustrated, center the current page within this range, include a jump menu, bind a click action to each button in order to actually do something and many more are aspects that we face again and again when building custom web pages including pagination logic.
tradpaginator plugin provides an easy and rapid way to append pagination buttons and controls letting you to state the parameters and taking care of all the rest.
tradpaginator illustrates the page buttons and controls and it lets you chain their functionality with the logic and structure of your application.

Installation

In order for the plugin to operate you need to include the following lines to the head of the page:

<!-- having the dependencies loaded: --> 
<script src="./path/to/jquery.js"></script>
<scirpt src="./path/to/underscore.js"></script>
<!-- load the plugin -->
<script src="./path/to/jquery.tradpaginator.js"></script>

Basic usage

In order to display the pagination buttons within a selected div just call the tradpaginator method, passing your settings:

$("#mypaginationdiv").tradpaginator('init', {
  curpage:4,
  totalpagesonresultset:18,
submitionmethod:'url',
getMethodOptions:{
pageinputvarname: 'page'
}
});

Settings

PARAMETER NAME	TYPE - DESCRIPTION	DEFAULT VALUE
curpage	(int) the number of the current page OR 'auto'. Use 'auto' if you want the plugin to auto detect the current page either from the url (with submitionmethod = 'url') or from the corresponding input field (with submitionmethod = 'form'). If the plugin does not auto-detect the value it will set the page = 1	'auto'
totalpagesonresultset	(int) the total number of pages	-
totalPageButtonsNumber	(int) the number of page buttons to display	11
devmode	(bool) set it to true in order to get warning and error alerts and messages	false
style	(string) style name	'default'
include_previousnextbuttons	(bool) include previous and next page buttons	true
previous	(string) the text to be illustrated on the previous page button	'previous'
next	(string) the text to be illustrated on the next page button	'next'
include_fistlastbuttons	(bool) include first and last page buttons	true
first	(string) the text to be illustrated on the first page button	'first'
last	(string) the text to be illustrated on the last page button	'last'
include_jumpmenu	(bool) include page jump menu	true
jumpmenu_caption	(string) the jump menu label	'jump to page'
submitionmethod	(string) one of the following: - form (change the input of a form and submit the form) - url (change page by passing a certain url variable) - none (none of the above)	'none'
postMethodOptions	(Object): should be filled when 'form' submittionmethod is selected { pageinputid (the id of the form input that holds the page to go when form is submitted) formid (the form id) alignbyinputid (the id of the form input that holds the the name of the column that the results are ordered by) ascdescinputid (the id of the form input that holds the ordering direction) }
getMethodOptions	(Object): should be filled when url submittionmethod is selected { pageinputvarname (the name of the url parameter that defines the page number) orderbyinputvarname (the name of the url parameter that defines the column by which the results are ordered by) ascdescinputvarname (the name of the url parameter that defines the ordering direction) }
orderinginfo	{ enable (default: false. Set this value to true if you want to enable the ordering functionality of the plugin) currentorderbycol (either specify the current column name by which the results are ordered by or set it to auto and let the plugin auto-detect it either from the url or from the corresponding form input) defaultordercol (if you set the currentorderbycol to auto and the plugin does not succeed finding the value it will set the currentorderbycol to the value of this attribute) currentascdesc (either specify the current ordering direction by which the results are ordered by or set it to auto and let the plugin auto-detect it either from the url or from the corresponding form input) defaultascdesc (if you set the currentascdesc to auto and the plugin does not succeed finding the value it will set the currentascdesc to the value of this attribute) ascendingvalue (this is the value that the plugin will set to url or the corresponding input field in the case that ascending order should be implied. The default value of this variable is 'asc') descendingvalue (this is the value that the plugin will set to url or the corresponding input field in the case that descending order should be implied. The default value of this variable is desc) }
onPageButtonClick	(function(el, pageno) - el: the jQuery element that represents the button clicked - pageno: the page number of the button clicked ) define a function to be called when a page button is clicked. The function runs before the action taken if you state a submition method other than none.
onPageButtonHover	(function(el, pageno) - el: the jQuery element that represents the button hovered - pageno: the page number of the button hoverd ) define a function to be called when a page button is hoverd.

Pagination Examples

1. Change page through url parameter

Let's suppose that you have:
- 150 total pages on your illustrating results

• You want ot illustrate 7 page buttons on the pagination control
  
• You want ot include a page jump menu, the previous and next buttons and the last and first page buttons
  
• The page is built so that it takes the page number from the url from the parameter page
  
• The div that you want to append the pagination controls has the id "mypaginationdiv"

- The current page is 9

Code

$("#mypaginationdiv").tradpaginator('init', {
  curpage:9,
  totalpagesonresultset:150,
  totalPageButtonsNumber: 7,
  submitionmethod:'url',
  getMethodOptions:{
    pageinputvarname: 'page'
  }
});

Result

By clicking to any of the page buttons or using the jump menu the page will be refreshed passing the proper value on the page parameter

2. Change page by submitting a form

Let's suppose that you have:
- 150 total pages on your illustrating results

• You want ot illustrate 7 page buttons on the pagination control
  
• You want ot include a page jump menu, the previous and next buttons and the last and first page buttons
  
• The page is built so that it takes the page number (among others) through a form
  
• The div that you want to append the pagination controls has the id "mypaginationdiv"

- The current page is 9

<form id="myform" method="post" action="./" />
  <input type="hidden" id="pageno" name="pageno" />
  <div id="mypaginationdiv"></div>
</form>

Code

$("#mypaginationdiv").tradpaginator('init', {
  curpage:9,
  totalpagesonresultset:150,
  totalPageButtonsNumber: 7,
  submitionmethod:'form',
  postMethodOptions:{
    pageinputid: 'pageno',
    formid: 'myform'
  }
});

Result

By clicking to any of the page buttons or using the jump menu the form will be submitted passing the selected page number

3. Asynchronous page change

Let's suppose that you have:
- 9 total pages on your illustrating results
- You want ot illustrate 7 page buttons on the pagination control
- You don't want ot include a page jump menu, the previous and next buttons and the last and first page buttons
- The page is built so that it aqcuires the next page through an asynchronous method (ajax, websockets etc)
- The div that you want to append the pagination controls has the id "mypaginationdiv"
- The current page is 9

<form id="myform" method="post" action="./" />
  <input type="hidden" id="pageno" name="pageno" />
  <div id="mypaginationdiv"></div>
</form>

Code

$("#mypaginationdiv").tradpaginator('init', {
  curpage:9,
  totalpagesonresultset:9,
  totalPageButtonsNumber: 7,
  submitionmethod:'none',
  include_jumpmenu:false,
  include_previousnextbuttons:false,
  include_fistlastbuttons:false,
  onPageButtonClick:function(el, pageno){
    // do your magic stuff here
  }
});

Result

By clicking to any of the page buttons the onPageButtonClick function declared will be called

Ordering functionality

From version 0.8 tradpaginator provides ordering capabilities too. The most often way that users change the ordering of a list (either by specifying the column by which the list should be ordered or by changing the ordering direction from to asc to desc to asc) is by clicking to the columns titles of a table that contains the results.
Each of the column titles (most often) represents a database column. In order to activate and use the new auto ordering functionality of the plugin you should follow these easy steps:

To explain better the way the tradpaginator ordering capabilites works let's take the followng example. Let's assume that we have the following table within which we illustrate our results:

<table>
<thead>
  <tr>
    <th>ID</th>
    <th>Surname</th>
    <th>Name</th>    
  </tr>
</thead>
<tbody>
.........
</table>

Let's now assume that we want to enable ordering capabilities to all the three of the columns (ID, Surname, Name). The first thing we have to do is the follow is to wrap each of the column title to a span with class tradpaginatororder:

<table>
<thead>
  <tr>
    <th><span class="tradpaginatororder" data-col="id">ID<span></th>
    <th><span class="tradpaginatororder" data-col="surname">Surname</span></th>
    <th><span class="tradpaginatororder" data-col="name">Name</span></th>    
  </tr>
</thead>
<tbody>
.........
</table>

As you may noticed in each of the spans we added a data-col attribute. This attribute should be added and defined in all of the tradpaginatororder spans. It defines the value that will passed to the server as the ordering column.
The next thing that you should do is to enable the ordering capabilities of the plugin by setting the orderinginfo.enable to true and then set up the rest of the details through orderinginfo, postMethodOptions and getMethodOptions variables.

Multiple instances

tradpaginator plugin can be used for multiple instances on the same page without a problem

Style and layout

For now there is only the default style included. New styles will be added during the upcoming releases.
If you want to customize the look and style of the buttons and controls you can copy the files "layout.html" and "layout.css" from the ./layouts/default/ folder to ./layouts/custom/.
You can edit the layout.css and - or the layout.html file. In order to edit the layout.html file you need to have basic knowledge on underscore templating engine.
Having the new custom layout ready you can load it by passing the "custom" value on the style property of setting during execution.