Version 6.3 Released!

Click to checkout the new features
Old Documentation
You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Upgrade Guide v3.5 to 4.0

Removal of jQuery

The core code of version 4.0 of Tabulator is now dependency free! That means no more jQuery, which means there are a few changes that need to be made to your existing code to get on board with the new way of doing things.

For a start this will mean that you no longer need to pull in any jQuery libraries with your code.

jQuery Wrapper

The process of converting away from jQuery can be quite time consuming so for those of you that want to keep on using the jQuery jQuery method of instantiating and function calls, not to worry, we now include a jQuery wrapper in /src/js/jquery_wrapper.min.js, as long as you include it in tour project after the Tabulato src files, you should be able to keep going as you are.

When using the wrapper you will still need to make sure that you use DOM Nodes instead of jQuery elements when returning from function or passing in arguments, the Editor and Formatter Return values and jQuery Element Values sections below will explain more.

New Instantiation Method

Now that we have removed jQuery, you can no longer use the jQuery UI widget to instantiate your table:

$("#example-table").tabulator({
	//table setup options
});

You now need to instantiate the Tabulator class, this will return a new Tabulator object that you can call all of the usual functions on. The first argument should be either a CSS selector for the table holding element or the DOM node of the table holding element The second argument should be your usual configuration object:

var table = new Tabulator("#example-table", {
	//table setup options
});

New Function Calls

With the removal of jQuery you no longer need to call the tabulator method on the selector to call a function

$("#example-table").tabulator("getRow", 1);

You can now call the function directly on your table object:

table.getRow(1);

Replacement By Regex

As there can be a lot of code to change for this, i found using a reg-ex find and replace to be the fastest solution. below are a couple of reg-ex's i have used for bulk find and replace. In the examples below you will need to replace the #example-table selector in the find regex with the selector for your table, and the table variable in the replace statement with your own variable name.

Find and replace functions with arguments:

//find
\$\("#example-table"\)\.tabulator\("([A-z]*)",

//replace
table.$1(

Find and replace functions without arguments:

//find
\$\("#example-table"\)\.tabulator\("([A-z]*)"\)

//replace
table.$1()

Editor and Formatter Return values

Any function that previously accepted a jQuery element as a return value, such as an editor or a formatter, will instead accept a DOM Node, if you were returning HTML previous then this will not affect you.

You can either completely rewrite your custom editor/formatter to remove the jQuery. or if you want to keep jQuery in your project and just want to upgrade to v4.0 then you need to adjust your function so that instead of returning a jQuery element:

var customEditor = function(cell, onRendered, success, cancel){
	var editor = $("<input></input>");
	return editor;
}

It should now return the DOM element from the jQuery, which as luck would have it we can access by looking for the first element in the array that the jQuery element returns, so you just need to append a [0] to your return statement.

var customEditor = function(cell, onRendered, success, cancel){
	var editor = $("<input></input>");
	return editor[0];
}

jQuery Element Values

Any function or property that previously accepted a jQuery element will instead accept a DOM node. You can either go through and change all of these statements, or as with the above example, pass the [0] of the jQuery element

Default Options

If you want to change the default options on a table, these now need to be changed on the defaultOptions object on the Tabulator prototype rahter that through a jQuery extend.

$.widget("ui.tabulator", $.ui.tabulator, {
    options: {
        resizableColumns:true,
        layout:"fitColumns"
    },
});

Should now be:

Tabulator.prototype.defaultOptions.resizableColumns = true;
Tabulator.prototype.defaultOptions.layout = "fitColumns";

As it was previously this needs to be done before any tables are created or they will not pickup the new default values.

NPM Package Change

With the removal of jQuery from the project, it seems sensible to change the NPM package.

The old jquery.tabulator package has been deprecated and will no longer be updated, all future updates will appear on the new tabulator-tables package.

To use the latest code you will need to remove the old package using NPM:

npm uninstall jquery.tabulator

And then install the new package:

npm install tabulator-tables --save

You will also need to replace any require statements in your code that pulled in the old package:

require('jquery.tabulator');
With require statements for the new package 
require('tabulator-tables');

Ajax Updates

The Ajax system has been overhauled an now uses the built in fetch API rather than the jQuery function.

This means any ajax config objects passed into the setData function or the ajaxConfig setup property need to be converted from using the jQuery ajax config options:

var table = new Tabulator("#example-table", {
	ajaxConfig: {
		type:"post", //set request type to Position
		contentType: 'application/json; charset=utf-8', //set specific content type
	}
});

To using the fetch API config options:

var table = new Tabulator("#example-table", {
	ajaxConfig: {
	    method:"post", //set request type to Position
	    headers: {
	        "Content-type": 'application/json; charset=utf-8', //set specific content type
	    },
	}
});

A full list of the available config options can be found on the Fetch API Documentation.

Promises

Tabulator now takes full advantage of the Promise API to make it easier than ever to run asynchronouscommands in the correct order.

On the whole the switch to using Promises should have no impact on most functions as the promise is now returned from functions that previously had no return.

However the setPage, nextPage and previousPage functions that used to return booleans as success indicators:

var success = table.setPage(1);

if(success){
	//successful
}else{
	//failure
}

Now return promises instead:

table.setPage(1)
.then(function(){
	//success;
})
.catch(function(error){
	//failure
})

Extensions Renamed to Modules

The modular extensions that allow Tabulator to be packed full of features have now been renamed to Modules, at the moment that change is only skin deep and means the extendExtension function:

Tabulator.extendExtension("format", "formatters", {
    bold:function(cell, formatterParams){
        return "" + cell.getValue() + ""; //make the contents of the cell bold
    },
});

Has been renamed to extendModule:

Tabulator.prototype.extendModule("format", "formatters", {
    bold:function(cell, formatterParams){
        return "" + cell.getValue() + ""; //make the contents of the cell bold
    },
});

This is part of a bigger change that will be coming over the next year, on the roadmap to v5.0 where modules will become self contained pages of functionality that can inject functions onto the core Tabulator object and listen to lifecycle events from the table allowing anyone to write a module that can add awesome new features to Tabulator.

Callback Context

All callbacks now have the context of the Tabulator object so you can make calls to the table directly on the this variable.

So where you used to have to explicitly call a function on the parent table:

$("#example-table").tabulator({
    dataLoaded:function(data){
        var firstRow = $("#example-table").tabulator("getRows")[0];

        if(firstRow){
            firstRow.freeze();
        }
    },
});

You can now call it on this.

var table = new Tabulator("#example-table", {
    dataLoaded:function(data){
        var firstRow = this.getRows()[0];

        if(firstRow){
            firstRow.freeze();
        }
    },
});

Clipboard Styling

The clipboard module has been update and now copies the tables style along with the data to give a better visual appearance when pasted into other documents.

This functionality is included by default, if you want to only copy the unstyled data then you should set the clipboardCopyStyled option to false in the table options object:

var table = new Tabulator("#example-table", {
	clipboard:true,
	clipboardCopyStyled:false,
});

Pagination URL Generation

The paginator property for generating the pagination URL has been removed, to be replaced with the more general purpose ajaxURLGenerator function.

The old paginator option:

var table = new Tabulator("#example-table", {
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginator: function(url, pageNo, pageSize, ajaxParams ){
        //url - the url from the ajaxURL parameter
        //pageNo - the requested page number
        //pageSize - the value of the paginationSize parameter
        //ajaxParams - the value of the ajaxParams parameter

        return ""; //must return the string of the page request URL
    },
});

The has been replaced be the new general purpose ajaxURLGenerator function, the pagination information such as page number and page size is now passed in the params argument:

var table = new Tabulator("#example-table", {
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    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
    },
});

IE Polyfills

Some of the core functionality of Tabulator has been migrated to using some of the newer JavaScript API's, as a result if you want your table to be compatible with IE you will need to include a couple of polyfills in your code.

Promises

Tabulator makes extensive use of the JavaScript Promise object to allow the table to work asynchronously. Unfortunatly this API is not available in IE11.

In order for Tabulator to work correctly you will need to install a polyfill to add the required functionality. We recommend taylorhakes/promise-polyfill for its small size and compatibility

Ajax

Tabulator uses the Fetch API to make its ajax requests for data. If you are using any ajax functionality and need Tabulator to work in IE 11 you will need to install a polyfill to add the required functionality.

We recommend github/fetch for its small size and compatibility

Removal Of Deprecated Functionality

The following deprecated functionality now been removed from Tabulator

Download Data Mutator

Deprecated Function

Setting the data download mutation function using the downloadDataMutator option:

$("#example-table").tabulator({
	downloadDataMutator:function(){},
});

Replacement Function

This has been replaced with the downloadDataFormatter option:

$("#example-table").tabulator({
	downloadDataFormatter:function(){},
});

Mutation Type

Deprecated Function

Binding the mutator callback to a given type of mutation using the mutateType option:

{title:"age", field:"age", mutator:ageMutator, mutatorParams:{limit:18}, mutateType:"edit"}

Replacement Function

You should now use the mutator option matching the type of event you want to bind to:

$("#example-table").tabulator({
	{title:"age", field:"age", mutatorEdit:ageMutator, mutatorEditParams:{limit:18}}
});

Persistence ID

Deprecated Function

Setting the persistent storage ID using the persistentLayoutID option:

$("#example-table").tabulator({
	persistentLayoutID:"table1",
});

Replacement Function

This has been replaced with the persistenceID option:

$("#example-table").tabulator({
	persistenceID:"table1",
});

Persistence Mode

Deprecated Function

Enabling column layout persistence and setting the persistent storage mode using the persistentLayout option:

$("#example-table").tabulator({
	persistentLayout:"cookie", //enable persistent column layout and set id
});

Replacement Function

You should now set the storage mode using the persistenceMode option and enable persistent column layouts with the persistentLayout option:

$("#example-table").tabulator({
	persistenceMode:"cookie", //set persistent storage mode
	persistentLayout:true, //enable persistent column layout
});

Email Formatter

Deprecated Function

Creating a mailto link using the email formatter:

{title:"Email", field:"email", formatter:"email"}

Replacement Function

This has been replaced with the link formatter with the new formatterParams of urlPrefix set to mailto::

{title:"Email", field:"email", formatter:"link", formatterParams:{urlPrefix:"mailto:"}}

fitColumns Setup Option

Deprecated Function

Setting the layout mode to fitColumns using the fitColumns option:

$("#example-table").tabulator({
	fitColumns:true, //enable fit columns layout mode
});

Replacement Function

This has been replaced with the layout option which allows the mode to be set to a number of different options including fitColumns:

$("#example-table").tabulator({
	layout:"fitColumns", //enable fitColumns layout mode
});

Get Filters

Deprecated Function

Getting the current filters using the getFilter function:

var filters = $("#example-table").tabulator("getFilter");

Replacement Function

This has been replaced with the getFilters function:

var filters = $("#example-table").tabulator("getFilters");

Get Sorters

Deprecated Function

Getting the current sorters using the getSort function:

var sorters = $("#example-table").tabulator("getSort");

Replacement Function

This has been replaced with the getSorters function:

var sorters = $("#example-table").tabulator("getSorters");

Header Tooltip

Deprecated Function

Setting a columns header tooltip using the tooltipHeader property in its column definition array:

{title:"name", field:"name", width:40, align:"center", tooltipHeader:true},

Replacement Function

This has been replaced with the headerTooltip property:

{title:"name", field:"name", width:40, align:"center", headerTooltip:true},

Ajax Sort Parameters

Ajax sorting now sends all current sorts instead of just the first, for more information checkout the Ajax Sorting Documentation

Deprecated Function

Setting the sort and sort_dir properties in the paginationDataSent option:

$("#example-table").tabulator({
	paginationDataSent:{
		"sort":"sort",
		"sort_dir":"sort_dir",
	}
});

Replacement Function

Sort data is now passed as an array to the sorters property of the paginationDataSent option:

$("#example-table").tabulator({
	paginationDataSent:{
		"sorters":"sorters",
	}
});

Ajax Filter Parameters

Ajax sorting now sends all current filters instead of just the first, for more information checkout the

Deprecated Function

Setting the filter, filter_value and filter_type properties in the paginationDataSent option:

$("#example-table").tabulator({
	paginationDataSent:{
		"filter":"filter",
		"filter_value":"filter_value",
		"filter_type":"filter_type",
	}
});

Replacement Function

Filter data is now passed as an array to the filters property of the paginationDataSent option:

$("#example-table").tabulator({
	paginationDataSent:{
		"filters":"filters",
	}
});
Donate