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:

• on() - Listen for events
• one() - Listen for a single event
• off() - Stop listening for events

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:

1. 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.
2. 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:

1. The event(s) to no longer be listened for
   • Again one or more events which are space separated and can include jQuery event namespaces.
2. 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