Internal Event Bus

• Overview
• Table Events
• Data Events
• Cell Events
• Row Events
• Column Events
• Group Events
• Filter Events
• Sort Events
• Page Events
• Edit Events

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-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

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

Interaction 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

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 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