Persistent Configuration
Overview
Tabulator can store a variety of table setup options so that each time a user comes back to the page, the table is laid out just as they left it.
var table = new Tabulator("#example-table", { persistence:true, //enable table persistence });
Persistence Types
Tabulator can persist a variety of different table configuration options. By setting the persistence property to true the table will persist the sort, filter, headerFilter, group (groupBy, groupStartOpen, groupHeader), pagination (paginationSize, currently selected page), and column (title, width, visibility, order) configuration of the table
var table = new Tabulator("#example-table", { persistence:true, //enable table persistence });
For more granular control of what is persisted you can pass an object to the persistence property:
var table = new Tabulator("#example-table", { persistence:{ sort: true, //persist column sorting filter: true, //persist filters headerFilter: true, //persist header filters group: true, //persist row grouping page: true, //persist page columns: true, //persist columns } });
Persistent Sort
You can ensure the data sorting is stored for the next page load by setting the sort property of the persistence option to true
This will persist all active column sorts on the table
var table = new Tabulator("#example-table", { persistence:{ sort: true, //persist sort } });
Note: Only built-in sorters can be stored (including module), custom sorter functions cannot be persistently stored.
Persistent Filters
You can ensure that programatic data filtering is stored for the next page load by setting the filter property of the persistence option to true
This will persist all active column filters on the table
var table = new Tabulator("#example-table", { persistence:{ filter: true, //persist filters } });
Built In Filters
Only built-in filters can be stored (including module), custom filter functions cannot be persistently stored.
Header Filters
This option only perists filters set programatically, eg using the setFilter function. If you want to persist header filters, you need to use the headerFilter option.
Persistent Heeader Filters
You can ensure the data header filters are stored for the next page load by setting the headerFilter property of the persistence option to true
This will persist all active column header filters on the table
var table = new Tabulator("#example-table", { persistence:{ headerFilter: true, //persist header filters } });
Built In Filters
Only built-in filters can be stored (including module), custom filter functions cannot be persistently stored.
Persistent Row Grouping
You can ensure the row grouping settings are stored for the next page load by setting the group property of the persistence option to true
This will persist the current values of the groupBy, groupStartOpen, groupHeader options
var table = new Tabulator("#example-table", { persistence:{ group: true, //persist row grouping } });
If you want more control over which group options are persisted you can pass an object to the group property:
var table = new Tabulator("#example-table", { persistence:{ group:{ groupBy: true, //persist only the groupBy setting groupStartOpen: false, groupHeader: false, } } });
Persistent Pagination
You can ensure the pagination settings are stored for the next page load by setting the page property of the persistence option to true
This will persist the current values of the paginationSize option and the currently selected page
var table = new Tabulator("#example-table", { persistence:{ page: true, //persist pagination settings } });
If you want more control over which page options are persisted you can pass an object to the group property:
var table = new Tabulator("#example-table", { persistence:{ page: { size:true, //persist the current page size page:false, //do not persist the current page } } });
Persistent Column Layout
You can ensure the layout of columns is stored for the next page load by setting the columns property of the persistence option to true
This will persist the current values of the title, width, visible options as well as the order of the columns
var table = new Tabulator("#example-table", { persistence:{ columns: true, //persist column layout } });
Note: If you update the column definition array after the the column layout has been stored, Tabulator will attempt to match the stored columns against the new definition. If you have any issues with column definitions updating then you will have to change the persistenceID or delete your cookies/local storage to clear out the old column layout information.
Custom Column Definition Monitoring
If you would prefer to persist additional column definition properties you can instead pass an array of the definition property keys to be watched, these will be stored whenever the column definitions are updated:
var table = new Tabulator("#example-table", { persistence:{ columns: ["width", "visible", "frozen"], //persist changes to the width, visible and frozen properties } });
Note: If you are going to use this mode of operation the property must exist in the column definition when the column is first initialized. Tabulator can only monitor properties that have been changed not those that have been added.
Persistence Mode
Persistence information can either be stored in a cookie or in the localSotrage object, you can use the persistenceMode to choose which. It can take three possible values:
- local - (string) Store the persistence information in the localStorage object
- cookie - (string) Store the persistence information in a cookie
- true - (boolean) check if localStorage is available and store persistence information, otherwise store in cookie (Default option)
var table = new Tabulator("#example-table", { persistenceMode:"cookie", //store persistence information in a cookie });
Custom Persistence Modes
You can extend the table with your own persistence modes by extending the reader and writer objects on the module. See the Persistence Module Documentation for more information
Custom Persistence Functions
If you would like to use an alternative storage method to cookies or local storage, you can override the modules reader and writer functions using the persistenceWriterFunc and persistenceReaderFunc options. It is important that if you use this method that you use both of the options defined below as one is needed to store the config data and the other to retrieve it.
When storing persistence data Tabulator stores one object per type of data being recorded (sort, filter, group, page, columns). This approach ensures itdoes not have to regenerate the entire persistence object when one value changes. The reader and writer functions handle this by being passed in the type as an argument to the functions.
Tabulator will also set a persistence ID for the table to ensure that if you have multiple tables on a page the persistence from one table is not loaded into another, this is passed into the id argument of the functions.
Persistence Data Writer Function
The persistenceWriterFunc function will receive three arguments, the persistance id of the table, the type of data to be written and an object or array representing the data
var table = new Tabulator("#example-table", { persistenceWriterFunc:function(id, type, data){ //id - tables persistence id //type - type of data being persisted ("sort", "filter", "group", "page" or "columns") //data - array or object of data localStorage.setItem(id + "-" + type, JSON.stringify(data)); }, });
Persistence Data Reader Function
The persistenceReaderFunc function will receive two arguments, the persistance id of the table, and the type of data to be written. This function must synchronously return the data in the format in which it was passed to the persistenceWriterFunc function. It should return a value of false if no data was present
var table = new Tabulator("#example-table", { persistenceReaderFunc:function(id, type){ //id - tables persistence id //type - type of data being persisted ("sort", "filter", "group", "page" or "columns") var data = localStorage.getItem(id + "-" + type); return data ? JSON.parse(data) : false; }, });
Persistence ID
If you are planning on having multiple tables on the same page using persistence then Tabulator needs a way to uniquely identify each table. There are two ways to do this either set the id attribute on the element that will hold the table, Tabulator will automatically use this id as a reference for the persistence id.
<div id="example-table"></div>
Alternatively if you do not want to give an id to the table holding element you can set the tabulator options parameter persistenceID to a unique persistence id for that table.
var table = new Tabulator("#example-table", { persistence:true, //enable persistence persistenceID:"example1", //id string, can only be numbers, letters, hyphens and underscores. });
Manual Column Layout
Get Column Layout Information
If you want to handle column layout persistence manually, for example storing it in a database to use elsewhere, you can use the getColumnLayout function to retrieve a layout object for the current table.
var columnLayout = table.getColumnLayout();
Set Column Layout
If you have previously used the getColumnLayout function to retrieve a tables layout, you can use the setColumnLayout function to apply it to a table.
table.setColumnLayout(columnLayout);