Bootstrap4 Paginator v 2.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

Size in Bootstrap Paginator is set via size attribute. It accepts the following values: large,normal, small.

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

		$('#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 defined in regional settings. By default bootstrap paginator supports only english. For additional strings you must set $.fn.bootstrapPaginator.regional["you language code"] object. Default language selected by browser settings or you can specify language in options.

				
		$.fn.bootstrapPaginator.regional["custom"] = {
			first: "Tooltip for first page",
			prev: "Tooltip for previous page",
			next: "Tooltip for next page",
			last: "Tooltip for last page",
			current: "Tooltip for current page",
			page: "Tooltip for page ${0}"
		}

		var options = {
			language: "custom",
			currentPage: 3,
			totalPages: 10
		}
				
		$('#bp-example-page-item-tooltip-text').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.

				
		$.fn.bootstrapPaginator.regional["custom"] = {
			first: "Tooltip for first page",
			prev: "Tooltip for previous page",
			next: "Tooltip for next page",
			last: "Tooltip for last page",
			current: "Tooltip for current page",
			page: "Tooltip for page ${0}"
		}
				
		var options = {
			language: "custom",
			currentPage: 3,
			totalPages: 10,
			useBootstrapTooltip:true,
			bootstrapTooltipOptions: {
				html: true,
				placement: 'bottom'
			}
		}
				
		$('#bp-example-page-item-bootstrap-tooltip-configuration').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" 
					: (page < current)
						? "cursor-left"
						: "cursor-right";
			}
		}

		$('#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);
				
			

Also you can control the presense of Buttons "first", "prev", "next" and "last" by properties alwaysDisplayNextPrevButtons and alwaysDisplayFirstLastButtons.

			
	
		var options = {
			currentPage: 3,
			totalPages: 10,
			alwaysDisplayFirstLastButtons: false,
			alwaysDisplayNextPrevButtons: false
		}

		$('#bp-example-presence-of-page-always-property').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
				
			

getOption Function

Function getOption caleld without parameter returns a copy of options object.

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);
				
			

Ajax call

You can set options for auto ajax call. Chromium-based browser blocks this demo. Try Firefox or Edge (non-chromium version).

				
		let options = {
			currentPage: 1,
			totalPages: 3,
			numberOfPages: 3,
			ajaxUrl: page => `ajaxPage${page}.txt`,
			targetElement: "#ajax-content"
		};
		
		$("#bp-example-ajax-call").bootstrapPaginator(options);