Old Documentation

You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Release Notes

Codebase Rebuild
Installing Tabulator
Initialization
Dependencies
Developer Tools
Module Building
Renderers
Data Loading
Columns
Rows
Events
User Interaction
Formatters
Sorting
Downloaders
Internet Explorer
Bug Fixes

Codebase Rebuild

With the release of version 5.0 Tabulator has undergone a complete rebuild of the codebase.

As Tabulator has grown in complexity and size, so has its codebase, making it harder to maintain and test and very big to download. In this release all of these issues have been addressed.

This release also aims to make Tabulator more accessible to developers, opening up the code and making it easier for you to build your own modules for the table.

Codebase Restructure

While the rest of the release notes will go over the practical implications of the updates in this release, this section will take you through some of the behind the scenes changes that have occurred.

Class Structures

To make the codebase easier to maintain it has been broken down in to much smaller files, and switched from the old prototypical design paradigm to using the cleaner ES6 Class structure.

ESM Importing

Tabulator has moved to using ESM importing of the library as standard (don't worry, the UMD require functionality is still available if needed), and by default will now only import the minimal core library, that provides basic table layout functionality. You can then import only the modules that you actually need to use to run your table.

This has significantly reduced the size of the library when it is imported, as well as reducing the loading and render time of the table as there are less modules to initialize.

For developers looking for a quick setup, there is still an option for importing a complete version of Tabulator with all the modules pre loaded.

Communication & Event Bus

Communication throughout the table is now managed through a central event bus that decouples each area of the system from each other, to help isolate code, improve testing and increase communication efficiency.

A second event bus now manages all external communication outside of the table, with old style callbacks on the table now being replaced with events that you can subscribe to.

Module Isolation

One of the big drives of this update has been to make it simple for anyone to create their own module to extend Tabulator and add any missing functionality they may like. As a result of this there is now a guide on creating your own modules, and in the next couple of months you will be able to show case your own modules on the Tabulator site.

To aid this, modules have been completely restructured to totally isolate their functionality from each other and the rest of the table. This has improved module reliability, simplifying the development process and improving testability.

As part of this release all modules have been isolated from Tabulators core logic, but the work of isolating the existing modules from one another will happen in stages over the next few releases due to the scale of the challenge with the legacy code base.

Modules are now also responsible for registering any options, callbacks or events that they use on the table, components or column definitions, allowing developers to easily build in user configurable custom functionality.

Modules now include a range of built-in helper function that allow safe interactions with the rest of the table and other modules.

Data Loader

A central data loader now manages all data as it is loaded into the table, this handles all local data, as well as triggering events on the internal event bus that allow modules to subscribe and provide data from remote sources such as ajax and databases.

The result of this is that the Ajax module is no longer responsible for loading remote data into the table, it is simply responsible for making ajax requests when triggered by a data load event. this means it is now easy to build your own custom remote data loading module and add it to the table.

Data Management Pipeline

The data and row management pipelines have been overhauled to allow modules to register themselves as a pipeline state, allowing modules to directly alter the rows displaying in the table as they are rendered

Event Listeners

A new interaction manager has been added to the core of Tabulator that listens to all standard table events (click, tap, mouse etc) through the main table element and then links these back to the relevant components for processing. This has resulted in a dramatic reduction memory usage and processing time as the whole table only runs off of a handful of event listeners rather than the 1000's it used to.

Table Renderers

Renderers (eg virtual DOM / basic) have been separated from the row management logic to make managing the render of the table simpler and more extensible.

The table renderers have been optimized to reduce redrawing during scroll, improving table load times and scroll efficiency, resulting in a smoother experience for end users.

Class Structures

All code has now been migrated to use the ES6 class structure to improve the readability of the code.

The codebase has also been broken down into considerably smaller files to improve readability and maintainability.

File Structure

The directory structure of the sources has been updated to make the role of each of the files clearer:

/src - The source files for Tabulator, make your changes in this directory
- /js - This folder contains the JS source. The core files are in the root of this folder
  - /builds - Build files that structure each of the different types of dist file
    - esm.js - Builder for the tabulator_esm.js file
    - umd.js - Builder for the tabulator.js file
    - polyfill.js - Compatibility polyfills for IE11
    - jquery_wrapper.js - JQuery wrapper
  - /core - Source files for the core Tabulator framework
    - /renderers - Built-in vertical and horizontal renderers
    - /tools - Core tools used throughout the system
  - /modules - Sources files for each of the modules
- /scss - The source scss files for the CSS style sheets, this folder contains one file per theme. for themes based on other frameworks like bootstrap there is a folder that contains the tabulator stylesheet and a variables file containing the SCSS from the other framework
/dist - All files contained in this folder are automatically generated by rollup

Build Tools

Module Builder

Tabulator has switched to using the Rollup Module Builder as its packaging solution.

Build Commands

The npm build commands have been improved to give more control over the development experience:

Regenerate the contents of the /dist folder

npm run build

Watch for changes in the source and regenerate the contents of the /dist folder (ESM and CSS files)

npm run dev

Watch for changes in the SCSS and regenerate only the CSS files

npm run dev:css

Watch for changes in the JavaScript and regenerate only the tabulator_esm.js file

npm run dev:esm

Watch for changes in the JavaScript and regenerate only the tabulator.js file

npm run dev:umd

Styling and Themes

Theme Extensions

The SCSS files for themes have been rewritten to import the base SCSS stylsheet for Tabulator and then extend any parts needed for that theme, making it easier to maintain the core table styling.

The package.json file has been updated to make it easier to import the default CSS into your project

@import  "tabulator-tables";

Theme Files

All themes have been moved into the root of the /dist/css/ folder and now include minified versions and source maps.

Some theme files have been renamed to improve naming consistency.

You still only need to pull in the one theme CSS file when importing Tabulator into your project

Class Naming

To improve consistency, all class names have been updated to kebab case, meaning the table-tableHolder is now table-tableholder

Prototype Functions

All functions that used to be accessible through the prototype are now accessible directly from the Tabulator class

Default Options

Default options can now be set on the defaultOptions object directly on the Tabulator class:

Tabulator.defaultOptions.movableRows = true;
Tabulator.defaultOptions.layout = "fitColumns";

Extending Modules

Modules can now be extended by calling the extendModule function directly on the Tabulator class

Tabulator.extendModule("format", "formatters", {
  bold:function(cell, formatterParams){}
});

Finding Tables

You can find tables by calling the extendModule function directly on the Tabulator class

var table = Tabulator.findTable("#example-table")[0]; // find table object for table with id of example-table

Deprecated Code

All 4.x deprecated code has been removed from the codebase. The updated functionality for each of the deprecated options can be found in the upgrade documentation for the relevant release

Installing Tabulator

Importing The Library

Tabulator has now moved to using ESM modular imports, so must now be included into projects using the import directive.

import {Tabulator} from 'tabulator-tables';

Core With Optional Modules

As Tabulator has grown to include 100's of features, so has its codebase, meaning that even simple tables used to mean including 500kb of library in their site.

To allow Tabulator to grow without rapidly increasing file sizes, the library has been broken down into a series of optional modules.

You now import the core Tabulator class, that includes the minimal JavaScript needed to build the table, you then import only the modules that you need to add functionality to your table.

You then register those modules with the Tabulator class, using the registerModule function before you instantiate your first table. This function takes one argument of either a module class or an array of module classes. If needed you can call this function multiple times.

import {Tabulator, FormatModule, EditModule} from 'tabulator-tables';

Tabulator.registerModule([FormatModule, EditModule]);

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

A full list of modules can be found in the Modules Documentation

Full Library

If you would prefer to include the whole Tabulator library in your project, complete with all the built-in modules, you can instead import TabulatorFull, this will pre-register all modules.

import {TabulatorFull as Tabulator} from 'tabulator-tables';

Initialization

Tabulator has now moved to an asynchronous initialization process.

This allows a consistent initialization experience between async and synchronous data sources, and allows binding of the new events system to the table before initialization is completed, to catch things like the tableBuilt event.

As a result of this it is no longer possible to call functions that change the setut of the table such as setData and setColumns straight after the table constructor.

In the first instance you should use the data and columns options to set these in the table constructor

var table = new Tabulator("#example-table", {
  data:[],
  columns:[],
});

But if you do need to call them straight after table initialization for whatever reason, you should call them after the tableBuilt event, which indicates the table has been initialized and is ready to be updated

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

//update columns after it is built
table.on("tableBuilt", function(){
  table.setColumns(columns);
});

Dependencies

As before, the Tabulator core remains free of any dependencies. As part of this release module functionality that was dependent on 3rd party libraries has been updated to use the latest versions of those libraries.

Luxon

In previous version of the library Tabulator used the moment.js library for date and time manipulation. In this release this has now been replaced with the much more compact luxon.js library.

JS PDF

The PDF downloader now uses the latest version of the jspdf library to generate its PDF file.

Developer Tools

A major aim of this update is to make Tabulator more accessible to developers, to give you the tools you need to modify and enhance the table, and to contribute to the library.

There is now a range of debug options built into Tabulator that will console log various table actions so you can see how your code is affecting table functionality.

You will notice the new Development Concepts section at the bottom of the menu sidebar. This contains a range of documentation aimed at helping developers understand more about the internal workings of Tabulator.

Invalid Options Warning

Enabled by default this will provide a console warning if you are trying to set an option on the table that does not exist. With the new optional modular structure this is particularly valuable as it will prompt you if you are trying to use an option for a module that has not been installed.

You can disable this using the debugInvalidOptions option in the table constructor:

var table = new Tabulator("#example-table", {
  debugInvalidOptions:false, //disable option warnings
});

Monitor External Event Bus

The debugEventsExternal option will create a console log for every external event that is fired so you can gain an understanding of which events you should be binding to.

var table = new Tabulator("#example-table", {
  debugEventsExternal:true, //console log external events
});

Passing an array of event keys into this option will restrict the console logging to just the events you want to see.

var table = new Tabulator("#example-table", {
  debugEventsExternal:["dataLoading", "dataLoaded"],
});

Monitor Internal Event Bus

The debugEventsInternal option will create a console log for every internal event that is fired so you can gain an understanding of which events you should be subscribing to in your modules.

var table = new Tabulator("#example-table", {
  debugEventsInternal:true, //console log internal events
});

Passing an array of event keys into this option will restrict the console logging to just the events you want to see.

var table = new Tabulator("#example-table", {
  debugEventsInternal:["data-loading", "data-loaded"],
});

Warning Tabulator fires a large amount of internal events, running with this enabled will slow the table down considerably. You should ensure you are only running this option with a table containing a small amount of data

Module Building

As mentioned above, one of the main focuses of this release has been to put you, the developer, in control of Tabulator. To this end the module functionality has had a complete overhaul to make it easier than ever to build your own custom modules.

Module Classes And Helpers

There is now a new Module base class, that is packed full of helper functions to make it easier than ever to access internal table functionality in a clean, safe and decoupled way.

The Module Building Documentation contains a detailed guide of how to setup and register a new module with Tabulator as well as a detailed run through of each of the helper functions built into the Module base class.

Example Modules

Building out your own module can be a bit daunting at first, with so many options it can be hard to know where to start.

To help with this there is now Module Examples Page that contains a series of step by step guides to building out practical and functional modules.

Internal Events

Tabulator now uses an internal event bus to handle communication between modules and the Tabulator core, and help keep Tabulators internal logic isolated from module logic.

The Internal Event Bus Documentation contains a detailed list of all the built-in internal events, along with a guide on how to dispatch and subscribe to them.

Renderers

Renderers have now been separated out from the core table logic into classes of their own that implement a standard interface.

This will make it easier to maintain each module and make it much easier for other developers to contribute updates to the core rendering systems and even build whole new renderers to meet different needs.

Classic Renderer Rename
The old classic renderer has been renamed to "basic" to make it clearer that it is a simple renderer compared to the virtual option.

Defining Renderers

Now that renderers have been separated, there is no longer a virtualDom option for turning on/off the virtual DOM. Instead there are now two options tht can be used to set the renderer for the horizontal rows and horizontal columns.

Vertical Renderers

The vertical renderer can now be set using the renderVertical option:

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

This option can be one of two built in renderers:

virtual (default) - the virtual renderer that uses virtual DOM techniques to render only the visible area of the table
basic - renders all rows at once

Horizontal Renderers

The horizontal renderer can now be set using the renderHorizontal option:

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

This option can be one of two built in renderers:

virtual - the virtual renderer that uses virtual DOM techniques to render only the visible area of the table
basic (default) - renders all columns at once

Custom Renderers

It is now also possible to build out your own custom renderer by extending the Renderer class and passing it into either the renderVerticalrenderHorizontal options

import {Tabulator, Renderer} from 'tabulator-tables';

//define renderer
class CustomRenderer extends Renderer{
  //build out your renderer
}

//define table
var table = new Tabulator("#example-table", {
  renderVertical:CustomRenderer,
});

For full details on how to build your own custom renderer, checkout the Rederer Documentation

If you make any optimizations to existing renderers or create your own renderer that you would like to see included with Tabulator, feel free to Submit a pull request

Data Loading

The data loading system has had a complete overhaul in this release. As part of this the Ajax module is no longer center stage for remotely loading data into the table. There are now a series of internal events that you can to subscribe to with any custom module that will allow you to easily integrate with any other data sources.

To reflect this, a number of table options have been changed/updated to remove their links to the ajax system and make them more generically about the source of the data.

Loading Events

The old ajax loading events have been removed from the ajax module and are now generic loading events that are called whenever data is being loaded into the table.

The existing dataLoading events have been moved into the new system and now specifically refer to the process or retrieving data and loading it into the table, the dataLoaded event is now called when data has been retrieved successfully but before it is processed into the table

Data Loading

The dataLoading event is triggered whenever new data is loaded into the table.

table.on("dataLoading", function(data){
  //data - the data loading into the table
});

Data Loaded

The dataLoaded event is triggered when a new set of data is loaded into the table, but before it is processed.

table.on("dataLoaded", function(data){
  //data - all data loaded into the table
});

Data Load Error

The dataLoadError event is triggered there is an error response to a load request. This event is passed the Fetch Response Object as its first argument, which allows access to the response content, status code, etc.

table.on("dataLoadError", function(error){
  //error - the returned error object
});

Processing Events

There are now two new events for data processing, this step happens after the data is loaded into the table and covers the period where the data is processed and rendered

Data Processing

The dataProcessing event is triggered after data is loaded into the table, just as it starts being processed into rows and cells.

table.on("dataProcessing", function(){});

Data Processed

The dataProcessed event is triggered after data has been processed and the table has been rendered.

table.on("dataProcessed", function(){});

Loaders

Now that the ajax module is no longer in charge of remote data loading, the loading elements displayed during remote data loading have had their options changed to reflect their new position

Data Loader

You can disable the remote data loading message using the dataLoader option

var table = new Tabulator("#example-table", {
  dataLoader:false, //disable data loader message
});

Data Loading

You can set the contents of the data loader message element using the dataLoaderLoading option

var table = new Tabulator("#example-table", {
  dataLoaderLoading:"Data Loading",
});

Data Error

You can set the contents of the data loader error message element using the dataLoaderError option

var table = new Tabulator("#example-table", {
  dataLoaderError:"Error Loading Data",
});

Localization Mappings

With the moving of the loaders out of the ajax module, their corresponding localization mappings have also changed

var table = new Tabulator("#example-table", {
  locale:true,
  langs:{
    "en-gb":{
      "data":{
        "loading":"Loading", //data loader text
        "error":"Error", //data error text
      },
    }
  },
});

Request Modes

In previous version of Tabulator there where various options that enable ajax interactions by certain modules, such as the ajaxSorting option. Now that the ajax module is no longer the source of all remote data for the table these options have been removed and replaced with "mode" options that let you set a a mode of operation for the modules.

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

The mode property takes a text string that by default can have one of two values:

local - perform action on local data in table (default)
remote - do not perform an action in table, instead add params to remote data request

In practice, each module looks at its mode option when an action triggers a change and then decides how to handle it. By making this a text option it means you can now extend module mode functionality, adding other request modes for them to handle.

Sort Mode

You can set the mode of the sort module using the sortMode option in the table constructor

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

Filter Mode

You can set the mode of the filter module using the filterMode option in the table constructor

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

Page Mode

The page module, worked slightly differently in the past and already used a mode passed into the pagination option to enable pagination. In this release the pagination option is now a boolean that enables pagination and the paginationMode option sets its mode

var table = new Tabulator("#example-table", {
  pagination:true,
  paginationMode:"remote",
});

Request & Response Params Mapping

The paginationDataSent and paginationDataReceived options that were used to map the parameters of incoming and outgoing request parameters have been moved out of the pagination module and incorporated into the data loader. As such their names have now been changed.

var table = new Tabulator("#example-table", {
  dataSendParams:{
    page:"current_page",
    size:"page_size",
  },
  dataReceiveParams:{
    last_page:"last",
    size:"page_data",
  }
});

Progressive Loading

Now that ajax functionality has been isolated from data loading the progressive load functionality has been move out of the ajax module.

As a result of this all progressive load table options have now changed name to remove the "ajax" prefix

var table = new Tabulator("#example-table", {
  progressiveLoad:"scroll",
  progressiveLoadDelay:400,
  progressiveLoadScrollMargin:300,
});

Columns

Default Column Definition Options

If you want to set the same property in every column on your table, you can use the columnDefaults option. Setting the value in this object will result in it being applied to every column in the table. You can set any Column Definition Options in this object and they will apply to all columns.

If a column needs to override the default value, then simply define the property in that columns definition object and the default will be ignored.

var table = new Tabulator("#example-table", {
  columnDefaults:{
    width:200, //set the width on all columns to 200px
  },
  columns:[
    {title:"Name", field:"name"},
    {title:"Age", field:"age"},
    {title:"Address", field:"address", width:300}, //override the column default and set this column to 300px wide
  ],
});

Old Default Column Values Removed

As a result of the new columnDefaults option, a number of table options that used to configure all rows have become redundant. Checkout the Upgrade Guide for a list of what has changed.

Rows

Get Cells Functionality

Cell components are now generated as needed by each row, meaning that as of this release the getCells and getCell functions on the row component will now work even if the row has not yet been initialized.

Events

Tabulator has moved from a callback model for events, where you would register a callback in the constructor for each event, to an event subscription model where you subscribe to each event after the table is built.

This approach has several advantages, allowing you to register multiple subscribers to any event and to unsubscribe from events at any point.

A full list of the callbacks that have been switched over to events can be found in the Upgrade Guide

Events vs Callbacks

As of version 5.0 there is now a difference in functionality between events and callbacks, with each having different purpose.

Events

Events are simple notifications that can be subscribed/unsubscribe from once the table has been initialized. they offer one way notifications that the state of the table has changed.

For a full list of available events, checkout the Events Documentation

Callbacks

Callbacks are defined in the table constructor and allow alteration of the tables fuctionality as it runs. As such they often require a return value from the function.

The one exception to this rule is cell/column header events which can also be registered as callbacks in the column definition. This functionality has been left in as it allows greater flexibility in binding events to specific columns.

For a full list of available callbacks, checkout the Callbacks Documentation

Subscribe To Events

You can subscribe to events by calling the on function on the table and passing in the name of the event and the function you wish to be triggered by the event.

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

//subscribe to event
table.on("dataProcessed", function(data){
  //data has been processed and the table rendered
});

Unsubscribe From Events

Unsubscribe All Listeners

To unsubscribe all listeners for a given event call the off function passing in the name of the event.

table.off("dataProcessed")

Unsubscribe One Listener

To a specific listener for a given event call the off function passing in the name of the event and the function that you previously subscribed too.

var dataProcessedEvent = function(data){
  //data has been loaded
}

//subscribe to event
table.on("dataProcessed", dataProcessedEvent);

//unsubscribe from event
table.off("dataProcessed", dataProcessedEvent);

Column Definition Event Callbacks

To aid in targeting individual columns with events, the event callbacks in column definitions are remaining as they were.

{title:"Name", field:"name", cellClick:function(e, cell){
    //e - the click event object
    //cell - cell component
  },
}

New & Updated Events

A number of new events have also been exposed at the table level. The section below out lines the changes, for a full list of available events, checkout the Events Documentation

Mouse Events

Mouse over events have now been added for the column headers and group headers to bring them into line with the cell and row mouse events

User Interaction

A new interaction manager has been added to the core of Tabulator that listens to all standard table events (click, tap, mouse etc) through the main table element and then links these back to the relevant components for processing. This has resulted in a dramatic reduction in memory usage and processing time as the whole table only runs off of a handful of event listeners rather than the 1000's it used to.

To partner up with this, a new interaction module has been introduced, that ties into the interaction manager to produce the table events for click, tap and mouse events. For example:

table.on("cellClick", function(e, cell){
  //e - the click event object
  //cell - cell component
});

Event Propagation

As a result of the way that the interaction manager has been built, events now propagate up the table before the external events are triggered. Which means that cell click events, especially while editing, now also propagate up to the row that contains the cell.

Formatters

Datetime

In previous version of the library Tabulator used the moment.js library for date and time formatting. In this release this has now been replaced with the much more compact luxon.js library. While offering broadly the same functionality, there has been some update to the formatterParams format properties.

Date Time Difference

In previous version of the library Tabulator used the moment.js library for date difference formatting. In this release this has now been replaced with the much more compact luxon.js library. While offering broadly the same functionality, there has been some update to the formatterParams format properties.

Downloaders

PDF Downloader

The PDF downloader now uses the latest version of the jspdf library to generate its PDF file.

Sorting

Date

In previous version of the library Tabulator used the moment.js library for date sorting. In this release this has now been replaced with the much more compact luxon.js library. While offering broadly the same functionality, there has been some update to the sorterParams format properties

Time

Datetime

In previous version of the library Tabulator used the moment.js library for date and time sorting. In this release this has now been replaced with the much more compact luxon.js library. While offering broadly the same functionality, there has been some update to the sorterParams format properties

Internet Explorer

As microsoft has now declared that Internet Explorer will be reaching End of Life next year, Tabulator will no longer be supporting the browser from version 5.0 onwards.

If you wish to continue using Tabulator on IE, then please stick to using the Tabulator 4.x releases.

Bug Fixes

v5.0.0 Release

As part of the rebuild most of the Tabulator codebase has been rewritten resulting in a large number of bugs being fixed along the way, check the git issues list for more details.