plugincollection.js 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module core/plugincollection
  7. */
  8. import Plugin from './plugin';
  9. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  10. import log from '@ckeditor/ckeditor5-utils/src/log';
  11. /**
  12. * Manages a list of CKEditor plugins, including loading, resolving dependencies and initialization.
  13. */
  14. export default class PluginCollection {
  15. /**
  16. * Creates an instance of the PluginCollection class.
  17. * Allows loading and initializing plugins and their dependencies.
  18. *
  19. * @param {module:core/editor/editor~Editor} editor
  20. * @param {Array.<Function>} [availablePlugins] Plugins (constructors) which the collection will be able to use
  21. * when {@link module:core/plugin~PluginCollection#load} is used with plugin names (strings, instead of constructors).
  22. * Usually, the editor will pass its built-in plugins to the collection so they can later be
  23. * used in `config.plugins` or `config.removePlugins` by names.
  24. */
  25. constructor( editor, availablePlugins = [] ) {
  26. /**
  27. * @protected
  28. * @member {module:core/editor/editor~Editor} module:core/plugin~PluginCollection#_editor
  29. */
  30. this._editor = editor;
  31. /**
  32. * Map of plugin constructors which can be retrieved by their names.
  33. *
  34. * @protected
  35. * @member {Map.<String|Function,Function>} module:core/plugin~PluginCollection#_availablePlugins
  36. */
  37. this._availablePlugins = new Map();
  38. /**
  39. * @protected
  40. * @member {Map} module:core/plugin~PluginCollection#_plugins
  41. */
  42. this._plugins = new Map();
  43. for ( const PluginConstructor of availablePlugins ) {
  44. this._availablePlugins.set( PluginConstructor, PluginConstructor );
  45. if ( PluginConstructor.pluginName ) {
  46. this._availablePlugins.set( PluginConstructor.pluginName, PluginConstructor );
  47. }
  48. }
  49. }
  50. /**
  51. * Collection iterator. Returns `[ PluginConstructor, pluginInstance ]` pairs.
  52. */
  53. *[ Symbol.iterator ]() {
  54. for ( const entry of this._plugins ) {
  55. if ( typeof entry[ 0 ] == 'function' ) {
  56. yield entry;
  57. }
  58. }
  59. }
  60. /**
  61. * Gets the plugin instance by its constructor or name.
  62. *
  63. * @param {Function|String} key The plugin constructor or {@link module:core/plugin~Plugin.pluginName name}.
  64. * @returns {module:core/plugin~Plugin}
  65. */
  66. get( key ) {
  67. return this._plugins.get( key );
  68. }
  69. /**
  70. * Loads a set of plugins and adds them to the collection.
  71. *
  72. * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~Plugin plugin constructors}
  73. * or {@link module:core/plugin~Plugin.pluginName plugin names}. The second option (names) work only if
  74. * `availablePlugins` were passed to the {@link #constructor}.
  75. * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
  76. * which should not be loaded (despite being specified in the `plugins` array).
  77. * @returns {Promise} A promise which gets resolved once all plugins are loaded and available into the
  78. * collection.
  79. * @returns {Promise.<Array.<module:core/plugin~Plugin>>} returns.loadedPlugins The array of loaded plugins.
  80. */
  81. load( plugins, removePlugins = [] ) {
  82. const that = this;
  83. const editor = this._editor;
  84. const loading = new Set();
  85. const loaded = [];
  86. const pluginConstructors = mapToAvailableConstructors( plugins );
  87. const removePluginConstructors = mapToAvailableConstructors( removePlugins );
  88. const missingPlugins = getMissingPluginNames( plugins );
  89. if ( missingPlugins ) {
  90. // TODO update this error docs with links to docs because it will be a frequent problem.
  91. /**
  92. * Some plugins are not available and could not be loaded.
  93. *
  94. * Plugin classes (constructors) need to be provided to the editor before they can be loaded by name.
  95. * This is usually done by the builder by setting the {@link module:core/editor/editor~Editor.build}
  96. * property.
  97. *
  98. * @error plugincollection-plugin-not-found
  99. * @param {Array.<String>} plugins The name of the plugins which could not be loaded.
  100. */
  101. const errorMsg = 'plugincollection-plugin-not-found: Some plugins are not available and could not be loaded.';
  102. // Log the error so it's more visible on the console. Hopefuly, for better DX.
  103. log.error( errorMsg, { plugins: missingPlugins } );
  104. return Promise.reject( new CKEditorError( errorMsg, { plugins: missingPlugins } ) );
  105. }
  106. return Promise.all( pluginConstructors.map( loadPlugin ) )
  107. .then( () => loaded );
  108. function loadPlugin( PluginConstructor ) {
  109. if ( removePluginConstructors.includes( PluginConstructor ) ) {
  110. return;
  111. }
  112. // The plugin is already loaded or being loaded - do nothing.
  113. if ( that.get( PluginConstructor ) || loading.has( PluginConstructor ) ) {
  114. return;
  115. }
  116. return instantiatePlugin( PluginConstructor )
  117. .catch( err => {
  118. /**
  119. * It was not possible to load the plugin.
  120. *
  121. * @error plugincollection-load
  122. * @param {String} plugin The name of the plugin that could not be loaded.
  123. */
  124. log.error( 'plugincollection-load: It was not possible to load the plugin.', { plugin: PluginConstructor } );
  125. throw err;
  126. } );
  127. }
  128. function instantiatePlugin( PluginConstructor ) {
  129. return new Promise( resolve => {
  130. loading.add( PluginConstructor );
  131. assertIsPlugin( PluginConstructor );
  132. if ( PluginConstructor.requires ) {
  133. PluginConstructor.requires.forEach( RequiredPluginConstructorOrName => {
  134. const RequiredPluginConstructor = getPluginConstructor( RequiredPluginConstructorOrName );
  135. if ( removePlugins.includes( RequiredPluginConstructor ) ) {
  136. /**
  137. * Cannot load a plugin because one of its dependencies is listed in the `removePlugins` option.
  138. *
  139. * @error plugincollection-required
  140. * @param {Function} plugin The required plugin.
  141. * @param {Function} requiredBy The parent plugin.
  142. */
  143. throw new CKEditorError(
  144. 'plugincollection-required: Cannot load a plugin because one of its dependencies is listed in' +
  145. 'the `removePlugins` option.',
  146. { plugin: RequiredPluginConstructor, requiredBy: PluginConstructor }
  147. );
  148. }
  149. loadPlugin( RequiredPluginConstructor );
  150. } );
  151. }
  152. const plugin = new PluginConstructor( editor );
  153. that._add( PluginConstructor, plugin );
  154. loaded.push( plugin );
  155. resolve();
  156. } );
  157. }
  158. function getPluginConstructor( PluginConstructorOrName ) {
  159. if ( typeof PluginConstructorOrName == 'function' ) {
  160. return PluginConstructorOrName;
  161. }
  162. return that._availablePlugins.get( PluginConstructorOrName );
  163. }
  164. function assertIsPlugin( PluginConstructor ) {
  165. if ( !( PluginConstructor.prototype instanceof Plugin ) ) {
  166. /**
  167. * The loaded plugin module is not an instance of {@link module:core/plugin~Plugin}.
  168. *
  169. * @error plugincollection-instance
  170. * @param {*} plugin The constructor which is meant to be loaded as a plugin.
  171. */
  172. throw new CKEditorError(
  173. 'plugincollection-instance: The loaded plugin module is not an instance of Plugin.',
  174. { plugin: PluginConstructor }
  175. );
  176. }
  177. }
  178. function getMissingPluginNames( plugins ) {
  179. const missingPlugins = [];
  180. for ( const pluginNameOrConstructor of plugins ) {
  181. if ( !getPluginConstructor( pluginNameOrConstructor ) ) {
  182. missingPlugins.push( pluginNameOrConstructor );
  183. }
  184. }
  185. return missingPlugins.length ? missingPlugins : null;
  186. }
  187. function mapToAvailableConstructors( plugins ) {
  188. return plugins
  189. .map( pluginNameOrConstructor => getPluginConstructor( pluginNameOrConstructor ) )
  190. .filter( PluginConstructor => !!PluginConstructor );
  191. }
  192. }
  193. /**
  194. * Adds the plugin to the collection. Exposed mainly for testing purposes.
  195. *
  196. * @protected
  197. * @param {Function} PluginConstructor The plugin constructor.
  198. * @param {module:core/plugin~Plugin} plugin The instance of the plugin.
  199. */
  200. _add( PluginConstructor, plugin ) {
  201. this._plugins.set( PluginConstructor, plugin );
  202. if ( PluginConstructor.pluginName ) {
  203. this._plugins.set( PluginConstructor.pluginName, plugin );
  204. }
  205. }
  206. }