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:

Javascript
1
2
3
4
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:

Javascript
1
2
3
4
5
6
7
8
9
10
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:

Javascript
1
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:

Javascript
1
2
3
4
5
6
7
8
9
10
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):

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

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

Comments (0)