Pagination
- Overview
- Remote Pagination (Server Side)
- Local Pagination (Client Side)
- Pagination Control Element
- Managing Pagination
- Callbacks
Overview
If you would prefer to display your data as pages rather than a scrolling list Tabulator can help you out there too.
There are two forms of pagination available. local pagination, where Tabulator will parse in all available data and then paginate this data set. Or remote pagination, where Tabulator will load individual pages of data via Ajax from a remote server.
When pagination is enabled, a footer element will be added to the bottom of the table, with a range of navigation controls to allow your users to easily switch between pages.
The first page of a table will automatically be loaded when the table is created if pagination is enabled.
If you are a Laravel user then you should find that the auto generated URL's and data processing work straight out the box with no additional configuration needed.
Note: Changing the filter, sorting or toggling a groups visibility, while pagination is enabled will revert the table back to the first page.
Remote Pagination
To enable remote pagination, set the pagination option to remote, and set the url for the Ajax request using the ajaxURL parameter. You can also pass an optional object to ajaxParams for any parameters you want to pass with the url (these should be static parameters, the page number etc, will be added later on).
By default the page size will be set by the amount of data returned by the remote server, if you need to tell the remote server how many rows to send you can set the paginationSize parameter.
var table = new Tabulator("#example-table", { pagination:"remote", //enable remote pagination ajaxURL:"http://testdata.com/data", //set url for ajax request ajaxParams:{token:"ABC123"}, //set any standard parameters to pass with the request paginationSize:5, //optional parameter to request a certain number of rows per page paginationInitialPage:2, //optional parameter to set the initial page to load });
Request URL
Tabulator will automatically create a page request URL when a user selects a page.
By default a url will be generated using the provided ajaxURL and a number of system generated parameters:
- page - the page number being requested
- size - the number of rows to a page (if paginationSize is set)
- sorters - the first current sorters(if any)
- filter - an array of the current filters (if any)
If you need to change the names of any of these parameters to fit your existing system, you can use the paginationDataSent option to set alternative parameter names.
var table = new Tabulator("#example-table", { pagination:"remote", //enable remote pagination ajaxURL:"http://testdata.com/data", //set url for ajax request paginationDataSent:{ "page":"pageNo", //change page request parameter to "pageNo" } , });
Custom Pagination URL Construction
If you need to have more complex control over the request URL, you can pass a callback to the ajaxURLGenerator option to return the URL you wish to use for each page, the pagination information such as page number and page size can be found in the prams argument
var table = new Tabulator("#example-table", { ajaxURLGenerator:function(url, config, params){ //url - the url from the ajaxURL property or setData function //config - the request config object from the ajaxConfig property //params - the params object from the ajaxParams property, this will also include any pagination, filter and sorting properties based on table setup //return request url return url + "?params=" + encodeURI(JSON.stringify(params)); //encode parameters as a json object }, });
Note: If you use a paginator function you will need to manually add the sort and filter parameters to the request url if required.
Returned Response Data
The remote server should return a JSON formatted object with the following structure:
{ "last_page":15, //the total number of available pages (this value must be greater than 0) "data":[ // an array of row data objects {id:1, name:"bob", age:"23"}, //example row data object ] }
If you need to change the names of any of these parameters to fit your existing system, you can use the paginationDataReceived option to set alternative parameter names.
var table = new Tabulator("#example-table", { pagination:"remote", //enable remote pagination ajaxURL:"http://testdata.com/data", //set url for ajax request paginationDataReceived:{ "last_page":"max_pages", //change last_page parameter name to "max_pages" } , });
Local Pagination
Local pagination works by loading the entire data set into the table then generating paged views of that data.
To enable local pagination set the pagination option to local.
var table = new Tabulator("#example-table", { pagination:"local", //enable local pagination. });
Setting Page size
With local pagination there are a couple ways to set the number of rows in each page.
You can specify the page size during table creation by setting the paginationSize option. If no height option is specified the table will resize to fit the number of rows on the page.
var table = new Tabulator("#example-table", { pagination:"local", //enable local pagination. paginationSize:5, // this option can take any positive integer value });
Alternatively, if you specify the height of the table, either in CSS or by using the height option, and don't define the paginationSize option the page size will be automatically set to fill the height of the table.
var table = new Tabulator("#example-table", { height:"300px", pagination:"local", //enable local pagination. });
Note: If you set the height of the table and use the paginationSize option, the number of rows may either not fill the available space, or not fit in the table and a vertical scrollbar will appear.
Setting Initial Page
By default Tabulator will load the first page of data when the table is initially loaded. You can use the paginationInitialPage option to specify that a specific page should be loaded when the table first loads.
var table = new Tabulator("#example-table", { pagination:"local", //enable local pagination. paginationInitialPage:2, // this option can take any positive integer value (default = 1) });
Pagination Control Element
Custom Pagination Control Element
By default the pagination controls are added to the footer of the table. If you wish the controls to be created in another element pass a DOM node or a CSS selector for that element to the paginationElement option.
var table = new Tabulator("#example-table", { pagination:"local", paginationElement:paginationElement, //build pagination controls in this element });
Set Number of Pagination Buttons
The number of pagination page buttons shown in the footer using the paginationButtonCount option. By default this has a value of 5.
var table = new Tabulator("#example-table", { paginationButtonCount:3, //use 3 page buttons in the footer });
Show Page Size Select Element
If you would like the user to be able to set the number of rows on each page, you can use the paginationSizeSelector option, which will add a page size selection select element to the table footer.
Auto Generate Page Size List
Setting this option to true will cause Tabulator to create a list of page size options, that are multiples of the current page size. In the example below, the list will have the values of 5, 10, 15 and 20.
When using the page size selector like this, if you use the setPageSize function to set the page size to a value not in the list, the list will be regenerated using the new page size as the starting value
var table = new Tabulator("#example-table", { pagination:"local", paginationSize:5, paginationSizeSelector:true, //enable page size select element and generate list options });
Sepecifying the Page Size List
If you want to specific the available page sizes you can pass an array of integers to the paginationSizeSelector option.
var table = new Tabulator("#example-table", { pagination:"local", paginationSize:10, paginationSizeSelector:[10, 25, 50, 100], //enable page size select element with these options });
When using the page size selector like this, if you use the setPageSize function to set the page size to a value not in the list, it will be added to the top of the list
Page Size Label
When the page size selector is enabled it is diplayed to the right of a text label to make its purpose clear. If you want to change the text in this label it can be updated through the localization module
Add Row Behaviour
When using the addRow function on a paginated table, rows will be added relative to the current page (ie to the top or bottom of the current page), with overflowing rows being shifted onto the next page.
If you would prefer rows to be added relative to the table (firs/last page) then you can use the paginationAddRow option. it can take one of two values:
- page - add rows relative to current page (default)
- table - add rows relative to the table
var table = new Tabulator("#example-table", { pagination:"local", paginationAddRow:"table", //add rows relative to the table });
Managing Pagination
A number of additional controls are available to help customize the pagination experience.
Set Current Page
When pagination is enabled the table footer will contain a number of pagination controls for navigating through the data.
In addition to these controls it is possible to change page using the setPage function
table.setPage(5); // show page 5
The setPage function takes one parameter, which should be an integer representing the page you wish to see. There are also four strings that you can pass into the parameter for special functions.
- "first" - show the first page
- "prev" - show the previous page
- "next" - show the next page
- "last" - show the last page
The setPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.
table.setPage(1) .then(function(){ //run code after table has been successfully updated }) .catch(function(error){ //handle error loading data });
Load Next Page
You can change to show the next page using the nextPage function.
table.nextPage(); // load the next page
The nextPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.
table.nextPage() .then(function(){ //run code after table has been successfully updated }) .catch(function(error){ //handle error loading data });
Load Previous Page
You can change to show the next page using the previousPage function.
table.previousPage(); // load the previous page
The previousPage method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.
table.previousPage() .then(function(){ //run code after table has been successfully updated }) .catch(function(error){ //handle error loading data });
Load Page For a Specific Row
You can load the page for a specific row using the setPageToRow function and passing in any of the standard row component look up options for the row you want to scroll to.
table.setPageToRow(12); // load the previous page
The setPageToRow method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.
table.setPageToRow(12) .then(function(){ //run code after table has been successfully updated }) .catch(function(error){ //handle error loading data });
If you have a Row Component for a specific row, you can call the pageTo function on the component to load the page for that row.
row.pageTo(); //load page that contains row
Local Pagination Only
This functionality is only available on local pagination. when using remote pagination Tabulator has ow way to lookup which page the requested row is on.
Change Page Size
You can change the page size at any point by using the setPageSize function. (this setting will be ignored if using remote pagination with the page size set by the server)
table.setPageSize(50); // show 50 rows per page
Get Page Size
To retrieve the number of rows allowed per page you can call the getPageSize function:
var pageSize = table.getPageSize(); // returns number of rows allowed per page
Get Current Page Number
To retrieve the current page use the getPage function. this will return the number of the current page. If pagination is disabled this will return false.
table.getPage(); // returns current page
Get Maximum Page Number
To retrieve the maximum available page use the getPageMax function. this will return the number of the maximum available page. If pagination is disabled this will return false.
table.getPageMax(); // returns maximum page
Callbacks
A range of callbacks are available for pagination. See the Pagination Callbacks section for more information.