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

Release Notes

Removal of jQuery

The biggest cahnge of this update is that Tabulator is now dependency free!

The core code of version 4.0 of Tabulator is no longer dependent jQuery, which means you can now instatiate your tables and store them in a JavaScript variable. 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
});

You can now call functions directly on your table object:

table.getRow(1);

Callbacks that previously accepted jQuery objects as return values will now expect DOMNodes

For those of you that want to continue using Tabulator as a jquery widget, there is now a jQuery wrapper that you can include in your project to keep old functionality. For full details on how to use the wrapper checkout the Upgrade Guide.

Promises

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

Commands that load data into the table now return a promise that you can use to run further commands once the table has been updated.

table.setData("/mydata.php")
.then(function(){
	//success;
})
.catch(function(error){
	//failure
})

At the moment promise based functionality is available on the following functions:

  • setData
  • replaceData
  • setPage
  • nextPage
  • previousPage

Over the next few releases you will see promises being returned from more and more functions.

Ajax

The Ajax module has been completely overhauled to give you even more options for how you load your table data.

Fetch

Tabulator now uses the built in fetch API to make its ajax requests for data.

This makes little difference to the exposed api endpoints but does now mean that any configuration options passed in for the request should now be compatible with the Fetch API

Promise Function

The ajax module now uses a replaceable promise to make ajax requests.

This means that the built in request functionality can easily be replaced to route the request to a different handler.

In the example below we want to query a local JS realm db rather than makiing an ajax request so we pass a function that returns a promise to the ajaxPromiseFunc option.

function queryRealm(url, config, params){
	//return promise
	return new Promise(function(resolve, reject){
		//do some async data retreival then pass the array of row data back into Tabulator
		resolve(data);
	});
}

var table = new Tabulator("#example-table", {
	ajaxPromiseFunc:queryRealm,
});

Extensions Renamed to Modules

In preperation for furture updates to Tabulator the modular extensions that allow Tabulator to be packed full of features have now been renamed to Modules, and means that modules are now extended using the extendModule function:

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.

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

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

Param Object Lookup Functions

in all column definition parameter options you can now pass in a lookup function that returns an object instead of the object itself. This function will then be called any time the object is needed, this allows for paramters to be changed after table instantiation:

//define lookup function
function paramLookup(){
	return {target:"_blank"};
}

//column definition
{title:"Website", field:"url", formatter:"link", formatterParams:paramLookup}

Currently this is available on the following column definition params:

  • sorterParams
  • formatterParams
  • editorParams
  • mutatorParams
  • mutatorDataParams
  • mutatorEditParams
  • mutatorClipboardParams
  • accessorParams
  • accessorDataParams
  • accessorDownloadParams
  • accessorClipboardParams
  • topCalcParams
  • topCalcFormatterParams
  • bottomCalcParams
  • bottomCalcFormatterParams
  • titleFormatterParams
  • headerFilterParams
  • headerFilterFuncParams

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

Formatters

A number of changes have been made to the Formatters Module.

onRendered Callback Function

A new onRendered function is now passed into formatter functions, working in the same was as it does with editors, a function passed into this function will be triggered when the formatted cell is added to the DOM. This is useful when instatiating widgets that need the element to be visible before they are used.

The example below uses the jQuery sparkline widget to format data into a chart

var sparklineFormatter = function(cell, formatterParams, onRendered){
    onRendered(function(){
        $(cell.getElement()).sparkline(cell.getValue(), {width:"100%", type:"bar"});
    });
};

New Formatters

Date Time Formatter

The new datetime formatter has been added to allow conversion of data or time formats.

This formatter reuqires the moment.js library to use

{title:"Date of Birth", field:"dob", formatter:"datetime", formatterParams:{inputFormat:"DD/MM/YYYY hh:mm:ss", outputFormat:"YYYY-MM-DD hh:mm:ss", invalidPlaceholder:"Invalid Date"}}

Updated Formatters

A number of formatters have been updated

Link Formatter

The link formatter now takes a new target parameter to set the target for the anchor tag

//open link in new tab
{title:"Website", field:"url", formatter:"link", formatterParams:{target:"_blank"}}

TickCross Formatter

The tickCross formatter now takes two new formatterParams:

The allowEmpty param will make the tick cross formatter show an empty cell instead of a cross if the cell has a value of undefined null or ""

The allowTruthy param will make the tick cross formatter show a tick if the cell has any value that can be considered truthy

{title:"Likes Cheese", field:"cheese", formatter:"tickCross", formatterParams:{allowEmpty:true, allowTruthy:true}}

Image Formatter

The image formatter now takes two new parameters, heigh and width to specify the dimensions of the image. they take any valid CSS value

{title:"Logo", field:"logo", formatter:"image", formatterParams:{height:25, width:"50%"}}

Filtering

The filter module has had a number of upgrades:

Initial Filters

You can now set the initial filters to be applied to the table when it is first created, by passing an array of filters to the initialFilter table setup option:

var table = new Tabulator("#example-table", {
	initialFilter:[
		{field:"color", type:"=", value:"red"}
	],
});

New Regex Filter

The new regex filter function allows you to use the power of regular expressions to filter the data in your table.

table.setFilter("name", "regex", /[a-z]/);

History Availability

This history module has been updated to include two new functions.

Get Count of Available Undo Operations

You can now use the getHistoryUndoSize function to get a count of the number of history undo actions available.

var undoCount = table.getHistoryUndoSize();

Get Count of Available Redo Operations

You can now use the getHistoryRedoSize function to get a count of the number of history redo actions available.

var redoCount = table.getHistoryRedoSize();

PDF Downloads

The pdf downloader has been updated to allow a function to be passed to the autoTable option in its params object.

This function should return the AutoTable options object. The jsPDF document object will be passed in as the first argument of this function which will allow you to call any of the jsPDF API functions on the document, so you can for example add additional text to your PDF or set the font.

table.download("pdf", "data.pdf", {
    orientation:"portrait", //set page orientation to portrait
    autoTable:function(doc){
        //doc - the jsPDF document object

        //add some text to the top left corner of the PDF
        doc.text("SOME TEXT", 1, 1);

        //return the autoTable config options object
        return {
            styles: {
                fillColor: [200, 00, 00]
            },
        };
    },
});

Column Headers

The event binding order for click and touch events in the column header has now been changed so that events bound from the column definition like headerClick are now bound before any internal events like the click that triggers a header sort. This means you can now block other event bindings after the click using the events stopImmediatePropagation function

{title:"Name", field:"name", headerClick:function(e){
	e.stopImmediatePropagation(); //block header sort or other click triggered events from happening
}},

Row Component

The row component has had been updated

getTable function

The new getTable function will return the Tabulator instance for the table that contains the row.

var table = row.getTable();

isSelected function

The new isSelected function will return a boolean representing the current selection state of the row

var selected = row.isSelected();

Column Component

The column component has had been updated

Component Lookup

getColumn function

You can now call the getColumn function to look up a column component by either its field or header DOM element

var column = table.getColumn("age");

Component Functions

getTable function

The new getTable function will return the Tabulator instance for the table that contains the column.

var table = column.getTable();

headerFilterFocus function

The new headerFilterFocus function will put focus on the header filter element for this column.

column.headerFilterFocus();

setHeaderFilterValue function

The new setHeaderFilterValue function will change the value of header filter element for this column.

column.setHeaderFilterValue("Bob");

reloadHeaderFilter function

The new reloadHeaderFilter function will rebuild the header filter, updating any params passed into the editor used to generate the filter.

column.reloadHeaderFilter();

Cell Component

The cell component has had been updated

getTable function

The new getTable function will return the Tabulator instance for the table that contains the cell.

var table = cell.getTable();

Group Component

The group component has had been updated

getTable function

The new getTable function will return the Tabulator instance for the table that contains the group.

var table = group.getTable();

Bug Fixes

The following minor bugs have been fixed:

  • The groupStartsOpen function is now correctly passed the component object
  • Header filters in frozen columns are now correctly counted when calculating the header height
  • The data mutator is now only triggered on updated data fields when a row is updated, rahter than on all row data
  • Ajax sorting and filtering now expect the correct returned data format when triggering an ajax request
  • Render issues when columns were frozen on the right hand side of the table have been resolved
  • The rowDeselected callback is nor correctly triggered for each row when all rows are deselected at once
  • An incorrect event binding in the olumn resize module has been fixed
  • Validators now correctly handle paramerters that include the : character
  • The textarea formatter now correctly handles null and undefined values
  • Fixed the force arcument on the Cell Component edit function
  • Column movement by mouse drag is now only triggered off of left click instead of any mouse clicks
  • Row movement by mouse drag is now only triggered off of left click instead of any mouse clicks
  • Bug in row height normalization on row shrinking fixed
  • Fixed an issue with tabbing out of the number editor on IE reseting the cells value
  • Fixed issue in progress formatter color params
  • Pasting into empty tables on Chrome now works
  • Graphical corruption of certain arangements of grouped headers has now been resolved

Removal Of Deprecated Functionality

All functionality marked as depricated in version 3.5 has now been removed. If you are still using any of the functionality outlined below you will need to update it to the new methodology.

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:

new Tabulator("#example-table", {
	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:

{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:

new Tabulator("#example-table", {
	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:

new Tabulator("#example-table", {
	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:

new Tabulator("#example-table", {
	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 = table.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 = table.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:

new Tabulator("#example-table", {
	paginationDataSent:{
		"sorters":"sorters",
	}
});

Ajax Filter Parameters

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

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:

new Tabulator("#example-table", {
	paginationDataSent:{
		"filters":"filters",
	}
});