trigger()

Since: DataTables 2.0

Trigger an event.

Description

This method is designed for use by DataTables extension authors to be able to trigger events in the same way that DataTables does internally. Events can be useful to let developers know that a certain action has happened and that they can perform some other operations. For example the Buttons extension triggers events when a button is processing an action or that an action has happened.

As with the other DataTables events, any event triggered with this method will have the .dt namespace appended to it. Additionally, event handlers are executed with the scope the table element for the DataTable and the event object has a dt property appended to it containing a DataTables API instance.

By default triggered events do not bubble up the document, as that operation has a performance impact. However, it is possible to enable bubbling with the optional third parameter. If enabled and the table is not in the document, the event will still be triggered on the body element.

Backwards compatibility note

Please note that prior to 3.0, the return value from this method would contain values from the event handlers, however, that could cause significant issues if multiple event handlers were used.

As a result, from 3.0, the values in the data set will reflect the defaultPrevented state of the event object for each item in the array (this matches the evolution of Event.returnValue to defaultPrevented in web standards).

Type

`trigger( name, args [, bubbles ] )`

Trigger a DataTables related event.

Parameters:

	Name	Type	Optional
1	`name`	`string`	No
	The event name.
2	`args`	`array`	No
	An array of the arguments to send to the event.
3	`bubbles`	`boolean`	Yes - default:false
	Indicate if the event should bubble up the document in the same way that DOM events usually do, or not. There is a performance impact for bubbling events.

Returns:

DataTable.Api:
A result set that contains a boolean indicating if the default action for the event should be prevented (i.e. if e.preventDefault() was called in an event handler). A value of true will be present if preventDefault was called, false otherwise.

Examples

Listen for and trigger a custom event:

let table = new DataTable('#myTable');

table.on('customEvent', function (e, length, start) {
	console.log(length, start);
	// would print `1, 0`
});

table.trigger('customEvent', [1, 0]);

Access the DataTables API in a custom event:

let table = new DataTable('#myTable');

table.on('customEvent', function (e) {
	let info = e.dt.page.info();

	console.log(info);
});

table.trigger('customEvent');

The following options are directly related and may also be useful in your application development.

API