Beta Release - This version is currently under development and should not be used in a production environment.

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 instatiating 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 funciton or passing in arguments, the Editor and Formatter Return values and jQuery Element Values sections below will explian 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 elementm 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/formater 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 statments, or as with the above example, pass the [0] of the jQuery element

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 asyncronous commands 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){
	//successfull
}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.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 comming 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 expicity 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 appearence 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,
});

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 recomend taylorhakes/promise-polyfill for its small size and compatability

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 recomend github/fetch for its small size and compatability

Removal Of Deprecated Functionality

The following depricated 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 pproperty 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 pproperty of the paginationDataSent option:

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