plugin.js 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  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. * @readonly
  25. * @member {module:core/editor/editor~Editor} #editor
  26. */
  27. this.editor = editor;
  28. }
  29. /**
  30. * @inheritDoc
  31. */
  32. destroy() {
  33. this.stopListening();
  34. }
  35. }
  36. mix( Plugin, ObservableMixin );
  37. /**
  38. * The base interface for CKEditor plugins.
  39. *
  40. * In its minimal form it can be a simple function (it will be used as a constructor) which accepts
  41. * {@link module:core/editor/editor~Editor the editor} as a parm.
  42. * It can also implement a few methods which, when present, will be used to properly initialize and destroy the plugin.
  43. *
  44. * // A simple plugin which enables a data processor.
  45. * function MyPlugin( editor ) {
  46. * editor.data.processor = new MyDataProcessor();
  47. * }
  48. *
  49. * In most cases, however, you'll want to inherit from the {@link module:core/plugin~Plugin} class which implements the
  50. * {@link module:utils/observablemixin~ObservableMixin} and is, therefore, more convenient:
  51. *
  52. * class MyPlugin extends Plugin {
  53. * init() {
  54. * // `listenTo()` and `editor` are available thanks to `Plugin`.
  55. * // By using `listenTo()` you'll ensure that the listener will be removed when
  56. * // the plugin is destroyed.
  57. * this.listenTo( this.editor, 'dataReady', () => {
  58. * // Do something when data is ready.
  59. * } );
  60. * }
  61. * }
  62. *
  63. * @interface PluginInterface
  64. */
  65. /**
  66. * Creates a new plugin instance. This is the first step of a plugin initialization.
  67. * See also {@link #init} and {@link #afterInit}.
  68. *
  69. * A plugin is always instantiated after its {@link module:core/plugin~PluginInterface.requires dependencies} and the
  70. * {@link #init} and {@link #afterInit} methods are called in the same order.
  71. *
  72. * Usually, you'll want to put your plugin's initialization code in the {@link #init} method.
  73. * The constructor can be understood as "before init" and used in special cases, just like
  74. * {@link #afterInit} servers for the special "after init" scenarios (e.g. code which depends on other
  75. * plugins, but which doesn't {@link module:core/plugin~PluginInterface.requires explicitly require} them).
  76. *
  77. * @method #constructor
  78. * @param {module:core/editor/editor~Editor} editor
  79. */
  80. /**
  81. * An array of plugins required by this plugin.
  82. *
  83. * To keep a plugin class definition tight it's recommended to define this property as a static getter:
  84. *
  85. * import Image from './image.js';
  86. *
  87. * export default class ImageCaption {
  88. * static get requires() {
  89. * return [ Image ];
  90. * }
  91. * }
  92. *
  93. * @static
  94. * @readonly
  95. * @member {Array.<Function>|undefined} module:core/plugin~PluginInterface.requires
  96. */
  97. /**
  98. * Optional name of the plugin. If set, the plugin will be available in
  99. * {@link module:core/plugincollection~PluginCollection#get} by its
  100. * name and its constructor. If not, then only by its constructor.
  101. *
  102. * The name should reflect the constructor name.
  103. *
  104. * To keep a plugin class definition tight it's recommended to define this property as a static getter:
  105. *
  106. * export default class ImageCaption {
  107. * static get pluginName() {
  108. * return 'ImageCaption';
  109. * }
  110. * }
  111. *
  112. * Note: The native `Function.name` property could not be used to keep the plugin name because
  113. * it will be mangled during code minification.
  114. *
  115. * Naming a plugin is necessary to enable removing it through the
  116. * {@link module:core/editor/editorconfig~EditorConfig#removePlugins `config.removePlugins`} option.
  117. *
  118. * @static
  119. * @readonly
  120. * @member {String|undefined} module:core/plugin~PluginInterface.pluginName
  121. */
  122. /**
  123. * The second stage (after plugin {@link #constructor}) of plugin initialization.
  124. * Unlike the plugin constructor this method can be asynchronous.
  125. *
  126. * A plugin's `init()` method is called after its {@link module:core/plugin~PluginInterface.requires dependencies} are initialized,
  127. * so in the same order as constructors of these plugins.
  128. *
  129. * **Note:** This method is optional. A plugin instance does not need to have to have it defined.
  130. *
  131. * @method #init
  132. * @returns {null|Promise}
  133. */
  134. /**
  135. * The third (and last) stage of plugin initialization. See also {@link #constructor} and {@link #init}.
  136. *
  137. * **Note:** This method is optional. A plugin instance does not need to have to have it defined.
  138. *
  139. * @method #afterInit
  140. * @returns {null|Promise}
  141. */
  142. /**
  143. * Destroys the plugin.
  144. *
  145. * **Note:** This method is optional. A plugin instance does not need to have to have it defined.
  146. *
  147. * @method #destroy
  148. * @returns {null|Promise}
  149. */