Documentation

Button

add

Arguments
name String
button Object

Adds a button to the toolbar or to the control bar.

this.app.toolbar.add('mybutton', button);
this.app.control.add('mybutton', button);
this.app.addbar.add('mybutton', button);

The button object can contain the parameters described below.

All the examples show the method of adding a button to the toolbar. The button object can have the same parameters to add to the control bar.

In all examples, Font Awesome is used for the button icon. You can add your own HTML and SVG icon.

position

The position of the button in the toolbar or control bar.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    position: 'first'
});

Add a button to the beginning of the toolbar.

position: 'first'

Add a new button after the specified button.

position: { after: 'buttonname' }

Add a new button before the specified button.

position: { before: 'buttonname' }

blocks

Adds a button only for specific blocks.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    blocks: {
        all: 'editable'
    }
});
  • all
    • for all block, by default
  • editable
    • for editable blocks only
  • first-level
    • for first-level blocks only
  • types
    • for specified blocks only
this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    blocks: {
        types: ['paragraph', 'heading']
    }
});

except

Adds a button to blocks except specified in the array.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    blocks: {
        all: 'editable',
        except: ['list']
    }
});

active

Makes the toolbar button active if the cursor is in the specified type of blocks.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    active: {
        types: ['type-of-block']
    }
});

Makes the toolbar button active if the cursor is in the specified tags.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle',
    active: {
        tags: ['name-of-tag']
    }
});

title

The text that will be displayed on the icon. You can use html.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle'
});

icon

Icon button in HTML or SVG format.

this.app.toolbar.add('mybutton', {
    title: 'My Button',
    icon: '<i class="fa fa-file-alt"></i>',
    command: 'myplugin.toggle'
});

observer

A method that will check whether a button is displayed. If the button does not need to be shown on a specific condition when clicking on a block, then the method should return false, in other cases it is necessary to return the button object.

ArticleEditor.add('plugin', 'myplugin', {
    start: function() {
        this.app.toolbar.add('mybutton', {
            title: 'My Button',
            icon: '<i class="fa fa-file-alt"></i>',
            command: 'myplugin.toggle',
            observer: 'myplugin.observe'
        });
    },
    observe: function(obj, name) {
        if (somethings) {
            return false;
        }

        return obj;
    },
    toggle: function(params, button) {
        // do something
    }
});

command

Calls the specified method when the button is clicked.

ArticleEditor.add('plugin', 'myplugin', {
    start: function() {
        this.app.toolbar.add('mybutton', {
            title: 'My Button',
            icon: '<i class="fa fa-file-alt"></i>',
            command: 'myplugin.toggle'
        });
    },
    toggle: function(params, button, name, e) {
        // do something
    }
});

The command passes the object with following values:

  • params — button parameters
  • button — button instance
  • name — name of the button
  • e — button click event object

params

It is specified as an object and is passed as an argument when the button command is called.

ArticleEditor.add('plugin', 'myplugin', {
    start: function() {
        this.app.toolbar.add('mybutton', {
            title: 'My Button',
            icon: '<i class="fa fa-file-alt"></i>',
            command: 'myplugin.toggle',
            params: {
                arg1: value1,
                arg2: value2
            }
        });
    },
    toggle: function(params, button, name, e) {
        // get params
        console.log(params.arg1, params.arg2);
    }
});