Upgrade Guide v4.9 to 5.0

• Version 4.9 Upgrades
• Importing
• Initialization
• Build Tools
• Themes
• Extending Modules
• Default Table Options
• Renderers
• Finding Tables
• Column Defaults
• Callbacks
• Ajax and Data Loading
• Localization
• Request & Response Params
• Progressive Loading
• Sorting
• Formatting
• Filter
• Pagination
• Downloaders
• Cell Navigation
• Debug Options

Previous Version Upgrades

If you are upgrading from any version of tabulator below version 4.9, you should read the v4.1 to 4.9 upgrade guides first.

Importing

Import Statements

Tabulator has now moved exclusivly to using ESM modular imports, for this reason you can no longer require Tabulator into your project:

var Tabulator = require('tabulator-tables');

You must now use the following Import statement

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

You may also now need to inport additional modules for your table, for full details see the Install Setup Guide

Core With Optional Modules

In version 4.x you used to be able to pull in the core tabulator file and import modules by including individual module files from 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>

This is now achieved by importing the Tabulator class along with any required modules and then binding these together using the registerModule function on the class.

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

Tabulator.registerModule([FormatModule, EditModule]);

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.

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

table.setData(data);

Initialization Values

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

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

Functional Update

If you do need to call these functions 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);
});

Build Tools

In version 4.x you used to trigger the build tools to watch for changes using the watch command

npm run watch

To achieve this you should now use the dev command

npm run dev

Extending Modules

When extending modules, you used to call the extendModule function on the Tabulator prototype:

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

You should now call this function directly on the Tabulator class

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

Default Table Options

When setting default table options, these used to be defined on the defaultOptions property of the Tabulator prototype:

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

The defaultOptions object should now be accessed directly on the Tabulator class

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

Renderers

With renderers now being separated from the core codebase the options for enabling/disabling the virtual DOM have now been renamed

Vertical Renderers

Disabling the Vertical Virtual DOM

To disable the vertical virtual DOM you used to set the virtualDom option false:

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

You should now set the renderVertical option to basic

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

Render Buffer

To set the size of the vertical render buffer, you used to set the value on the virtualDomBuffer option:

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

You should now set it on the renderVerticalBuffer

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

Horizontal Renderers

Enabling the Horizontal Virtual DOM

To enable the horizontal virtual DOM you used to set the virtualDomHoz option true:

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

You should now set the renderHorizontal option to virtual

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

Finding Tables

When finding tables, the findTable function was called on the Tabulator prototype:

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

The findTable function should now be called directly on the Tabulator class

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

Themes

The structure of of the /dist/css/ folder has been updated to make themes easier to find

Bootstrap 3

You used to import the bootstrap 3 theme from inside the /bootstrap folder.

<link href="/dist/css/bootstrap/tabulator_bootstrap.min.css" rel="stylesheet">

You can now import it directly from the /dist/css folder. You will also note that the file is now called bootstrap3.css to make it clear which version of bootstrap the style is from

<link href="/dist/css/tabulator_bootstrap3.min.css" rel="stylesheet">

Bootstrap 4

You used to import the bootstrap 4 theme from inside the /bootstrap folder.

<link href="/dist/css/bootstrap/tabulator_bootstrap4.min.css" rel="stylesheet">

You can now import it directly from the /dist/css folder.

<link href="/dist/css/tabulator_bootstrap4.min.css" rel="stylesheet">

Semantic UI

You used to import the Semantic UI theme from inside the /semantic-ui folder.

<link href="/dist/css/semantic-ui/tabulator_semantic-ui.min.css" rel="stylesheet">

You can now import it directly from the /dist/css folder. You will also note that the file is now called tabulator_semanticui.css to match the naming convention of the other themes

<link href="/dist/css/tabulator_semanticui.min.css" rel="stylesheet">

Bulma

You used to import the bulma theme from inside the /bulma folder.

<link href="/dist/css/bulma/tabulator_bulma.min.css" rel="stylesheet">

You can now import it directly from the /dist/css folder.

<link href="/dist/css/tabulator_bulma.min.css" rel="stylesheet">

Materialize

You used to import the materialize theme from inside the /materialize folder.

<link href="/dist/css/materialize/tabulator_materialize.min.css" rel="stylesheet">

You can now import it directly from the /dist/css folder.

<link href="/dist/css/tabulator_materialize.min.css" rel="stylesheet">

Column Defaults

With the inclusion of the new columnDefaults option, a number of table options that used to configure all rows have become redundant. This section lists the old table options and their new default options

Horizontal Align Cells

You used to globally set the horizontal alignment of cells using the cellHozAlign option

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

You should now set it using the hozAlign propety in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        hozAlign:"left",
    }
});

Vertical Align Cells

You used to globally set the vertical alignment of cells using the cellVertAlign option

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

You should now set it using the vertAlign propety in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        vertAlign:"top",
    }
});

Horizontal Align Column Headers

You used to globally set the horizontal alignment of column headers using the headerHozAlign option

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

You should now set it using the headerHozAlign propety in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        headerHozAlign:"left",
    }
});

Column Min Width

You used to globally set the minimum width of columns using the columnMinWidth option

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

You should now set it using the minWidth property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        minWidth:20,
    }
});

Column Max Width

You used to globally set the maximum width of columns using the columnMaxWidth option

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

You should now set it using the maxWidth property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        maxWidth:20,
    }
});

Resizable Columns

You used to globally set resiable columns using the resizableColumns option

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

You should now set it using the resizable property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        resizable:"header",
    }
});

Cell Tooltips

You used to globally set cell tooltips using the tooltips option

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

You should now set it using the tooltip property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        tooltip:true,
    }
});

Header Tooltips

You used to globally set header tooltips using the tooltipsHeader option

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

You should now set it using the headerTooltip property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        headerTooltip:true,
    }
});

Header Filter Placeholder

You used to globally set header filter placeholder text using the headerFilterPlaceholder option

var table = new Tabulator("#example-table", {
    headerFilterPlaceholder:"Filter Values",
});

You should now set it using the headerFilterPlaceholder property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        headerFilterPlaceholder:"Filter Values",
    }
});

Header Sort

You used to globally set header sorting using the headerSort option

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

You should now set it using the headerSort property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        headerSort:true,
    }
});

Header Sort Tristate

You used to globally set tristate header sorting using the headerSortTristate option

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

You should now set it using the headerSortTristate property in the columnDefaults option

var table = new Tabulator("#example-table", {
    columnDefaults:{
        headerSortTristate:true,
    }
});

Callbacks

The whole table event callbacks that you used to set on the table in the constructor object have now been replaced with an event subscription model.

So where you used to bind the callback in the constructor:

var table = new Tabulator("#example-table", {
    dataLoaded: function(){
        //do something
    }
});

You now subscribe to the event after you have instantiated the table:

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

table.on("dataLoaded", function(){
    //do something
})

The callbacks that have changed to events are:

Ajax and Data Loading

Events

With the creation of the new data loading system, all the old ajax events have been removed and the data loading events have changed purpose to show any data being loaded into the table.

You will now need to map your ajax events to the new data loading events

Ajax Loading

Where you used to subscribe to the ajaxLoading event

table.on("ajaxLoading", function(){
    //do something
})

You should now subscribe to the dataLoading event

table.on("dataLoading", function(){
    //do something
})

Ajax Loaded

Where you used to subscribe to the ajaxLoaded event

table.on("ajaxLoaded", function(){
    //do something
})

You should now subscribe to the dataLoading event

table.on("dataLoading", function(){
    //do something
})

Ajax Error

Where you used to subscribe to the dataLoadError event

table.on("dataLoadError", function(){
    //do something
})

You should now subscribe to the dataLoading event

table.on("dataLoading", function(){
    //do something
})

Data Loaders

With the creation of the new data loading system, all the old ajax loaders have been changed to data loaders.

You will now need to map your ajax loader options to the new data loader options

Data Loader

Where you used to disable the ajax loader using the ajaxLoader option

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

You should now use the the dataLoader option

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

Data Loading Message

Where you used to set the ajax loader message using the ajaxLoaderLoading option

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

You should now use the the dataLoaderLoading option

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

Data Loading Error Message

Where you used to set the ajax loader error message using the ajaxLoaderError option

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

You should now use the the dataLoaderError option

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

Localization

Ajax Request Localization

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

Where you used to set the ajax loader messaging in the ajax property of a lang definition object

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

You should now set it on the data property

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

Request & Response Params Mapping

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

Map Request Params

Where you used to define the param map with the paginationDataSent option.

var table = new Tabulator("#example-table", {
  paginationDataSent:{
    page:"current_page",
    size:"page_size",
  },
});

You should now use the dataSendParams option

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

Map Response Params

Where you used to define the param map with the paginationDataReceived option.

var table = new Tabulator("#example-table", {
  paginationDataReceived:{
    last_page:"last",
    size:"page_data",
  },
});

You should now use the dataReceiveParams option

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

Progressive Load Type

Where you used to use the ajaxProgressiveLoad option to set the type of load to be used

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

You should now use the progressiveLoad option

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

Progressive Load Delay

Where you used to use the ajaxProgressiveLoadDelay option to set the progressive load delay

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

You should now use the progressiveLoadDelay option

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

Progressive Load Scroll Margin

Where you used to use the ajaxProgressiveLoadScrollMargin option to set the progressive load scroll margin

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

You should now use the progressiveLoadScrollMargin option

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

Sorting

Remote Sorting

You used to enable remote sorting using the ajaxSorting option

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

You should now use the sortMode option

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

Date and Time Sorting

In previous version of the library Tabulator used the moment.js library for date and time sorting. When sorting a column with a date, time or datetime sorter, you needed to include the moment library in your code

<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.js"></script>

In this release this has now been replaced with the much more compact luxon.js library. Which can be included from the following CDN:

<script src="https://cdn.jsdelivr.net/npm/luxon/build/global/luxon.min.js"></script>

Formatting

DateTime Formatting

In previous version of the library Tabulator used the moment.js library for date and time formatting. When formatting a cell with a datetime or datetimediff formatter, you needed to include the moment library in your code

<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.js"></script>

In this release this has now been replaced with the much more compact luxon.js library. Which can be included from the following CDN:

<script src="https://cdn.jsdelivr.net/npm/luxon/build/global/luxon.min.js"></script>

Filter

You used to enable remote fitering using the ajaxFiltering option

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

You should now use the filterMode option

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

Pagination

You used to enable remote fitering using the pagination option

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

You should now use the pagination option to enable pagination and the paginationMode option to set it to remote mode

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

Downloaders

PDF Downloader

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

You used to include the old versions of the jspdf libraries.

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/1.3.5/jspdf.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf-autotable/3.0.5/jspdf.plugin.autotable.js"></script>

You should now include the new libraries instead

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.4.0/jspdf.umd.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf-autotable/3.5.20/jspdf.plugin.autotable.min.js"></script>

Cell Navigation

Cell navigation functions have been moved from inside the nav function to directly on the cell component.

Where you used to access cell navigation functions on the cell component by calling the nav function, and then a direction function like up:

cell.nav().up()

You now navigate using function names starting with navigate and then the direction, such as Up:

cell.navigateUp()

This is the case for all navigation functions, up, down, left, right, prev and next.

Debug Options

The invalidOptionWarning option has been renamed to debugInvalidOptions to fit in with the new range of debug tools.

So where you used to disable invalid option warnings with the invalidOptionWarning option

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

You should now use the debugInvalidOptions option

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