Overview

Paginator is a customized pagination plugin made with jQuery. It's flexible and easy to use.

Live Demo

Page Number:

This is a live demo.

Please use the dropdown selector in the top left corner, the input box in the top right corner, the page index in the bottom left corner, or swipe on a touch screen device to play with this sample paginator.

You can easily use css to change the style, set the position and dimension for each element.

By default, the paginator viewport is as high as the highest page, and as wide as it can be (depends on parent element's width). However, you can change them with css as you want.

Also, you can use other html tag as a page in the paginator.

HTML form: Hello, what's your name?

Your Name:
  • item 1
  • item 2
  • item 3
  • item 4
  • item 5
  • item 6
column 1 column 2 column 3
cell 1 cell 2 cell 3
cell 4 cell 5 cell 6
cell 7 cell 8 cell 9

You can also use the APIs to create your own UI to control the paginator. For example, here are two buttons made with selectPage, one will bring you back to the first page, the other one will bring you to the next page.

This is page8. So now you can see the button color has been changed to orange, the .on('selectPage') listener did it.

Go to page9 to get the original color back.

This is page9. Isn't the original color back?

If you don't know what am I talking about, go to page8.

Feature

  • Free
  • Support most html contents.
  • Support swiping on touch screen device.
  • Support modern browser: IE9+, Firefox, Opera, Chrome, and Safari.
  • Support auto pagination

Usage

Basic Usage

The HTML code looks like this (demo) :

1. Make sure to include jQuery, jquery.paginator.js, and paginator.css in your HTML file: 

<head>
  <script type="text/javascript" src="js/jquery-1.9.0.min.js"></script>
  <script type="text/javascript" src="js/jquery.paginator.js"></script>
  <link rel="stylesheet" href="css/paginator.css">
</head>

2. Create your paginator in the <body> tag. Your page content should be placed inside a <div class="page"> tag, and use a <div class="pages"> tag to wrap all the pages and put it inside a <div class="viewport"> tag.

There are four basic ways to control the paginator: 1) drop down selector, 2) input box, 3) index bar, and 4) swiping on a touch screen device. Swiping is a default, the other three can be implemented as the example below, and you can use css to define their position and style.

The example includes all of the three methods, but they are actually optional.

<div id="paginator1">
  <select class="pageSelector"></select><--This is the dropdown selector-->
  <div class="pageInputWrapper">Page Number: <input type="text" size="2" class="pageInput"></div><--This is the input box-->
  <div class="viewport">
    <div class="pages">
      <div class="page" title="title1">page content</div>
      <div class="page" title="title2">page content</div>
      <div class="page" title="title3">page content</div>
    </div>
  </div>
  <div class="pageIndexBar"></div><--This is the index bar-->
</div>

3. Apply it in JavaScript.

<script type="text/javascript">
  $(function () {
    $('#paginator1').paginator();
  });
</script>

The syntax is:

  .paginator([options], [callback]).

The options and callback function are both optional, you will find the details below.


Advance Usage

You can use not only <div> tag as each page, but also some other tags, like: <img />, <ul>, <table>, ... (please see the live demo above)

Just easily give them a class="page":

<img class="page" title="title1" />
<ul class="page" title="title2">list content</ul>
<form class="page" title="title3">form content</form>
<table class="page" title="title3">table content</table>

Note: This plugin doesn't solve the iframe dimesion problems on iOS, so iframe is not suggested

Note: The swipe method is not gonna work for a <video> tag which swallows all touch events on an iPad unless you remove the controls attribute; on iPhone or iPod Touch, the <video> tag is just a link to open the QuickTime app to play the video, so, it won't work even you remove the controls attribute.


The paginator allows you to use css to change style of its child elements (demo).

Note: The only exception is the class="pages" element, which is just a wrapper for all the page elements, it should not have left and right border, padding, or margin.


Pagination for a table is also possible. The concept is using <tbody> tags to be pages (demo) :

<table class="pages">
  <tbody class="page" title="title1">
    <tr>
      <td>content</td>
      <td>content</td>
      <td>content</td>
    </tr>
  </tbody>
  <tbody class="page" title="title2">
    <tr>
      <td>content</td>
      <td>content</td>
      <td>content</td>
    </tr>
  </tbody>
  <tbody class="page" title="title3">
    <tr>
      <td>content</td>
      <td>content</td>
      <td>content</td>
    </tr>
  </tbody>
</table>

Options

The first argement of .paginator() is an option object. You can specify options when applying paginator:

$('#paginator1').paginator({autoPagination: true}); // turn on auto pagination

Available options

Option Type Default Description
autoPagination boolean false

If set to true, the page content elements shoulde be placed inside the <div class="pages"> tag, and each page will be automatically generated. (demo)

Ex:

<div class="pages">
  <p>paragraph1</p>
  <p>paragraph2</p>
  <img src="pic1.jpg" />
    .
    .
    .
</div>

Note:

The page will be generated according to the viewport height and the height of each element in the <div class="pages"> tag, so make sure:

  1. The viewport height is set before applying the paginator.
  2. Each child element has a real height. For example: if it has floated elements inside and itself is not floated or overflow: auto, and there is no elements has clear attribute, it doesn't really wrap the floated elements. So, you need to give it a height before applying the paginator.
displayNumber integer 9

Set the max page number shoud be visible in the index bar.
swipe boolean true

Allow users to swipe on the touch screen devices.

APIs

You can use the APIs to control the paginator you just created. Using the same element to call these APIs.

$('#paginator1').paginator('selectPage', 1); // turn to page1

Control the Paginator

Syntax Description
.paginator('initPaginator')

Initialize the paginator.

This method doens't accept arguments.

Code example:

Initialize the paginator.

$('#paginator1').paginator('initPaginator');
.paginator('selectPage', pageId)

Turn to a page.

Code example:

Turn to page 1.

$('#paginator1').paginator('selectPage', 1);
.paginator('insertPage', pageId, {
  content: htmlString,
  title: textString
})

Insert a new page into the paginator and initialize it. The third argument is the page object including content and title, the second argument is the page id of the page you are gonna insert.

The index is an option. If index is not defined, the new page will be automatically inserted after the last page.

If the title is not defined, the page title will be page number.

Code example:

Insert a new page before page 1.

$('#paginator1').paginator('insertPage', 1, {
  content: 'This is a new page!',
  title: 'new'
});
.paginator('updatePage', pageId, {
  content: htmlString,
  title: textString
})

Update a page's content and title and initialize the paginator. The third argument is the page object including content and title, and the second argument is the page id of the page you are gonna update.

Code example:

Update page 1.

$('#paginator1').paginator('updatePage', 1, {
  content: 'Page 1 has been updated!',
  title: 'update'
});
.paginator('removePage', pageId)

Remove a page and initialize the paginator.

Code example:

Remove page 1.

$('#paginator1').paginator('removePage', 1);

Event Listener

Syntax Description
.on('selectPage', handler)

Called when a page is selected. Like the reguler event, the scope is bound to the selector itself.

Code example:

$('#paginator1 .page:eq(0)').on('selectPage', function () {
    //do something
});

and this will be fired on page1

Note: For a page element only.

Callback

The callback function will be fired right after the paginator is created. Ex: 

$('#paginator1').paginator(function () {
  console.log(this);
}); // show the object in console

Download