Old Documentation

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

Release Notes

Performance Improvements
Editing
Formatting
Placeholders
Persistence
Column Calculations
Downloads
Events
Component Objects
Internal Events
Bug Fixes

Performance Improvements

Vertical Virtual Renderer

The vertical virtual renderer has been updated to take advantage of document fragments to build out table rows in blocks rather than one at a time.

This has had the effect of making the table render and redraw when using dynamic height rows, and 2 times faster when using fixed height rows.

Editing

Editor Updates

Date Editor

The new verticalNavigation option for the date editor allows you to determine how the up and down arrow keys affect the editor:

{title:"Example", field:"example", editor:"date", editorParams:{
    verticalNavigation:"table", //navigate cursor around table without changing the value
}}

The verticalNavigation param can take one of two values:

editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor

DateTime Editor

The new verticalNavigation option for the datetime editor allows you to determine how the up and down arrow keys affect the editor:

{title:"Example", field:"example", editor:"date", editorParams:{
    verticalNavigation:"table", //navigate cursor around table without changing the value
}}

The verticalNavigation param can take one of two values:

editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor

Time Editor

The new verticalNavigation option for the time editor allows you to determine how the up and down arrow keys affect the editor:

{title:"Example", field:"example", editor:"date", editorParams:{
    verticalNavigation:"table", //navigate cursor around table without changing the value
}}

The verticalNavigation param can take one of two values:

editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor

Formatting

Formatter Updates

Money Formatter

The money formatter has been updated to add the negativeSign formatter param. This allows you to specify the symbol that should be shown in front of negative numbers (default "-")

{title:"Example", field:"example", formatter:"money", formatterParams:{
    negativeSign:"!", //show the ! symbol in front of negative numbers instead of the - symbol
}}

Passing a value of true to this option will cause negative numbers to be wrapped in parentheses (123.45), which is the standard style for negative numbers in accounting.

{title:"Example", field:"example", formatter:"money", formatterParams:{
    negativeSign:true, //show negative numbers wrapped in parentheses
}}

Placeholders

Empty Table Placeholder Callback

The placeholder option can now take a callback function that will be run when the placeholder has shown, this lets you customize your placeholder based on external factors.

var table = new Tabulator("#example-table", {
    placeholder:function(){
        return this.getHeaderFilters().length ? "No Matching Data" : "No Data"; //set placeholder based on if there are currently any header filters
    }
});

Header Filter Empty Table Placeholder

You can use the placeholderHeaderFilter option to display a different message to your users when the table has no data available as a result of header filters being active.

var table = new Tabulator("#example-table", {
    placeholderHeaderFilter:"No Matching Data", //display message to user on empty table due to header filters
});

Persistence

Header Filter Persistence

You can ensure the data header filters are stored for the next page load by setting the headerFilter property of the persistence option to true

This will persist all active column header filters on the table

var table = new Tabulator("#example-table", {
    persistence:{
        headerFilter: true, //persist header filters
    }
});

Built In Filters
Only built-in filters can be stored (including module), custom filter functions cannot be persistently stored.

Column Calculations

Calculation Functions

Unique

The new unique function counts the number of unique non-empty values in a column (cells that do not have a value of null, undefined or "").

{title:"Example", field:"example", topCalc:"unique"}

Downloads

XLSX Downloader

SheetJS File Write Options

You can now configure the type of file output from the SheetJS library using the native SheetJS file writing options with the optional writeOptions option.

table.download("xlsx", "data.wk3", {
    writeOptions:{
        bookType:"wk3", //save file in lotus notes format
    }
});

Events

Updated Events

Row Selection Changed

Two new arguments have been added to the rowSelectionChanged event to make it easier to track the changes in selection as a result of the event.

In addition to the first and second arguments that show the currently selected rows, the third argument now contains an array of Row Components for the any rows selected in the last action, and the fourth argument now contains an array of Row Components for any rows deselected in the last action.

table.on("rowSelectionChanged", function(data, rows, selected, deselected){
    //rows - array of row components for the currently selected rows in order of selection
    //data - array of data objects for the currently selected rows in order of selection
    //selected - array of row components that were selected in the last action
    //deselected - array of row components that were deselected in the last action
});

Component Objects

Cell Component

Get Type

The new getType function on the CellComponent can be used to determine if the cell is being used as a cell or a header element. This can be useful for editors or formatters if you want them to behave differently when used ina header vs a cell.

var type = cell.getType();

This function will return a string:

cell - This cell is being used as a cell
header - This cell is being used as a header

Trigger Accessor on Get Data

The getData function has been updated to accept an optional argument, that is the transform type for column accessors. You can use this to trigger accessors on the row data when calling the function

var data = cell.getData("data");

Row Component

Scroll To Row

The scrollTo function has been updated with two optional arguments to change the behaviour of the scroll

The first optional argument is used to set the position of the row, it should be a string with a value of either top, center, bottom or nearest, if omitted it will be set to the value of the scrollToRowPosition option which has a default value of top.

The second argument is optional, and is a boolean used to set if the table should scroll if the row is already visible, true to scroll, false to not, if omitted it will be set to the value of the scrollToRowIfVisible option, which defaults to true

row.scrollTo("bottom", true); //scroll row to bottom if it is currently visible

Column Component

Scroll To Column

The scrollTo function has been updated with two optional arguments to change the behaviour of the scroll

You can pass optional arguments to the function to change the behaviour of the scroll. The first argument is used to set the position of the column, it should be a string with a value of either left, middle or right, if omitted it will be set to the value of the scrollToColumnPosition option which has a default value of left.

The second argument is optional, and is a boolean used to set if the table should scroll if the column is already visible, true to scroll, false to not, if omitted it will be set to the value of the scrollToColumnIfVisible option, which defaults to true

column.scrollTo("right", true); //scroll column to right if it is currently visible

Group Component

Scroll To Group Header

The scrollTo function will scroll the table to the group header if it passes the current filters.

group.scrollTo();

You can pass optional arguments to the function to change the behaviour of the scroll. The first optional argument is used to set the position of the group header, it should be a string with a value of either top, center, bottom or nearest, if omitted it will be set to the value of the scrollToRowPosition option which has a default value of top.

The second argument is optional, and is a boolean used to set if the table should scroll if the group header is already visible, true to scroll, false to not, if omitted it will be set to the value of the scrollToRowIfVisible option, which defaults to true

group.scrollTo("top", true); //scroll group to top if it is currently visible

The scrollTo method returns a promise, this can be used to run any other commands that have to be run after the group has been scrolled to. By running them in the promise you ensure they are only run after the group has been scrolled to.

group.scrollTo()
.then(function(){
    //run code after group has been scrolled to
})
.catch(function(error){
    //handle error scrolling to group
});

Internal Events

New internal events have been added in this release.

Placeholder

The placeholder event is a chain type event, that is triggered when the placeholder is about to be displayed.

It passes the current placeholder content as its first argument. and should return the content for the placeholder if it wants to replace it,either a string or HTML.

this.subscribe("placeholder", function(placeholder) => {
    //placeholder - current placeholder value

    return "New Placeholder" //set new placeholder;
});