Bootstrap Paginator v 1.0

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

    Default:
    {
        animation: true,
        html: true,
        placement: 'top',
        selector: false,
        title: "",
        container: false
    }
                    

Public Methods

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

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.

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.

                
        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.

                
                    // 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.

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.

                
        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.

                
        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.

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

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