Events
It can often be useful to know when Editor has performed a particular operation, so you can further instruct the program with additional actions. To provide this information, Editor will trigger custom events as it processes the form operation. Events provide a single point of interface for actions Editor takes as a result of API calls or the end user performing operations on the form with their keyboard and mouse.
As a brief example, the submitSuccess
event is triggered when the Ajax request made by Editor to update the server has been completed and the page updated with the changes. This event could be used to show a message to the user stating that a row has been created, edited or removed.
The Editor event interface is built upon, and styled after, the jQuery DOM event interface. Three API methods are used to interact with the events triggered by Editor:
For a full list of the events that Editor will trigger, please refer to the event reference documentation.
Listening for events
To listen for events emitted by Editor, use the API method's on()
or one()
. These two functions are identical, with a single exception: one()
will be triggered by the first event of that kind only. Any subsequent events would not trigger the callback.
These two functions both take two arguments:
- The event(s) to listen for
- This can be more than one event, separated by a single space, and can include namespaces just like a jQuery event.
- The callback function
- This is the function that is triggered when Editor emits an event of the type(s) given in the first parameter. It will always have an event as the first parameter given to it, but it might also have additional parameter, useful for the type of event, based on what event has been activated.
As an example, to listen for the open
event, which is triggered when the Editor form is shown to the end user you would use:
editor.on( 'open', function ( e, type ) {
// Type is 'main', 'bubble' or 'inline'
alert( 'Editor '+type+' form shown' );
} );
Complex expressions
All of the events, and any combination of them, that Editor emits can be listened for at any time with different callback functions as required. Also the same event can be listened for multiple times. As a more complex example, consider the following:
var openVals;
editor
.on( 'open', function ( e, type ) {
openVals = JSON.stringify( editor.get() );
} )
.on( 'preBlur', function ( e ) {
if ( openVals !== JSON.stringify( editor.get() ) ) {
return confirm( 'You have unsaved changes. Are you sure you want to exit?' );
}
} );
Here we use the open
and preBlur
events to run some custom code when Editor emits these events. Specifically, what is happening is that on open
the data in the form is stored in a variable (using the get()
method to get all of the form values).
Then if a preBlur
event occurs (i.e. the end user clicks on the shaded background) we check the values at that time to the values as they were when the form was opened. If the values have changed, then we ask the user if they are sure they want to discard their changes. Returning false
from preBlur
will cancel the blur (not all events expect a return value, please refer to the individual event's documentation for full details).
DOM events and bubbling
Please note that unlike DataTables, Editor does not emit DOM events. The events from Editor are entirely Javascript based and to listen for these events, you should use the Editor API methods described here.
Removing events
The inverse of on()
is off()
which will cause the events given to no longer be listened for. Just like on()
, off()
is based upon the jQuery off() method, and takes exactly the same parameters:
- The event(s) to no longer be listened for
- Again one or more events which are space separated and can include jQuery event namespaces.
- Optionally - the function to no longer listen for
Continuing our example above of listening for an open
event, let us now remove that event:
editor.off( 'open' );
Namespaces
jQuery event namespaces are a method allowing different components to add and remove event listeners for the same events without interfering with other components. A namespace is added simply by adding a dot (.
) and then the name of the namespace (which is any string you wish to use as an identifier). Multiple namespaces can be used for an event if required.
As an example, let's listen again for an open
event, but this time we'll listen for it twice, with different namespaces, and then remove one of them:
editor
.on( 'open.ns1', function ( e, type ) {
alert( 'Editor form displayed - namespace 1' );
} )
.on( 'open.ns2', function ( e, type ) {
alert( 'Editor form displayed - namespace 2' );
} );
// Then, sometime later, remove the first namespace:
editor.off( 'open.ns1' );
Now when the open
event occurs, only the second namespace event handler will be called.
For more detailed information on namespaces, please refer to the jQuery on() documentation.
Event sequence
It is important to know what order the events that Editor emits are fired in, and when. The following details the events, from initialisation of an editing method through to the submission of the form by the end user and the page being updated.
Create
The following event sequence is triggered by Editor when the create()
method is used (if you are using the Buttons integration that Editor has built in, the create
button type will call this method and the following sequence also applies):
Event | Operation |
---|---|
Create action is triggered by create() |
|
initCreate |
Create form has been initialised, with default values set, and is ready for display. |
preOpen |
Form is about to be shown to the end user. Note that if create() was triggered with the parameters set to not show the form to the end user, this event, open , preClose and close will not be triggered in the following sequence |
open |
Form is displayed |
opened (async) |
Open is complete. This is asynchronous, and is likely to be the last to open in the open sequence |
During this time the form is shown, with the user required to fill in the fields. The following events are triggered when the submit button is pressed (more specifically when submit() is called) |
|
processing |
Processing indicator is shown |
initSubmit |
Data is about to be collected from the form. API can be used to update values if needed |
preSubmit |
Ajax data is prepared and ready to submit and can be manipulated if required |
postSubmit |
Ajax request has been completed, and data retrieved from the server |
preCreate |
Immediately prior to the row addition to the DataTable |
create |
Immediately after the row addition to the DataTable |
postCreate |
Row addition to the DataTable complete |
preClose |
Form display about to be removed |
close |
Form display removed |
closed (async) |
Called after close , and since it's asynchronous, that is likely to happen after submitSuccess and submitComplete |
submitSuccess |
Ajax request completed successfully and Editor actions complete |
processing |
Processing indicator is hidden |
submitComplete |
Ajax request complete and Editor actions complete |
Edit
The following event sequence is triggered by Editor when the edit()
, bubble()
or inline()
methods are used (if you are using the Buttons integration that Editor has built in, the edit
button type will call edit()
and the following sequence also applies):
Event | Operation |
---|---|
Edit action is triggered by edit() , bubble() or inline() |
|
initEdit |
Edit form has been initialised, with values set, and is ready for display. |
preOpen |
Form is about to be shown to the end user. Note that if edit() was triggered with the parameters set to not show the form to the end user, this event, open , preClose and close will not be triggered in the following sequence |
open |
Form is displayed |
opened (async) |
Open is complete. This is asynchronous, and is likely to be the last to open in the open sequence |
During this time the form is shown, with the user required to fill in the fields. The following events are triggered when the submit button is pressed (more specifically when submit() is called) |
|
processing |
Processing indicator is shown |
initSubmit |
Data is about to be collected from the form. API can be used to update values if needed |
preSubmit |
Ajax data is prepared and ready to submit and can be manipulated if required |
postSubmit |
Ajax request has been completed, and data retrieved from the server |
preEdit |
Immediately prior to the row update in the DataTable |
edit |
Immediately after the row update in the DataTable |
postEdit |
Row update in the DataTable complete |
preClose |
Form display about to be removed |
close |
Form display removed |
closed (async) |
Called after close , and since it's asynchronous, that is likely to happen after submitSuccess and submitComplete |
submitSuccess |
Ajax request completed successfully and Editor actions complete |
processing |
Processing indicator is hidden |
submitComplete |
Ajax request complete and Editor actions complete |
Remove
The following event sequence is triggered by Editor when the remove()
method is used (if you are using the Buttons integration that Editor has built in, the remove
button type will call this method and the following sequence also applies):
Event | Operation |
---|---|
Remove action is triggered by remove() |
|
initRemove |
Remove form has been initialised and is ready for display. |
preOpen |
Form is about to be shown to the end user. Note that if create() was triggered with the parameters set to not show the form to the end user, this event, open , preClose and close will not be triggered in the following sequence |
open |
Form is displayed |
opened (async) |
Open is complete. This is asynchronous, and is likely to be the last to open in the open sequence |
During this time the form is shown. The following events are triggered when the submit button is pressed (more specifically when submit() is called) |
|
processing |
Processing indicator is shown |
initSubmit |
Data is about to be collected from the form. API can be used to update values if needed |
preSubmit |
Ajax data is prepared and ready to submit and can be manipulated if required |
postSubmit |
Ajax request has been completed, and data retrieved from the server |
preRemove |
Immediately prior to the row deletion from the DataTable |
remove |
Immediately after the row deletion from the DataTable |
postRemove |
Row deletion from the DataTable complete |
preClose |
Form display about to be removed |
close |
Form display removed |
closed (async) |
Called after close , and since it's asynchronous, that is likely to happen after submitSuccess and submitComplete |
submitSuccess |
Ajax request completed successfully and Editor actions complete |
processing |
Processing indicator is hidden |
submitComplete |
Ajax request complete and Editor actions complete |