Job Opportunity - JavaScript Developer
Under Development
This version is currently under development and should not be used in a production environment.

Release Notes

Release 5.0-alpha (Technology Preview)

Installing

The current 5.0 release is still in alpha so you will need to add @alpha to your npm install command to access the 5.0 release

npm install tabulator-tables@alpha --save

Community Feedback

The aim of this release is to gain community feedback into the direction of the library. If you have any feedback please reply to the GitHub Discussion Thread.

Bug Reporting

Please do not raise any bug reports against this release just yet, it is still under active development and should be considered unstable. The process of migrating the codebase to its new structure has undoubtedly introduced numerous small regressions into the modules which will be fixed before the beta release.

When the beta release is made available in a few weeks, I will then begin accepting bug reports on this release. Though if you spot a simple error and want to make a pull request to fix it, please feel free.

Documentation

There have been substantial changes to the library in this release, and whilst I have made every effort to ensure that the documentation has been fully updated, given the scale of the changes it is likely that some errors have crept in. If you spot any problems with the documentation, please create an issue on the GitHub Repo.

New Features

It is also worth noting that this alpha release only includes the core technology updates to the code base. The roadmapped new features will be added before the beta release.

Unit Testing

As part of this release I would love to add some unit tests to help speed up future development and testing. I am looking for members of the Tabulator community to come forward with recommendations for a unit testing framework, and ideally to help integrate it in to Tabulator.

Support

It has taken months of hard graft to get this release ready, if you fancy buying a drink for a weary developer that builds all of Tabulator in his free time, then please head over to the Support Page

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 built 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, helps 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 internal events on the 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 memory/processing saving 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 manageable.

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 - Compatability pollyfills for IE11
        • jquery_wrapper.js - JQuery wrapper
      • /core - Sorce 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 the theme, making it easier to maintain the core table styling.

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

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.

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 exclusively 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';

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.

To help with this there are several new features available in this release. 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.

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.

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 table 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 a 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 contains a detailed list of all the built-in internal events, along with a guide on how to dispatch and subscribe to events.

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 number of 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. Checout the Upgrade Guide

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, it allows you to register multiple subscribers to any event and also to unsubscribe from events at any point.

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 constructed. the 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 execution. as such the 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 on the event.

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

//subscribe to event
table.on("dataLoaded", function(data){
  //data has been loaded
});

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

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

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 dataLoadedEvent = function(data){
  //data has been loaded
}

//subscribe to event
table.on("dataLoaded", dataLoadedEvent);

//unsubscribe from event
table.off("dataLoaded", dataLoadedEvent);

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

Interaction Module

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 memory/processing saving 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.

Internet Explorer

Core JS

Tabulator is no longer packaged with a polyfill library for legacy browsers. If you wish to continue using Tabulator in IE 11 then you will need to use the Core JS Polyfill Library to provide the polyfill functionality

To ensure full compatibility with IE, it is recommended that you include the Core JS Pollyfill Library in your project before requiring Tabulator.

Proxy

Tabulator components are now wrapped in JavaScript Proxy objects to allow mapping of functions from modules. Unfortunatly this API is not available in IE11.

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

End of IE Support

Tabulator 5.x will be the last version to support the legacy Internet Explorer browsers. As of version 6.0 (currently scheduled for early 2023) there will be no further support for IE.

Bug Fixes

V5.0.0 Release

The following minor updates and bug fixes have been made:

  • Fixed issue with custom writers not being correctly registered in the persistence module
  • The print function now defaults to the printRowRange option when no range argument is defined