/** * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved. * For licensing, see LICENSE.md. */ /** * @module core/plugin */ import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin'; import mix from '@ckeditor/ckeditor5-utils/src/mix'; /** * The base class for CKEditor plugin classes. * * @implements module:core/plugin~PluginInterface * @mixes module:utils/observablemixin~ObservableMixin */ export default class Plugin { /** * @inheritDoc */ constructor( editor ) { /** * The editor instance. * * @readonly * @member {module:core/editor/editor~Editor} #editor */ this.editor = editor; } /** * @inheritDoc */ destroy() { this.stopListening(); } } mix( Plugin, ObservableMixin ); /** * The base interface for CKEditor plugins. * * In its minimal form it can be a simple function (it will be used as a constructor) which accepts * {@link module:core/editor/editor~Editor the editor} as a parm. * It can also implement a few methods which, when present, will be used to properly initialize and destroy the plugin. * * // A simple plugin which enables a data processor. * function MyPlugin( editor ) { * editor.data.processor = new MyDataProcessor(); * } * * In most cases, however, you'll want to inherit from the {@link module:core/plugin~Plugin} class which implements the * {@link module:utils/observablemixin~ObservableMixin} and is, therefore, more convenient: * * class MyPlugin extends Plugin { * init() { * // `listenTo()` and `editor` are available thanks to `Plugin`. * // By using `listenTo()` you'll ensure that the listener will be removed when * // the plugin is destroyed. * this.listenTo( this.editor, 'dataReady', () => { * // Do something when data is ready. * } ); * } * } * * @interface PluginInterface */ /** * Creates a new plugin instance. This is the first step of a plugin initialization. * See also {@link #init} and {@link #afterInit}. * * A plugin is always instantiated after its {@link module:core/plugin~PluginInterface.requires dependencies} and the * {@link #init} and {@link #afterInit} methods are called in the same order. * * Usually, you'll want to put your plugin's initialization code in the {@link #init} method. * The constructor can be understood as "before init" and used in special cases, just like * {@link #afterInit} servers for the special "after init" scenarios (e.g. code which depends on other * plugins, but which doesn't {@link module:core/plugin~PluginInterface.requires explicitly require} them). * * @method #constructor * @param {module:core/editor/editor~Editor} editor */ /** * An array of plugins required by this plugin. * * To keep a plugin class definition tight it's recommended to define this property as a static getter: * * import Image from './image.js'; * * export default class ImageCaption { * static get requires() { * return [ Image ]; * } * } * * @static * @readonly * @member {Array.|undefined} module:core/plugin~PluginInterface.requires */ /** * Optional name of the plugin. If set, the plugin will be available in * {@link module:core/plugincollection~PluginCollection#get} by its * name and its constructor. If not, then only by its constructor. * * The name should reflect the constructor name. * * To keep a plugin class definition tight it's 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 * {@link module:core/editor/editorconfig~EditorConfig#removePlugins `config.removePlugins`} option. * * @static * @readonly * @member {String|undefined} module:core/plugin~PluginInterface.pluginName */ /** * The second stage (after plugin {@link #constructor}) of plugin initialization. * Unlike the plugin constructor this method can be asynchronous. * * A plugin's `init()` method is called after its {@link module:core/plugin~PluginInterface.requires 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 to have it defined. * * @method #init * @returns {null|Promise} */ /** * The third (and last) stage of plugin initialization. See also {@link #constructor} and {@link #init}. * * **Note:** This method is optional. A plugin instance does not need to have to have it defined. * * @method #afterInit * @returns {null|Promise} */ /** * Destroys the plugin. * * **Note:** This method is optional. A plugin instance does not need to have to have it defined. * * @method #destroy * @returns {null|Promise} */