Writing Custom Plugins

Release 2.4.0 and above.

API

SynapEditor.addPlugin(pluginName, pluginGenerator)

Adds a plugin to Synap Editor.

Params:

Example:

var pluginName = "pluginName";
var pluginGenerator = function (editor) {
    // Returns the plugin object.
    return {
        // ...
    };
};
SynapEditor.addPlugin(pluginName, pluginGenerator); // Add the plugin. Must be added before creating the SynapEditor.

// ...
new SynapEditor(editorId, synapEditorconfig, ...); // Create the editor

Plugin Object Shape

Sets the button definition for adding buttons to the toolbar area or menu area.

For more details: buttonDef

Array form

buttonDef: [{
    name: 'button name',         // Required when there are 2 or more buttons. Used as the key when adding to the UI.
    label: 'button text',
    iconSVG: 'SVG tag to use as the button icon',
    onClickFunc: function () {
        // Function executed when the button is clicked
    }
}, ...]

Object form

buttonDef: {
    name: 'button name',         // Optional when there is only 1 button. If not set, the plugin name is used automatically. When set, the button is added to the UI using the configured button name.
    label: 'button text',
    iconSVG: 'SVG tag to use as the button icon',
    onClickFunc: function () {
        // Function executed when the button is clicked
    }
}

Sets the definition for adding shortcuts.

For more details: shortcutDef

Array form

shortcutDef: [{
    key: {
        windows: 'Windows shortcut',
        mac: 'Mac shortcut'
    },
    option: {
        action: 'editor action name',
        params: ['editor action parameter 1', ...],
        focusIme: true or false   // Whether to set editor focus after the shortcut action
    }
}, ...]

Object form

shortcutDef: {
    key: {
        windows: 'Windows shortcut',
        mac: 'Mac shortcut'
    },
    option: {
        action: 'editor action name',
        params: ['editor action parameter 1', ...],
        focusIme: true or false   // Whether to set editor focus after the shortcut action
    }
}

Release 2.9.0 and above.

Registers plugin dialogs.

For more details: dialogs

Example

A plugin that inserts 'Hello World~' into the editor

Define the PluginGenerator

./plugins/helloWorldInserter.js

var pluginName = "helloWorldInserter";
var pluginGenerator = function(editor) {
    return {
        buttonDef: {
            label: 'Hello World Inserter',
            iconSVG: `<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 16 16">
                <g xmlns="http://www.w3.org/2000/svg"><title>Layer 1</title>
                <text stroke="#000000" transform="matrix(0.7835232019424438,0,0,1,0.2672135476022959,0) " xml:space="preserve"
                text-anchor="start" font-family="Helvetica, Arial, sans-serif" font-size="13" y="12.580528" x="-1.056391" fill="#000000">HW</text>
                </g>
                </svg>`,
            onClickFunc: function () {
                editor.execCommand('insertText', 'Hello World~');
            }
        }
    };
};

SynapEditor.addPlugin(pluginName, pluginGenerator); // Add before creating the editor

// ...
new SynapEditor(editorId, synapEditorconfig, ...); // Create the editor

Load the written plugin

./index.html

<!-- synapeditor plugin -->
<script type="text/javascript" src="./plugins/helloWorldInserter.js"></script>

Add the plugin button to the editor toolbar area

./synapeditor.config.js

"editor.toolbar": ["bold", "italic", "underline", "strike", "helloWorldInserter"] // Add the helloWorldInserter plugin to the toolbar area.

Result