Version 6.3 Released!

Click to checkout the new features
Old Documentation
You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Internal Event Bus

Overview

The internal event bus provides a way for modules and Tabulator to talk to one another and helps keep Tabulators internal logic isolated from module logic.

This section will outline all of the built in internal events in Tabulator, along with the arguments passed in those events and information about when they are dispatched.

Event Types

There are several types of event that can be dispatched. We will briefly describe each type of event here, but for a full description along with example usage cases and sample code for subscribing to each event type, please read the Building Modules Documentation

Dispatch

Dispatched events are simple send and forget notifications which do not return any values. Then can be triggered using the dispatch function.

The first argument is the name of the event, any other arguments after the event are then passed to the subscribers

this.dispatch("example-event", arg1, arg2, arg3);

Example
An example usage case of this is when a row is deleted, the row dispatches a row-deleted event that lets modules know that a row has been deleted so they can carry out any needed housekeeping functions.

Chain

Chain events are used when you want to receive a response to an event, they can be used to request feedback from other modules to the result of an event.

Because any number of modules can be subscribed to an event, this isnt a simple call and response. Each subscriber is called in turn an passed the results of the last to subscriber and should return its own response combined with with that of the previous subscribers. When the last subscriber returns the result is returned to the dispatching module.

The first argument is the name of the event, The second argument is an array of arguments to be passed to the subscriber function. The third argument is the initial value to be passed into the previous value argument of the first subscriber. The fourth argument is the fallback value that will be returned if their are no subscribers to the event, this can either be a value or a callback function that is called in the event of no subscribers, that should return the fallback value,

var result = this.chain("example-event", [arg1, arg2, arg3], {}, {noparams:true})

Example
An example usage case of this when the data loader dispatches the data-params event to retrieve a list of ajax parameters for a request. the filter, sort and pagination modules then add their parameters to the params object and pass it back to the data loader.

Confirm

The confirm event should be used to check if modules are happy for something to proceed, if any module returns to to the event it will return true, otherwise it will return false.

The first argument is the name of the event, the second argument is an array of arguments to be passed to the subscriber function

var success = this.confirm("example-event", [arg1, arg2, arg3]);

Example
The data loader dispatches a data-load confirm when it starts to load data, to allow modules to take control of the loading process and for example make an ajax request instead of the data being loaded from an array.

Inspecting Events

Understanding when events occur can be tricky to know from reading a simple list. To help you out when building your modules, Tabualtor provides a debug tool that logs internal events out to the console so you can gain practical understanding of when they are fired.

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 huge number of internal events, running with this enabled will slow the table down considerably, and you should ensure you are only running this option with a table containing a small amount of data.

Table Events

Lifecycle Events

Key Type Arguments Response Notes
table-building dispatch Table is being built
table-built dispatch Table has been built
table-initialized dispatch Table initialized flag has been set
table-redrawing confirm forced Table is being redawn, check if a module wants to handler the layout refresh instead of the default action
table-redraw dispatch forced Table has been redrawn
table-resized dispatch Table container has been resized
table-layout dispatch Column layout has been run, after rendering
table-destroy dispatch Table has been destroyed
placeholder chain placeholder Replacement placeholder content (string or HTML) Use to replace content of placeholder element when it is drawn

Footer Events

Key Type Arguments Response Notes
footer-redraw dispatch The footer has been redrawn

Layout Events

Key Type Arguments Response Notes
layout-refreshing dispatch The current layout is being redrawn
layout-refreshed dispatch The current layout has been redrawn
redraw-blocking dispatch The redrawBlock function has been called but before the column and row managers have blocked redrawing
redraw-blocked dispatch The redrawBlock function has been called and the column and row managers have blocked redrawing
redraw-restoring dispatch The redrawRestore function has been called but before the column and row managers have restored redrawing
redraw-restored dispatch The redrawRestore function has been called and the column and row managers have restored redrawing

Scroll Events

Key Type Arguments Response Notes
scroll-horizontal dispatch left, dir The table has been horizontally scrolled
scroll-vertical dispatch top, dir The table has been vertically scrolled
scrollbar-vertical dispatch width The vertical scroll bar has appeared/disappered

Renderer Events

Key Type Arguments Response Notes
render-virtual-fill dispatch The vertical virtual renderer has completed a fill

Data Events

Key Type Arguments Response Notes
data-loading confirm data, params, config, silent (boolean) true indicated remote data loading events should be used Check if any modules want to load data
data-params chain data, config, silent, previousValue (object) params object for remote request Return a params object for use in a remote data request
data-load chain data, params, config, silent (Promise - resolves array) a promise that resolves with an array of row data object Trigger modules remote data retrieval, passd the params returned from the data-params event
data-loaded chain data (array) an array of row data objects Handle incoming data, pass the array resolved from the data-load event event
data-processing dispatch Data is being loaded into the row manager for processing
data-processed dispatch Data has been processed by the row manager
data-refreshing dispatch The row management pipeline is refreshing the table data
data-refreshed dispatch The row management pipeline has refreshed the table data

Cell Events

Lifecycle Events

Key Type Arguments Response Notes
cell-init dispatch cell Cell is first initialized
cell-value-changing chain cell, value (any) - return the mutated cell value Cell value is being changed from its initial value
cell-value-save-before dispatch cell Cells changing value is ready to be saved
cell-value-save-after dispatch cell Cells changing value has been saved
cell-value-changed dispatch cell Cells value has been saved, if there has been a change
cell-value-updated dispatch cell cell value has been updated by user (edit or set value)
cell-format chain cell (any) - return the formatted contents of the cell Cell contents needs formatting
cell-layout dispatch cell Cell with its contents is ready for aditional module bindings
cell-rendered dispatch cell Cell has been rendered in the DOM
cell-height dispatch cell, height Called when the cell height has been changed
cell-delete dispatch cell Cell is about to be deleted

Interaction Events

Key Type Arguments Response Notes
cell-click dispatch event, component User left clicks on a cell
cell-dblclick dispatch event, component User double clicks on a cell
cell-contextmenu dispatch event, component User right clicks on a cell
cell-mouseenter dispatch event, component Mouse pointer enters a cell
cell-mouseleave dispatch event, component Mouse pointer leaves a cell
cell-mouseover dispatch event, component Mouse pointer enters a cell or one of its child element
cell-mouseout dispatch event, component Mouse pointer leaves a cell or one of its child element
cell-mousemove dispatch event, component Mouse pointer moves over a cell
cell-touchstart dispatch event, component User starts touching a cell
cell-touchend dispatch event, component User stops touching a cell

Row Events

Management Events

Key Type Arguments Response Notes
rows-wipe dispatch All rows are being wiped from the table
rows-added dispatch rows Rows have been added to the table
rows-retrieve chain type (array) an array of row component objects A user has requested an array of current rows from the table
rows-visible chain type (array) an array of rows Another part of the table needs an array currently visible rows
rows-sample chain rowCount (array) an array of rows Return an array of rows, used by the renderer to estimate table contents size

Lifecycle Events

Key Type Arguments Response Notes
row-init dispatch row Row is first initialized
row-layout-before dispatch row Before rows first layout - before cell generation and height normalization
row-layout dispatch row Rows first layout
row-layout-after dispatch row After rows first layout
row-relayout dispatch row Row layout reinitialized
row-data-init-before chain row, data (object) - return mutated row data Before data is first set on a row (before it is saved)
row-data-init-after dispatch row After data is first set on a row
row-data-changing chain row, data, updatedData (object) - return mutated row data Rows data is being changed from its initial value
row-data-save-before dispatch row Rows changing data is ready to be saved
row-data-save-after dispatch row Rows changing data has been saved
row-data-changed dispatch row, visible, updatedData after the rows data has been saved, if there has been a change
row-data-retrieve chain row, transformType (object) - return the accessed row data Data is retireved from a row
row-delete dispatch row Row deleteion has been requested by the user
row-deleting dispatch row Row is being deleted
row-deleted dispatch row Row has been deleted and table redawn
row-add dispatch data, pos, index Row add has been requested by the user
row-adding-position chain row, top ({number, boolean}) - return the an object containing the index and position of the row to be inserted Alter the position and index of a row being added
row-adding-index chain row, index, top (number) - The updated index of the incoming row Alter the index of an incoming row, after inclusion in the row data
row-added dispatch row, data, pos, index Row has been added by a user

Interaction Events

Key Type Arguments Response Notes
row-click dispatch event, component User left clicks on a row
row-dblclick dispatch event, component User double clicks on a row
row-contextmenu dispatch event, component User right clicks on a row
row-mouseenter dispatch event, component Mouse pointer enters a row
row-mouseleave dispatch event, component Mouse pointer leaves a row
row-mouseover dispatch event, component Mouse pointer enters a row or one of its child element
row-mouseout dispatch event, component Mouse pointer leaves a row or one of its child element
row-mousemove dispatch event, component Mouse pointer moves over a row
row-touchstart dispatch event, component User starts touching a row
row-touchend dispatch event, component User stops touching a row

Module Events

Key Type Arguments Response Notes
row-move dispatch fromRow, toRow, after User has started moving row
row-moving dispatch fromRow, toRow, after Row is being moved
row-moved dispatch fromRow, toRow, after Row has been moved

Column Events

Management Events

Key Type Arguments Response Notes
columns-loading dispatch Before columns are loaded through setColumns or initial load
columns-loaded dispatch After columns are loaded through setColumns or initial load

Lifecycle Events

Key Type Arguments Response Notes
column-init dispatch column Column is first initialized
column-layout dispatch column Layout column header element
column-format chain column, title, el (any) - return the formatted contents of the column header Column header contents needs formatting
column-rendered dispatch column Called when a column has been added to the DOM
column-height dispatch column, height Called when the column header height has been changed
column-show dispatch column Column has been made visible
column-hide dispatch column Column has been hidden
column-width-fit-before dispatch column Before column width is resized to fit its data
column-width dispatch column Column width updated
column-width-fit-after dispatch column After column width is resized to fit its data
column-add dispatch definition, before, nextToColumn Column add has been requested by the user
column-added dispatch Column has been added
column-delete dispatch column Column is being deleted
column-deleted dispatch column Column has been deleted

Interaction Events

Key Type Arguments Response Notes
column-click dispatch event, component User left clicks on a column header
column-dblclick dispatch event, component User double clicks on a column header
column-contextmenu dispatch event, component User right clicks on a column header
column-mouseenter dispatch event, component Mouse pointer enters a column header
column-mouseleave dispatch event, component Mouse pointer leaves a column header
column-mouseover dispatch event, component Mouse pointer enters a column header or one of its child element
column-mouseout dispatch event, component Mouse pointer leaves a column header or one of its child element
column-mousemove dispatch event, component Mouse pointer moves over a column header
column-touchstart dispatch event, component User starts touching a column header
column-touchend dispatch event, component User stops touching a column header

Module Events

Key Type Arguments Response Notes
column-moving-rows chain fromColumn, toColumn, after (array) - array of any row components that need updating as a result of the move When a column is being moved
column-moved dispatch fromColumn, toColumn, after Column has been moved
column-resized dispatch Column has been resized

Group Events

Lifecycle Events

Key Type Arguments Response Notes
group-changed dispatch The current grouping setup has changed

Interaction Events

Key Type Arguments Response Notes
group-click dispatch event, component User left clicks on a group header
group-dblclick dispatch event, component User double clicks on a group header
group-contextmenu dispatch event, component User right clicks on a group header
group-mouseenter dispatch event, component Mouse pointer enters a group header
group-mouseleave dispatch event, component Mouse pointer leaves a group header
group-mouseover dispatch event, component Mouse pointer enters a group header or one of its child element
group-mouseout dispatch event, component Mouse pointer leaves a group header or one of its child element
group-mousemove dispatch event, component Mouse pointer moves over a group header
group-touchstart dispatch event, component User starts touching a group header
group-touchend dispatch event, component User stops touching a group header

Filter Events

Key Type Arguments Response Notes
filter-changed dispatch The current filter set has changed

Sort Events

Key Type Arguments Response Notes
sort-changed dispatch The current sort order has changed

Page Events

Key Type Arguments Response Notes
page-changed dispatch The current page setup has changed

Edit Events

Key Type Arguments Response Notes
edit-success chain component, news value returningtrue will allow the edit to proceed, returning false with block the completion of the edit Used to check if an edit to a cell can be classed as successfull
edit-cancelled dispatch component An edit of a cell has been cancelled
edit-editor-clear dispatch component, cancelled Dispatched when the editor is being cleared after success or cancel
edit-edited-clear dispatch component Dispatched when the edited state of a cell is being reset
edit-blur confirm cell returning true will prevent the default blur behaviour Dispatched when an edit is about to blur the cell focus, to give the opertunity to preven or override this behaviour

Menu Events

Key Type Arguments Response Notes
menu-opened dispatch menu, popup A new menu has been opened
menu-closed dispatch menu, popup A menu has been closed

Alert Events

Key Type Arguments Response Notes
alert-show dispatch type An alert has been opened
alert-hide dispatch type An alert has been hidden

Clipboard Events

Key Type Arguments Response Notes
clipboard-paste confirm paste event returning true will prevent the paste event from being handled by the cliboard module A user has pasted content into the table

Keybinding Events

Key Type Arguments Response Notes
keybinding-nav-prev dispatch trigger event The navPrev action has been triggered by a keybinding
keybinding-nav-next dispatch trigger event The navNext action has been triggered by a keybinding
keybinding-nav-left dispatch trigger event The navLeft action has been triggered by a keybinding
keybinding-nav-right dispatch trigger event The navRight action has been triggered by a keybinding
keybinding-nav-up dispatch trigger event The navUp action has been triggered by a keybinding
keybinding-nav-down dispatch trigger event The navDown action has been triggered by a keybinding
keybinding-nav-range dispatch trigger event, direction, jump, expand A range navigation action has been triggered by a keybinding
Donate