# Bootstrap Paginator v 1.0

## Intro

Bootstrap Paginator is a jQuery plugin that simplifies the rendering of Bootstrap Pagination component. It provides methods to automates the update of the pagination status and also some events to notify the status changes within the component. Bootstrap v3 is now supported.

Download Visit Project in GitHub

## Get Started

It is very easy to get Bootstrap Paginator start working. You need to include the Bootstrap, jQuery and Bootstrap Paginator before you can use it. The zip ball can be download via the button provided above.

        <link href="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">
        <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
        <script src="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/js/bootstrap.min.js"></script>
        <script src="/js/bootstrap-paginator.min.js"></script>

Then in your code, you can use the following lines to render your Bootstrap Paginator. This is explained in the section Minimum Initialization. The Bootstrap Paginator will be rendered as shown. The only html markup required by Bootstrap Paginator is an empty div.

        <div id="example"></div>
        <script type='text/javascript'>
            var options = {
                currentPage: 3,
                totalPages: 10
            }

            $('#example').bootstrapPaginator(options);
        </script>

## Documentation

### Structure Explained

Bootstrap Paginator will have the Bootstrap Pagination Component rendered as shown in the following graph. It has 5 parts. Left most one is the go to first page item. The one next to it is the previous page item. The following numeric page items are of the type page. Next page item comes after it. Last page item will be the last one rendered. Please note that the labels are the types of each component.

### Options

Attribute | Type | Default | Description
--- | --- | --- | ---
size | string | "normal" | Controls the size of output pagination component. Accepts values: mini(not supported in Bootstrap v3), small, normal, large. See the Size and alignment example for more detail.
bootstrapMajorVersion | number | 2 | Specifies the major version number of bootstrap so that the plugin know how to render the pagination
alignment | string | "left" | Controls the alignment of the pagination component. It accepts values left, center and right. Those values maps to the alignment class pagination-centered and pagination-right in Bootstrap Pagination. See the Size and alignment example for more information. Note that this property is not supported when using Bootstrap v3
itemContainerClass | function |  | This functions must return a string class name when rendering a specific page item. type, page, current are given as the parameters. The default function only returns "active" when the page is the current page. See the Controlling the item container class example for more detail.
currentPage | number | 1 | It marks the current page. If the current page is set out of range, an exception will be thrown.
numberOfPages | number | 5 | This one decides how many numeric pages (with type page as stated in the Structure Exaplained section) should be rendered. If its value <= 0, no numeric page will be rendered. See the Number of Pages example for more detail.
totalPages | number | 1 | It defines the upper limit of the page range.
pageUrl | function |  | pageUrl fills the href attribute when rendering the page items. type, page, current are given as the parameters. A string of URL should be returned. See Page URL example for more detail.
shouldShowPage | boolean/function | true | Defines whether a page item should be shown. Before each page item is rendered, the code will check whether it should be rendered. Once supplied as a function, the following parameters are given: type, page, current. Boolean should be returned. See Controlling The Presence of Page Item for more detail.
itemTexts | function |  | Supplies the page item text during the rendering, it can be either plain text or html. The following parameters are given: type, page, current. See Page Item Example for more detail.
tooltipTitles | function |  | Supplies the tooltip text during the rendering. The function should returns a string. The following parameters given: type, page, current. Html text can be rendered when using Bootstrap Tooltip option and has the html attribute inside set to true. See Page Item Tooltip Text for more detail.
useBootstrapTooltip | boolean | false | Defines whether to use the Bootstrap Tooltip as its tooltip rather than the original title attribute in the anchor tag <a>. See Use Bootstrap Tooltip example for more detail.
bootstrapTooltipOptions | object |  |
        Default:
        {
            animation: true,
            html: true,
            placement: 'top',
            selector: false,
            title: "",
            container: false
        }
This object is the same as what you've seen in Bootstrap Tooltip Documentation for more detail.
onPageClicked | function |  | onPageClicked is the handler for the page-clicked event. The signature of the handler is function(event, originalEvent, type,page). If you would like the stop the page change from happening. Simply call event.stopImmediatePropagation() and do the page change yourself if applicable later. See page-clicked Event example for more detail. Also the stoppable page change within page click event is demonstrated in See Stopping Page Change Within Page Clicked Event for more detail.
onPageChanged | function |  | onPageChanged is the handle for the page-changed event. The signature of the handler is function(event, oldPage, newPage). See page-changed Event example for more detail.

### Public Methods

Bootstrap Paginator have the following public method for controlling the component or accessing the state of the component.

Name | Parameters | Return | Description
--- | --- | --- | ---
show | page |  | Function show makes the Bootstrap Paginator to show the specified page. This method will trigger the page-changed event if the specified page differs from the current page. See Show Function example for more detail.
showFirst |  |  | Function showFirst shows the first page. This method will trigger the page-changed event as the show function. See Show Function example for more detail.
showPrevious |  |  | Function showPrevious shows the previous page. This method will trigger the page-changed event as the show function. See Show Function example for more detail.
showNext |  |  | Function showNext shows the next page. This method will trigger the page-changed event as the show function. See Show Function example for more detail.
showLast |  |  | Function showLast shows the last page. This method will trigger the page-changed event as the show function. See Show Function example for more detail.
getPages |  | object | Function getPages returns an array with extra attributes that state the current status of the page. Elements that can be access via numeric index are the items with type: page. Attributes first, prev, next, last maps to the type of pages that other than the numeric pages. getPages function will now no longer set these value to null even if the page at either first or last page. Instead, the values will be either set to first or last page respectively. The control of the visibility of each page item now is handed to the shouldShowPage function. Attribute current is the current page. Attribute total and numberOfPages indicate the total pages and number of numeric pages respectively. See getPages Function example for more information.
setOptions | object |  | Function setOptions updates options to the current setting. Attributes in the option object can be any combination in the option table. A common example is to update the total pages when it's changed. See setOptions Function exmaple for more information.

### Events

Bootstrap Paginator has two event. You can bind to them either through the callback through the handler or using the .on method in jQuery.

Event | Handler Signatrue | Description
--- | --- | ---
page-clicked | function(event, originalEvent, type, page) | It will be triggered when the page item is clicked. Parameter originalEvent is provided as if you need to have control over the original click event. Plus, the type and page is associated with the clicked item. For more information please see page-clicked Event example.
page-changed | function(event, oldPage, newPage) | page-changed event will be triggered when the current page is changed via show method or its variant. oldPage and newPage together represents the change. Please see page-changed Event example for more detail.

## Examples

### Minimum Configuration

Initialization requires only two attributes in the configuration object. Attributes currentPage and totalPages are needed to get it running.

        <div id="example"></div>
        <script type='text/javascript'>
            var options = {
                currentPage: 3,
                totalPages: 10
            }

            $('#example').bootstrapPaginator(options);
        </script>

### Size and Alignment

Size in Bootstrap Paginator is set via size attribute. It accepts the following values: large,normal, small, mini. Alignment is set via alignment attribute, and it accepts the following values: left, center, right. In this example, you can change the size and alignment via a set buttons.

            var options = {
                currentPage: 3,
                totalPages: 10,
                size:"normal",
                alignment:"left"
            }

            $('#example').bootstrapPaginator(options);

### Page Item Text

You can change the text of the page items. It is done via an attribute called itemTexts in the configuration object. The value is a function that should returns a string. type, page, current are given as the parameters.

            var options = {
                currentPage: 3,
                totalPages: 10,
                itemTexts: function (type, page, current) {
                        switch (type) {
                        case "first":
                            return "First";
                        case "prev":
                            return "Previous";
                        case "next":
                            return "Next";
                        case "last":
                            return "Last";
                        case "page":
                            return "p"+page;
                        }
                    }
                }

            $('#example').bootstrapPaginator(options);

### Page Item Tooltip Text

Tooltip text can be changed by using the attribute tooltipTitles. It is a function that returns a string. type, page, current are given as the parameters.

            var options = {
                currentPage: 3,
                totalPages: 10,
                tooltipTitles: function (type, page, current) {
                        switch (type) {
                        case "first":
                            return "Tooltip for first page";
                        case "prev":
                            return "Tooltip for previous page";
                        case "next":
                            return "Tooltip for next page";
                        case "last":
                            return "Tooltip for last page";
                        case "page":
                            return "Tooltip for page " + page;
                        }
                    }
                }

            $('#example').bootstrapPaginator(options);

### Use Bootstrap Tooltip

Instead of using the title in the <a> tag, you can use Bootstrap Tooltip for the tooltip options. There is a switch named useBootstrapTooltip to turn it on. It is off by default.

            var options = {
                currentPage: 3,
                totalPages: 10,
                useBootstrapTooltip:true
            }

            $('#example').bootstrapPaginator(options);

### Configure Bootstrap Tooltip

You can use bootstrapTooltipOptions to config the bootstrap tooltip used in the bootstrapPaginator. It is the same as the configuration we've seen in Bootstrap Tooltip's documentation. For more information please see Bootstrap Tooltip Documentation.

            var options = {
                currentPage: 3,
                totalPages: 10,
                useBootstrapTooltip:true,
                tooltipTitles: function (type, page, current) {
                    switch (type) {
                    case "first":
                        return "Go To First Page <i class='icon-fast-backward icon-white'></i>";
                    case "prev":
                        return "Go To Previous Page <i class='icon-backward icon-white'></i>";
                    case "next":
                        return "Go To Next Page <i class='icon-forward icon-white'></i>";
                    case "last":
                        return "Go To Last Page <i class='icon-fast-forward icon-white'></i>";
                    case "page":
                        return "Go to page " + page + " <i class='icon-file icon-white'></i>";
                    }
                },
                bootstrapTooltipOptions: {
                    html: true,
                    placement: 'bottom'
                }
            }

            $('#example').bootstrapPaginator(options);

### Controlling the Item Container Class

Item container class is controllable via an attribute itemContainerClass. This attribute accepts a function that returns a string. type, page, current are given as the parameters. One example is that the active class is added via this attribute by default. Another example is that you can easily add the pointer cursor on the page items. See the code and demo below.

            var options = {
                currentPage: 3,
                totalPages: 10,
                itemContainerClass: function (type, page, current) {
                    return (page === current) ? "active" : "pointer-cursor";
                }
            }

            $('#example').bootstrapPaginator(options);

### Number of Pages

The max number of pages is controllable via attribute numberOfPages. This attribute accepts only integer. The following example shows the 3 pages example.

            var options = {
                currentPage: 2,
                totalPages: 10,
                numberOfPages:3
            }

            $('#example').bootstrapPaginator(options);

### Page URL

What if your pagination relies on the page parameters that's set in the url rather than ajax mode. That's where you need pageUrl. It accepts a function that returns a string as url for different type of pages. type, page, current are given as the parameters.

Click on the pages to show the url

            var options = {
                currentPage: 3,
                totalPages: 10,
                pageUrl: function(type, page, current){

                    return "http://example.com/list/page/"+page;

                }
            }

            $('#example').bootstrapPaginator(options);

### Controlling The Presence of Page Item

The presence of page items are controllable. For example, if you don't want the first and the last page item. You can simply do that via shouldShowPage. The attribute accepts a simple boolean value or a function that returns the situation according to the type, page and current given. The following example hide the first and last page item.

            var options = {
                currentPage: 3,
                totalPages: 10,
                shouldShowPage:function(type, page, current){
                    switch(type)
                    {
                        case "first":
                        case "last":
                            return false;
                        default:
                            return true;
                    }
                }
            }

            $('#example').bootstrapPaginator(options);

### show Function

Function show is the interface that can be use to control the current page of Bootstrap Paginator from the outside. It accepts a number as it's parameter. If the current page is out of bound of the current configuration. An exception will be thrown. Besides show function, there are some variants. They are, showFirst, showPrevious, showNext and showLast.

Go to page:
Click on the buttons or select the pages to invoke the show function.

                        // waiting for the function to be called

### getPages Function

Function getPages returns an array with extra attributes that state the current status of the Bootstrap Paginator Component. Additional attributes first, prev, next and last refer to the four different types of page items. current attribute tells the current page value of the component. total tells the total pages and numberOfPages tells the number of numeric pages being shown.

### setOptions function

Function setOptions updates the options for Bootstrap Paginator. You don't have to call the method specifically after initialization, just use $('#example').bootstrapPaginator(optionsToUpdate) can also achieve the same effect. The following example will allow you to set numberOfPages and totalPages attribute.

Number of Pages:
Total Pages:

### page-clicked Event

The event page-clicked will be triggered when a page item is clicked. You can register the handler via the attribute onPageClicked or you can simply use the `on('page-clicked',handler)`. The signature of the handler is function(event, originalEvent, type,page). The originalEvent is the original click event generated by the page item. It exists for the case that you might want to get call preventDefault or stopPropagation on it. The following example will shows the type and page in the alert when the page is clicked.

Click on the pages to trigger the page-clicked event.

            var options = {
                currentPage: 3,
                totalPages: 10,
                onPageClicked: function(e,originalEvent,type,page){
                    $('#alert-content').text("Page item clicked, type: "+type+" page: "+page);
                }
            }

            $('#example').bootstrapPaginator(options);

### Stopping the page change within Page Clicked event

If an ajax call is triggered through page click event and you want the page change happen after the content is loaded. You can simply stop the default page change event by calling event.stopImmediatePropagation() and do it later when the document is loaded.

Click on the pages to trigger the page-clicked event.

            var options = {
                currentPage: 3,
                totalPages: 10,
                onPageClicked: function(e,originalEvent,type,page){

                    e.stopImmediatePropagation();

                    var currentTarget = $(e.currentTarget);

                    var pages = currentTarget.bootstrapPaginator("getPages");

                    $('#alert-content').text("Page item clicked, current page: "+pages.current);

                    setTimeout(function(){

                        currentTarget.bootstrapPaginator("show",page);

                        var pages = currentTarget.bootstrapPaginator("getPages");

                        $('#alert-content').append("<br/>Page item click finished, current page: "+pages.current);

                    },3000);
            }

            $('#example').bootstrapPaginator(options);

### page-changed Event

The event page-changed will be triggered when the current page is changed to another one. This event only cares about the change between pages. So it's signature doesn't include the type parameter. Instead, the old and new value of the change are given.

Go to page:
Click on the pages or type the selected pages trigger the page-change event.

            var options = {
                currentPage: 3,
                totalPages: 10,
                onPageChanged: function(e,oldPage,newPage){
                    $('#alert-content').text("Current page changed, old: "+oldPage+" new: "+newPage);
                }
            }

            $('#example').bootstrapPaginator(options);

Bootstrap Paginator is licensed under the Apache Software Foundation License Version 2.0. Coded by Yun Lai.