Release Notes

• Removal of jQuery Dependancy
• Core Files Package
• Promises
• Ajax
  • Fetch
  • URL Generator
  • Request Function
• Extensions Renamed to Modules
• Callback Context
• Param Object Lookup Functions
• Clipboard Styling
• SCSS Default Variables
• Formatters
• Filtering
• History Availability
• Pagination URL
• PDF Downloads
• Column Headers
• Row Component
• Column Component
• Cell Component
• Group Component
• Bug Fixes
• Removal of deprecated Functionlaity

Removal of jQuery

The biggest change 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 instantiate 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 element 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.

Core Files Package

In addition to the standard install options, Tabulator now comes with another option for developers that are really conscious of package size.

The core js files provide the minimal JavaScript needed to create a basic table, these are perfect for environments where optimal file sizes are needed.

Minified

<script type="text/javascript" src="dist/js/tabulator_core.min.js"></script>

Unminified

<script type="text/javascript" src="dist/js/tabulator_core.js"></script>

If you need any of the modules in addition to the core files (for example you want to include formatters with your table), then you should include these files after the core js file. The module distributions can be found in the /dist/js/modules folder.

<script type="text/javascript" src="dist/js/tabulator_core.min.js"></script>
<script type="text/javascript" src="dist/js/modulesformat.min.js"></script>

Promises

Tabulator now takes full advantage of the Promise API to make it easier than ever to run asynchronouscommands 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 table functions:

Promises are also now returned from some component object functions, which will be covered later in the release notes.

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

URL Generator Function

The new ajaxURLGenerator gives you more control over the url of the request that you can get from the ajaxURL and ajaxParams properties alone, you can pass in a callback to generate any URL you like.

The callback should return a string representing the URL to be requested.

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

Request 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 ajaxRequestFunc option.

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

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

Extensions Renamed to Modules

In preparation for future 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 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.

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

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

SCSS Default Variables

All SCSS file variables now use the !default property so you can override them from outside the imported source file.

$backgroundColor:#f00; //change background color of table

@import  "tabulator_simple"; //import table scss

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 instantiating 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 requires 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"}}

Date Time Diff Formatter

The new datetimediff formatter will display in human readable terms the difference between two dates.

This formatter requires the moment.js library to use

{title:"Last Service", field:"service_date", formatter:"datetimediff", formatterParams:{inputFormat:"DD/MM/YYYY hh:mm:ss", humanize:true, suffix:true, nvalidPlaceholder:"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"}
	],
});

Header Filter Empty Function

The behaviour of empty header filters has been tweaked to improve usability. By default Tabulator will clear the filter when it considers the header filter value to be empty, in the case of most filters that is if the value is undefined, null, or "", or in the case of check boxes that is if the value is not either true or false.

If you are using a custom filter or want to alter what an existing filter considers empty, you can pass a function to the headerFilterEmptyCheck column definition property. This function will be passed in the value of the filter as an argument and should return a boolean where true represents an empty filter

{title:"Allowed", field:"allowed", headerFilter:"tick", headerFilterEmptyCheck:function(value){
    return !value; //only filter when the value is true
}},

New Filters

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();

Pagination URL

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

details of the new function can be found in the Ajax Documentation

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

Promises

The following row component functions now return a promise

• update
• delete
• scrollTo

New Component Functions

The following new functions have been added to the row component.

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");

Promises

The following column component functions now return a promise

• scrollTo

New 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, rather 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 argument 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 arrangements of grouped headers has now been resolved
• Row height normalization calculations now correctly take into account any row contents other than cells

Removal Of Deprecated Functionality

All functionality marked as deprecated 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 property 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 property of the paginationDataSent option:

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