Interface

PluginInterface (core)

@ckeditor/ckeditor5-core/src/plugin

interface

The base interface for CKEditor plugins.

In its minimal form a plugin can be a simple function that accepts the editor as a parameter:

// A simple plugin that enables a data processor.
function MyPlugin( editor ) {
    editor.data.processor = new MyDataProcessor();
}

In most cases however, you will want to inherit from the Plugin class which implements the ObservableMixin and is, therefore, more convenient:

class MyPlugin extends Plugin {
    init() {
        // `listenTo()` and `editor` are available thanks to `Plugin`.
        // By using `listenTo()` you will ensure that the listener is removed when
        // the plugin is destroyed.
        this.listenTo( this.editor.data, 'ready', () => {
            // Do something when the data is ready.
        } );
    }
}

The plugin can also implement methods (e.g. init() or destroy()) which, when present, will be used to properly initialize and destroy the plugin.

Note: When defined as a plain function, the plugin acts as a constructor and will be called in parallel with other plugins' constructors. This means the code of that plugin will be executed before init() and afterInit() methods of other plugins and, for instance, you cannot use it to extend other plugins' schema rules as they are defined later on during the init() stage.

Filtering

Properties

Static properties

  • pluginName : String | undefined

    readonly static

    An optional name of the plugin. If set, the plugin will be available in get by its name and its constructor. If not, then only by its constructor.

    The name should reflect the constructor name.

    To keep the plugin class definition tight it is recommended to define this property as a static getter:

    export default class ImageCaption {
        static get pluginName() {
            return 'ImageCaption';
        }
    }

    Note: The native Function.name property could not be used to keep the plugin name because it will be mangled during code minification.

    Naming a plugin is necessary to enable removing it through the config.removePlugins option.

  • requires : Array.<Function> | undefined

    readonly static

    An array of plugins required by this plugin.

    To keep the plugin class definition tight it is recommended to define this property as a static getter:

    import Image from './image.js';
    
    export default class ImageCaption {
        static get requires() {
            return [ Image ];
        }
    }

Methods

  • constructor( editor )

    Creates a new plugin instance. This is the first step of the plugin initialization. See also init and afterInit.

    A plugin is always instantiated after its dependencies and the init and afterInit methods are called in the same order.

    Usually, you will want to put your plugin's initialization code in the init method. The constructor can be understood as "before init" and used in special cases, just like afterInit serves the special "after init" scenarios (e.g.the code which depends on other plugins, but which does not explicitly require them).

    Parameters

    editor : Editor
  • afterInit() → null | Promise

    The third (and last) stage of plugin initialization. See also constructor and init.

    Note: This method is optional. A plugin instance does not need to have it defined.

    Returns

    null | Promise
  • destroy() → null | Promise

    Destroys the plugin.

    Note: This method is optional. A plugin instance does not need to have it defined.

    Returns

    null | Promise
  • init() → null | Promise

    The second stage (after plugin constructor) of plugin initialization. Unlike the plugin constructor this method can be asynchronous.

    A plugin's init() method is called after its dependencies are initialized, so in the same order as constructors of these plugins.

    Note: This method is optional. A plugin instance does not need to have it defined.

    Returns

    null | Promise