Documentation

Overview

Article Editor creates events for various actions in it, as well as for starting and stopping the entire application.

Plugins can also create their own events or subscribe to the events of both the editor and the events of other plugins.

Events help to manipulate actions in the editor, stop certain actions and access the functions of the editor from the outside.

Subscription in the settings when you run the editor

Using the subscribe object, you can specify the events and functions that will be triggered when this event occurs. Here is an example of the function that will be launched at the start of the editor:

ArticleEditor('#entry', {
    css: '/your-article-dist-path/',
    subscribe: {
        'app.start': function() {
            console.log('Article started!');
        }
    }
});

Inside this function, the this object is available, so in this function you can access the editor API, settings and other features, for example, get the current active block and create a condition depending on the setting value:

ArticleEditor('#entry', {
    css: '/your-article-dist-path/',
    subscribe: {
        'app.start': function() {
            var instance = this.app.block.get();
            if (this.opts.editor.focus) {
                // do something
            }
        }
    }
});

Often, events pass to the function an argument in the form of an object, using which you can access the parameters of the event and manipulate them, for example:

ArticleEditor('#entry', {
    css: '/your-article-dist-path/',
    subscribe: {
        'editor.before.load': function(event) {
            var content = event.get('html');
            content = '<p>Hello world!</p>' + content;
            event.set('html', content);
        }
    }
});

In this example, the event occurs before the content sets in the editor. You can get the content and change it, then send it back to the event in a modified form.

How to subscribe to an event in your plugin

Plugins can subscribe to editor events with the subscribe object.

ArticleEditor.add('plugin', 'myplugin', {
    subscribe: {
        'block.remove': function() {
            this.catchBlockRemove();
        }
    },
    start: function() {
        // myplugin start actions
    },
    catchBlockRemove: function() {
        // do something
    }
});

In this example, the catchBlockRemove plugin method will be called each time a block is deleted in the editor.

Send an event from one plugin to another

Any plugin can create its own events using the this.app.broadcast method. These events as well as the editor events can be caught in another plugin.

Here is an example of creating an event in a plugin when it starts:

ArticleEditor.add('plugin', 'myplugin', {
    start: function() {
        this.app.broadcast('myplugin.start');
    }
});

And this is how you can caught this event in another plugin:

ArticleEditor.add('plugin', 'mysecondplugin', {
    subscribe: {
        'myplugin.start': function() {
            this.catchMypluginStart();
        }
    },
    catchMypluginStart: function() {
        // do something
    }
});

Event object

Some events pass an object as argument. This object can take various parameters and has several methods for working with parameters.

The editor triggers an event using the this.app.broadcast method. You can call the same method in your plugin to generate an event and pass event parameters like this:

ArticleEditor.add('plugin', 'myplugin', {
    start: function() {
        this.app.broadcast('myplugin.start', { value: 10 });
    }
});

You can access the event parameters by catch it in another plugin:

ArticleEditor.add('plugin', 'mysecondplugin', {
    subscribe: {
        'myplugin.start': function(event) {
            this.catchMypluginStart(event);
        }
    },
    catchMypluginStart: function(event) {
        // get param
        var value = event.get('value');

        // set param
        event.get('value', 20);
        event.get('customname', 30);
    }
});

As you can see in the example above, you can get the value of the parameter and set it back to the event. The event object is mutable, so setting a new value is reflected for all functions that catch this event.

Event object methods

has

Checks if a parameter exists in the event object. Returns boolean.

var has = event.has('paramname');

get

Returns the value of the parameter.

var value = event.get('paramname');

set

Sets the value of the parameter.

event.set('paramname', 'myvalue');

stop

Indicates the event will be stopped.

event.stop();

isStopped

Checks if the event has been stopped. Returns boolean.

if (event.isStopped()) {
    return;
}

Stop event

Sometimes it may be necessary to stop the event and the actions of the editor after it. This can be done using the stop event object method. For example, you want to stop the editor working under certain conditions on the keydown event, for this you can call the stop method in the caught event.

ArticleEditor.add('plugin', 'myplugin', {
    subscribe: {
        'editor.keydown': function(event) {
            this.catchEvent(event);
        }
    },
    catchEvent: function(event) {
        if (something) {
            event.stop();
        }
    }
});

Now the editor.keydown event will know that all processing by the keydown should be stopped.

In the description of each event, we indicate which of them can be stopped by the stop method.