plugin.js 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module core/plugin
  7. */
  8. import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
  9. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  10. /**
  11. * The base class for CKEditor plugin classes.
  12. *
  13. * @implements module:core/plugin~PluginInterface
  14. * @mixes module:utils/observablemixin~ObservableMixin
  15. */
  16. export default class Plugin {
  17. /**
  18. * @inheritDoc
  19. */
  20. constructor( editor ) {
  21. /**
  22. * The editor instance.
  23. *
  24. * Note that most editors implement the {@link module:core/editor/editorwithui~EditorWithUI} interface in addition
  25. * to the base {@link module:core/editor/editor~Editor} interface. However, editors with an external UI
  26. * (i.e. Bootstrap-based) or a headless editor may not implement the {@link module:core/editor/editorwithui~EditorWithUI}
  27. * interface.
  28. *
  29. * Because of above, to make plugins more universal, it is recommended to split features into:
  30. * - The "editing" part that only uses the {@link module:core/editor/editor~Editor} interface.
  31. * - The "UI" part that uses both the {@link module:core/editor/editor~Editor} interface and
  32. * the {@link module:core/editor/editorwithui~EditorWithUI} interface.
  33. *
  34. * @readonly
  35. * @member {module:core/editor/editor~Editor} #editor
  36. */
  37. this.editor = editor;
  38. }
  39. /**
  40. * @inheritDoc
  41. */
  42. destroy() {
  43. this.stopListening();
  44. }
  45. /**
  46. * @inheritDoc
  47. */
  48. static get isContextPlugin() {
  49. return false;
  50. }
  51. }
  52. mix( Plugin, ObservableMixin );
  53. /**
  54. * The base interface for CKEditor plugins.
  55. *
  56. * In its minimal form a plugin can be a simple function that accepts {@link module:core/editor/editor~Editor the editor}
  57. * as a parameter:
  58. *
  59. * // A simple plugin that enables a data processor.
  60. * function MyPlugin( editor ) {
  61. * editor.data.processor = new MyDataProcessor();
  62. * }
  63. *
  64. * In most cases however, you will want to inherit from the {@link module:core/plugin~Plugin} class which implements the
  65. * {@link module:utils/observablemixin~ObservableMixin} and is, therefore, more convenient:
  66. *
  67. * class MyPlugin extends Plugin {
  68. * init() {
  69. * // `listenTo()` and `editor` are available thanks to `Plugin`.
  70. * // By using `listenTo()` you will ensure that the listener is removed when
  71. * // the plugin is destroyed.
  72. * this.listenTo( this.editor.data, 'ready', () => {
  73. * // Do something when the data is ready.
  74. * } );
  75. * }
  76. * }
  77. *
  78. * The plugin can also implement methods (e.g. {@link module:core/plugin~PluginInterface#init `init()`} or
  79. * {@link module:core/plugin~PluginInterface#destroy `destroy()`}) which, when present, will be used to properly
  80. * initialize and destroy the plugin.
  81. *
  82. * **Note:** When defined as a plain function, the plugin acts as a constructor and will be
  83. * called in parallel with other plugins' {@link module:core/plugin~PluginInterface#constructor constructors}.
  84. * This means the code of that plugin will be executed **before** {@link module:core/plugin~PluginInterface#init `init()`} and
  85. * {@link module:core/plugin~PluginInterface#afterInit `afterInit()`} methods of other plugins and, for instance,
  86. * you cannot use it to extend other plugins' {@glink framework/guides/architecture/editing-engine#schema schema}
  87. * rules as they are defined later on during the `init()` stage.
  88. *
  89. * @interface PluginInterface
  90. */
  91. /**
  92. * Creates a new plugin instance. This is the first step of the plugin initialization.
  93. * See also {@link #init} and {@link #afterInit}.
  94. *
  95. * A plugin is always instantiated after its {@link module:core/plugin~PluginInterface.requires dependencies} and the
  96. * {@link #init} and {@link #afterInit} methods are called in the same order.
  97. *
  98. * Usually, you will want to put your plugin's initialization code in the {@link #init} method.
  99. * The constructor can be understood as "before init" and used in special cases, just like
  100. * {@link #afterInit} serves the special "after init" scenarios (e.g.the code which depends on other
  101. * plugins, but which does not {@link module:core/plugin~PluginInterface.requires explicitly require} them).
  102. *
  103. * @method #constructor
  104. * @param {module:core/editor/editor~Editor} editor
  105. */
  106. /**
  107. * An array of plugins required by this plugin.
  108. *
  109. * To keep the plugin class definition tight it is recommended to define this property as a static getter:
  110. *
  111. * import Image from './image.js';
  112. *
  113. * export default class ImageCaption {
  114. * static get requires() {
  115. * return [ Image ];
  116. * }
  117. * }
  118. *
  119. * @static
  120. * @readonly
  121. * @member {Array.<Function>|undefined} module:core/plugin~PluginInterface.requires
  122. */
  123. /**
  124. * An optional name of the plugin. If set, the plugin will be available in
  125. * {@link module:core/plugincollection~PluginCollection#get} by its
  126. * name and its constructor. If not, then only by its constructor.
  127. *
  128. * The name should reflect the constructor name.
  129. *
  130. * To keep the plugin class definition tight it is recommended to define this property as a static getter:
  131. *
  132. * export default class ImageCaption {
  133. * static get pluginName() {
  134. * return 'ImageCaption';
  135. * }
  136. * }
  137. *
  138. * Note: The native `Function.name` property could not be used to keep the plugin name because
  139. * it will be mangled during code minification.
  140. *
  141. * Naming a plugin is necessary to enable removing it through the
  142. * {@link module:core/editor/editorconfig~EditorConfig#removePlugins `config.removePlugins`} option.
  143. *
  144. * @static
  145. * @readonly
  146. * @member {String|undefined} module:core/plugin~PluginInterface.pluginName
  147. */
  148. /**
  149. * The second stage (after plugin {@link #constructor}) of plugin initialization.
  150. * Unlike the plugin constructor this method can be asynchronous.
  151. *
  152. * A plugin's `init()` method is called after its {@link module:core/plugin~PluginInterface.requires dependencies} are initialized,
  153. * so in the same order as constructors of these plugins.
  154. *
  155. * **Note:** This method is optional. A plugin instance does not need to have it defined.
  156. *
  157. * @method #init
  158. * @returns {null|Promise}
  159. */
  160. /**
  161. * The third (and last) stage of plugin initialization. See also {@link #constructor} and {@link #init}.
  162. *
  163. * **Note:** This method is optional. A plugin instance does not need to have it defined.
  164. *
  165. * @method #afterInit
  166. * @returns {null|Promise}
  167. */
  168. /**
  169. * Destroys the plugin.
  170. *
  171. * **Note:** This method is optional. A plugin instance does not need to have it defined.
  172. *
  173. * @method #destroy
  174. * @returns {null|Promise}
  175. */
  176. /**
  177. * A flag which defines if plugin is allowed or not allowed to be use directly by a {@link module:core/context~Context}.
  178. *
  179. * @static
  180. * @readonly
  181. * @member {Boolean} module:core/plugin~PluginInterface.isContextPlugin
  182. */
  183. /**
  184. * Array of loaded plugins.
  185. *
  186. * @typedef {Array.<module:core/plugin~PluginInterface>} module:core/plugin~LoadedPlugins
  187. */