Internal Event Bus
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.
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 |
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 |
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 |
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 |
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-moving |
dispatch |
event, column |
|
Column has started to be moved |
column-moved |
dispatch |
fromColumn, toColumn, after |
|
Column has been moved |
column-resized |
dispatch |
|
|
Column has been resized |
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 |
Key |
Type |
Arguments |
Response |
Notes |
filter-changed |
dispatch |
|
|
The current filter set has changed |
Key |
Type |
Arguments |
Response |
Notes |
sort-changed |
dispatch |
|
|
The current sort order has changed |
Key |
Type |
Arguments |
Response |
Notes |
page-changed |
dispatch |
|
|
The current page setup has changed |
Key |
Type |
Arguments |
Response |
Notes |
import-choose |
dispatch |
|
|
The import file picker has been opened |
import-importing |
dispatch |
files |
|
The user has chosen a file to import |
import-error |
dispatch |
error |
|
The import has failed |
import-imported |
dispatch |
data |
|
The import has succeded |
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 |
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 |