Callbacks

Overview

Tabulator features a range of callbacks to allow you to handle user interaction and system events.

These callbacks can all be set in the options object when you create your Tabulator.

Table Callbacks

Table Building

When a the tabulator constructor is called, the tableBuilding callback will triggered:

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

Table Built

When a the tabulator constructor is called and the table has finished being rendered, the tableBuilt callback will triggered:

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

Column Callbacks

Column Header Click

The headerClick callback is triggered when a user left clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

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

Column Header Double Click

The headerDblClick callback is triggered when a user double clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

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

Column Header Right Click

The headerContext callback is triggered when a user right clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

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

Column Header Tap

The headerTap callback is triggered when a user taps on the column header on a touch display, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerTap:function(e, column){
    //e - the tap event object
    //column - column component
    },
}

Column Header Double Tap

The headerDblTap callback is triggered when a user taps on the column header on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerDblTap:function(e, column){
    //e - the tap event object
    //column - column component
    },
}

Column Header Tap Hold

The headerTapHold callback is triggered when a user taps on the column header on a touch display and holds their finger down for over 1 second, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerTapHold:function(e, column){
    //e - the tap event object
    //column - column component
    },
}

Column Moved

The columnMoved callback will be triggered when a column has been successfuly moved.

var table = new Tabulator("#example-table", {
    columnMoved:function(column, columns){
    //column - column component of the moved column
    //columns- array of columns in new order
    },
});

Column Resized

The columnResized callback will be triggered when a column has been resized by the user.

var table = new Tabulator("#example-table", {
    columnResized:function(column){
    //column - column component of the resized column
    },
});

Column Visibility Changed

The columnVisibilityChanged callback is triggered whenever a column changes between hidden and visible states.

var table = new Tabulator("#example-table", {
    columnVisibilityChanged:function(column, visible){
    //column - column component
    //visible - is column visible (true = visible, false = hidden)
    },
});

Column Title Changed

The columnTitleChanged callback is triggered whenever a user edits a column title when the editableTitle parameter has been enabled in the column definition array.

var table = new Tabulator("#example-table", {
    columnTitleChanged:function(column){
    //column - column component
    },
});

Row Callbacks

Row Click

The rowClick callback is triggered when a user clicks on a row.

var table = new Tabulator("#example-table", {
    rowClick:function(e, row){
    //e - the click event object
    //row - row component
    },
});

Row Double Click

The rowDblClick callback is triggered when a user double clicks on a row.

var table = new Tabulator("#example-table", {
    rowDblClick:function(e, row){
    //e - the click event object
    //row - row component
    },
});

Row Context Menu

The rowContext callback is triggered when a user right clicks on a row.

If you want to prevent the browsers context menu being triggered in this event you will need to include the preventDefault() function in your callback.

var table = new Tabulator("#example-table", {
    rowContext:function(e, row){
    //e - the click event object
    //row - row component

    e.preventDefault(); // prevent the browsers default context menu form appearing.
    },
});

Row Tap

The rowTap callback is triggered when a user taps on a row on a touch display.

var table = new Tabulator("#example-table", {
    rowTap:function(e, row){
    //e - the tap event object
    //row - row component
    },
});

Row Double Tap

The rowDblTap callback is triggered when a user taps on a row on a touch display twice in under 300ms.

var table = new Tabulator("#example-table", {
    rowDblTap:function(e, row){
    //e - the tap event object
    //row - row component
    },
});

Row Tap Hold

The rowTapHold callback is triggered when a user taps on a row on a touch display and holds their finger down for over 1 second.

var table = new Tabulator("#example-table", {
    rowTapHold:function(e, row){
    //e - the tap event object
    //row - row component
    },
});

Row Added

The rowAdded callback is triggered when a row is added to the table by the addRow and updateOrAddRow functions.

var table = new Tabulator("#example-table", {
    rowAdded:function(row){
    //row - row component
    },
});

Row Updated

The rowUpdated callback is triggered when a row is updated by the updateRow, updateOrAddRow, updateData or updateOrAddData, functions.

var table = new Tabulator("#example-table", {
    rowUpdated:function(row){
    //row - row component
    },
});

Row Deleted

The rowDeleted callback is triggered when a row is deleted from the table by the deleteRow function.

var table = new Tabulator("#example-table", {
    rowDeleted:function(row){
    //row - row component
    },
});

Row Moved

The rowMoved callback will be triggered when a row has been successfuly moved.

var table = new Tabulator("#example-table", {
    rowMoved:function(row){
    //row - row component
    },
});

Row Resized

The rowResized callback will be triggered when a row has been resized by the user.

var table = new Tabulator("#example-table", {
    rowResized:function(row){
    //row - row component of the resized row
    },
});

Cell Callbacks

Cell Click

The cellClick callback is triggered when a user left clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

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

The cellClick callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellClick:function(e, cell){
    //e - the click event object
    //cell - cell component
    },
});

Cell Double Click

The cellDblClick callback is triggered when a user double clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

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

The cellDblClick callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellDblClick:function(e, cell){
    //e - the click event object
    //cell - cell component
    },
});

Cell Right Click

The cellContext callback is triggered when a user right clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

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

The cellContext callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellContext:function(e, cell){
    //e - the click event object
    //cell - cell component
    },
});

Cell Tap

The cellTap callback is triggered when a user taps on a cell in this column on a touch display, it can be set on a per column basis using the option in the columns definition object.

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

The cellTap callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellTap:function(e, cell){
    //e - the tap event object
    //cell - cell component
    },
});

Cell Double Tap

The cellDblTap callback is triggered when a user taps on a cell in this column on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

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

The cellDblTap callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellDblTap:function(e, cell){
    //e - the tap event object
    //cell - cell component
    },
});

Cell Tap Hold

The cellTapHold callback is triggered when a user taps on a cell in this column on a touch display and holds their finger down for over 1 second, it can be set on a per column basis using the option in the columns definition object.

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

The cellTapHold callback can also be set globally.

var table = new Tabulator("#example-table", {
    cellTapHold:function(e, cell){
    //e - the tap event object
    //cell - cell component
    },
});

Cell Editing

The cellEditing callback is triggered when a user starts editing a cell.

var table = new Tabulator("#example-table", {
    cellEditing:function(cell){
    //cell - cell component
    },
});

The cellEditing callback can also be set in the column definition object of a column

{title:"Name", field:"name", cellEditing:function(cell){
    //cell - cell component
    },
}

Cell Edit Cancelled

The cellEditCancelled callback is triggered when a user aborts a cell edit and the cancel function is called.

var table = new Tabulator("#example-table", {
    cellEditCancelled:function(cell){
    //cell - cell component
    },
});

The cellEditCancelled callback can also be set in the column definition object of a column

{title:"Name", field:"name", cellEditCancelled:function(cell){
    //cell - cell component
    },
}

Cell Edited

The cellEdited callback is triggered when data in an editable cell is changed.

var table = new Tabulator("#example-table", {
    cellEdited:function(cell){
    //cell - cell component
    },
});

The cellEdited callback can also be set in the column definition object of a column

{title:"Name", field:"name", cellEdited:function(cell){
    //cell - cell component
    },
}

Data Callbacks

Data Loading

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

var table = new Tabulator("#example-table", {
    dataLoading:function(data){
    //data - the data loading into the table
    },
});

Data Loaded

The dataLoaded callback is triggered when a new set of data is loaded into the table.

var table = new Tabulator("#example-table", {
    dataLoaded:function(data){
    //data - all data loaded into the table
    },
});

Data Edited

The dataEdited callback is triggered whenever the table data is changed by the user. Triggers for this include editing any cell in the table, adding a row and deleting a row.

var table = new Tabulator("#example-table", {
    dataEdited:function(data){
    //data - the updated table data
    },
});

HTML Importing

The htmlImporting callback is triggered when Tabulator starts importing data from an HTML table.

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

HTML Imported

The htmlImported callback is triggered when Tabulator finishes importing data from an HTML table.

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

Ajax Callbacks

Ajax Request

The ajaxRequesting callback is triggered when ever an ajax request is made.

var table = new Tabulator("#example-table", {
    ajaxRequesting:function(url, params){
    //url - the URL of the request
    //params - the parameters passed with the request
    },
});

Returning a value of false from this callback will abort the ajax request

Ajax Response

The ajaxResponse callback is triggered when a successful ajax request has been made. This callback can also be used to modify the received data before it is parsed by the table. If you use this callback it must return the data to be parsed by Tabulator, otherwise no data will be rendered.

var table = new Tabulator("#example-table", {
    ajaxResponse:function(url, params, response){
    //url - the URL of the request
    //params - the parameters passed with the request
    //response - the JSON object returned in the body of the response.

    return response; //return the response data to tabulator
    },
});

Ajax Error

The ajaxError callback is triggered there is an error response to an ajax request.

var table = new Tabulator("#example-table", {
    ajaxError:function(xhr, textStatus, errorThrown){
    //xhr - the XHR object
    //textStatus - error type
    //errorThrown - text portion of the HTTP status
    },
});

Filter Callbacks

Data Filtering

The dataFiltering callback is triggered whenever a filter event occurs, before the filter happens.

var table = new Tabulator("#example-table", {
    dataFiltering:function(filters){
    //filters - array of filters currently applied

    },
});

Data Filtered

The dataFiltered callback is triggered after the table dataset is filtered.

var table = new Tabulator("#example-table", {
    dataFiltered:function(filters, rows){
    //filters - array of filters currently applied
    //rows - array of row components that pass the filters
    },
});

Sorting Callbacks

Data Sorting

The dataSorting callback is triggered whenever a sort event occurs, before sorting happens.

var table = new Tabulator("#example-table", {
    dataSorting:function(sorters){
    //sorters - an array of the sorters currently applied
    },
});

Data Sorted

The dataSorted callback is triggered after the table dataset is sorted.

var table = new Tabulator("#example-table", {
    dataSorted:function(sorters, rows){
    //sorters - array of the sorters currently applied
    //rows - array of row components in their new order
    },
});

Layout Callbacks

Render Started

The renderStarted callback is triggered whenever all the rows in the table are about to be rendered. This can include:

  • Data is loaded into the table when setData is called
  • A page is loaded through any form of pagination
  • Rows are added to the table during progressive rendering
  • Columns are changed by setColumns
  • The data is filtered
  • The data is sorted
  • The redraw function is called

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

Render Complete

The renderComplete callback is triggered after the table has been rendered

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

Pagination Callbacks

Page Loaded

Whenever a page has been loaded, the pageLoaded callback is called, passing the current page number as an argument.

var table = new Tabulator("#example-table", {
    pageLoaded:function(pageno){
    //pageno - the number of the loaded page
    },
});

Localization

Table Localized

When a localization event has occurred , the localized callback will triggered, passing the current locale code and language object:

var table = new Tabulator("#example-table", {
        localized:function(locale, lang){
        //locale - a string representing the current locale
        //lang - the language object for the current locale
        },
});

Group Callbacks

Data Grouping

The dataGrouping callback is triggered whenever a data grouping event occurs, before grouping happens.

var table = new Tabulator("#example-table", {
    dataGrouping:function(){

    },
});

Data Grouped

The dataGrouped callback is triggered whenever a data grouping event occurs, after grouping happens.

var table = new Tabulator("#example-table", {
    dataGrouped:function(groups){
    //groups - array of top level group components
    },
});

Group Visibility Changed

The groupVisibilityChanged callback is triggered whenever a group changes between hidden and visible states.

var table = new Tabulator("#example-table", {
    groupVisibilityChanged:function(group, visible){
    //group - group component
    //visible - is group visible (true = visible, false = hidden)
    },
});

Group Click

The groupClick callback is triggered when a user clicks on a group header.

var table = new Tabulator("#example-table", {
    groupClick:function(e, group){
    //e - the click event object
    //group - group component
    },
});

Group Double Click

The groupDblClick callback is triggered when a user double clicks on a group header.

var table = new Tabulator("#example-table", {
    groupDblClick:function(e, group){
    //e - the click event object
    //group - group component
    },
});

Group Context Menu

The groupContext callback is triggered when a user right clicks on a group header.

If you want to prevent the browsers context menu being triggered in this event you will need to include the preventDefault() function in your callback.

var table = new Tabulator("#example-table", {
    groupContext:function(e, group){
    //e - the click event object
    //group - group component

    e.preventDefault(); // prevent the browsers default context menu form appearing.
    },
});

Group Tap

The groupTap callback is triggered when a user taps on a group header on a touch display.

var table = new Tabulator("#example-table", {
    groupTap:function(e, group){
    //e - the tap event object
    //group - group component
    },
});

Group Double Tap

The groupDblTap callback is triggered when a user taps on a group header on a touch display twice in under 300ms.

var table = new Tabulator("#example-table", {
    groupDblTap:function(e, group){
    //e - the tap event object
    //group - group component
    },
});

Group Tap Hold

The groupTapHold callback is triggered when a user taps on a group header on a touch display and holds their finger down for over 1 second.

var table = new Tabulator("#example-table", {
    groupTapHold:function(e, group){
    //e - the tap event object
    //group - group component
    },
});

Selection Callbacks

Row Selected

The rowSelected event is triggered when a row is selected, either by the user or programatically.

var table = new Tabulator("#example-table", {
    rowSelected:function(row){
    //row - row component for the selected row
    },
});

Row Deselected

The rowDeselected event is triggered when a row is deselected, either by the user or programatically.

var table = new Tabulator("#example-table", {
    rowDeselected:function(row){
    //row - row component for the deselected row
    },
});

Row Selection Changed

Whenever the number of selected rows changes, through selection or deselection, the rowSelectionChanged event is triggered. This passes an array of the data objects for each row in the order they were selected as the first argument, and an array of row components for each of the rows in order of selection as the second argument.

var table = new Tabulator("#example-table", {
    rowSelectionChanged:function(data, rows){
    //rows - array of row components for the selected rows in order of selection
    //data - array of data objects for the selected rows in order of selection
    },
});

Row Movement Callbacks

Sending Start

The movableRowsSendingStart callback is triggered on the sending table when a row is picked up from a sending table.

var table = new Tabulator("#example-table", {
    movableRowsSendingStart:function(toTables){
    //toTables - array of receiving table elements
    },
});

Row Sent

The movableRowsSent callback is triggered on the sending table when a row has been successfuly received by a receiving table.

var table = new Tabulator("#example-table", {
    movableRowsSent:function(fromRow, toRow, toTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //toTable - the Tabulator object for the receiving table
    },
});

Row Sent Failed

The movableRowsSentFailed callback is triggered on the sending table when a row has failed to be received by the receiving table.

var table = new Tabulator("#example-table", {
    movableRowsSentFailed:function(fromRow, toRow, toTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //toTable - the Tabulator object for the receiving table
    },
});

Sending Stop

The movableRowsSendingStop callback is triggered on the sending table after a row has been dropped and any senders and receivers have been handled.

var table = new Tabulator("#example-table", {
    movableRowsSendingStop:function(toTables){
    //toTables - array of receiving table Tabulator objects
    },
});

Receiving Start

The movableRowsReceivingStart callback is triggered on a receiving table when a connection is established with a sending table.

var table = new Tabulator("#example-table", {
    movableRowsReceivingStart:function(fromRow, fromTable){
    //fromRow - the row component from the sending table
    //fromTable - the Tabulator object for the sending table
    },
});

Row Received

The movableRowsReceived callback is triggered on a receiving table when a row has been successfuly received.

var table = new Tabulator("#example-table", {
    movableRowsReceived:function(fromRow, toRow, fromTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //fromTable - the Tabulator object for the sending table
    },
});

Row Received Failed

The movableRowsReceivedFailed callback is triggered on a receiving table when a row receiver has returned false.

var table = new Tabulator("#example-table", {
    movableRowsReceivedFailed:function(fromRow, toRow, fromTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //fromTable - the Tabulator object for the sending table
    },
});

Receiving Stop

The movableRowsReceivingStop callback is triggered on a receiving table after a row has been dropped and any senders and receivers have been handled.

var table = new Tabulator("#example-table", {
    movableRowsReceivingStop:function(fromTable){
    //fromTable - the Tabulator object for the sending table
    },
});

Validation Callbacks

Validation Failed

The validationFailed event is triggered when the value entered into a cell during an edit fails to pass validation.

var table = new Tabulator("#example-table", {
    validationFailed:function(cell, value, validators){
    //cell - cell component for the edited cell
    //value - the value that failed validation
    //validatiors - an array of validator objects that failed
    },
});

History Callbacks

History callbacks are triggered when undo and redo actions are triggered.

The history callbacks are passed three arguments, the first is a string representing the action being undone/redone, the second is the Row or Cell component relating to the action, the third is the data object related to the action. The table below outlines the possible actions and their assoicated data objects:

Action Description Component Data
cellEdit Cell value edited Cell Component
{
                oldValue:"", //the original value of the cell
                newValue:"", //the nev value of the cell
            }
rowAdd Row added to table Row Component
{
                data:{}, //the data contained in the row
                pos:0, //the position the row was inserted into the table
                index:0, //the index column value for the row
            }
rowDelete Row deleted from table Row Component
{
                data:{}, //the data contained in the row
                pos:0, //the position the row was removed from the table
                index:0, //the index column value for the row
            }
rowMoved Row moved to new position in table Row Component
{
                pos:0, //the position the row was moved from
                to:null, //row component for the row this row was moved next to
                after:false, //row was moved before or after the "to" row
            }

Undo Occurred

The historyUndo event is triggered when the undo action is triggered.

var table = new Tabulator("#example-table", {
    historyUndo:function(action, component, data){
    //action - the action that has been undone
    //component - the Component object afected by the action (colud be a row or cell component)
    //data - the data being changed
    },
});

Redo Occurred

The historyRedo event is triggered when the redo action is triggered.

var table = new Tabulator("#example-table", {
    historyRedo:function(action, component, data){
    //action - the action that has been redone
    //component - the Component object afected by the action (colud be a row or cell component)
    //data - the data being changed
    },
});

Clipboard Callbacks

Data Copied to Clipboard

The clipboardCopied event is triggered whenever data is copied to the clipboard.

var table = new Tabulator("#example-table", {
    clipboardCopied:function(clipboard){
    //clipboard - the string that has been copied into the clipboard
    },
});

Data Pasted into Table

The clipboardPasted event is triggered whenever data is successfuly pasted into the table.

var table = new Tabulator("#example-table", {
    clipboardPasted:function(clipboard, rowData, rows){
    //clipboard - the clipboard string
    //rowData - the row data from the paste parser
    //rows - the row components from the paste action (this will be empty if the "replace" action is used)
    },
});

Data Paste into Table Failed

The clipboardPasteError event is triggered whenever an atempt to paste data into the table has failed because it was rejected by the paste parser.

var table = new Tabulator("#example-table", {
    clipboardPasteError:function(clipboard){
    //clipboard - the clipboard string that was rejected by the paste parser
    },
});

Download Callbacks

Mutate Data Before Download

If you want to make any changes to the table data before it is parsed into the download file you can pass a mutator function to the downloadDataFormatter callback.

In the example below we map the numerical age column into a string of "adult" or "child" based on the age value

var table = new Tabulator("#example-table", {
    downloadDataFormatter:function(data){
    //data - active table data array

    data.forEach(function(row){
    row.age = row.age >= 18 ? "adult" : "child";
});

return data;
    },
});

Intercept & Manipulate Download Blob

The downloadReady callback allows you to intercept the download file data before the users is prompted to save the file.

In order for the download to proceed the downloadReady callback is expected to return a blob of file to be downloaded.

If you would prefer to abort the download you can return false from this callback. This could be useful for example if you want to send the created file to a server via ajax rather than allowing the user to download the file.

var table = new Tabulator("#example-table", {
    downloadReady:function(fileContents, blob){
    //fileContents - the unencoded contents of the file
    //blob - the blob object for the download

    //custom action to send blob to server could be included here

    return blob; //must return a blob to proceed with the download, return false to abort download
    },
});

Download Complete

The downloadComplete callback is triggered when the user has been prompted to download the file.

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

Data Tree Callbacks

Row Expanded

The dataTreeRowExpanded callback is triggered when a row with child rows is expanded to reveal the children.

var table = new Tabulator("#example-table", {
    dataTreeRowExpanded:function(row, level){
        //row - the row component for the expanded row
        //level - the depth of the row in the tree
    },
});

Row Collapsed

The dataTreeRowCollapsed callback is triggered when a row with child rows is collapsed to hide its children.

var table = new Tabulator("#example-table", {
    dataTreeRowCollapsed:function(row, level){
        //row - the row component for the collapsed row
        //level - the depth of the row in the tree
    },
});