| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242 |
- /**
- * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md.
- */
- /**
- * @module core/plugincollection
- */
- import Plugin from './plugin';
- import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
- import log from '@ckeditor/ckeditor5-utils/src/log';
- /**
- * Manages a list of CKEditor plugins, including loading, resolving dependencies and initialization.
- */
- export default class PluginCollection {
- /**
- * Creates an instance of the PluginCollection class.
- * Allows loading and initializing plugins and their dependencies.
- *
- * @param {module:core/editor/editor~Editor} editor
- * @param {Array.<Function>} [availablePlugins] Plugins (constructors) which the collection will be able to use
- * when {@link module:core/plugin~PluginCollection#load} is used with plugin names (strings, instead of constructors).
- * Usually, the editor will pass its built-in plugins to the collection so they can later be
- * used in `config.plugins` or `config.removePlugins` by names.
- */
- constructor( editor, availablePlugins = [] ) {
- /**
- * @protected
- * @member {module:core/editor/editor~Editor} module:core/plugin~PluginCollection#_editor
- */
- this._editor = editor;
- /**
- * Map of plugin constructors which can be retrieved by their names.
- *
- * @protected
- * @member {Map.<String|Function,Function>} module:core/plugin~PluginCollection#_availablePlugins
- */
- this._availablePlugins = new Map();
- /**
- * @protected
- * @member {Map} module:core/plugin~PluginCollection#_plugins
- */
- this._plugins = new Map();
- for ( const PluginConstructor of availablePlugins ) {
- this._availablePlugins.set( PluginConstructor, PluginConstructor );
- if ( PluginConstructor.pluginName ) {
- this._availablePlugins.set( PluginConstructor.pluginName, PluginConstructor );
- }
- }
- }
- /**
- * Collection iterator. Returns `[ PluginConstructor, pluginInstance ]` pairs.
- */
- *[ Symbol.iterator ]() {
- for ( const entry of this._plugins ) {
- if ( typeof entry[ 0 ] == 'function' ) {
- yield entry;
- }
- }
- }
- /**
- * Gets the plugin instance by its constructor or name.
- *
- * @param {Function|String} key The plugin constructor or {@link module:core/plugin~Plugin.pluginName name}.
- * @returns {module:core/plugin~Plugin}
- */
- get( key ) {
- return this._plugins.get( key );
- }
- /**
- * Loads a set of plugins and adds them to the collection.
- *
- * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~Plugin plugin constructors}
- * or {@link module:core/plugin~Plugin.pluginName plugin names}. The second option (names) work only if
- * `availablePlugins` were passed to the {@link #constructor}.
- * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
- * which should not be loaded (despite being specified in the `plugins` array).
- * @returns {Promise} A promise which gets resolved once all plugins are loaded and available into the
- * collection.
- * @returns {Promise.<Array.<module:core/plugin~Plugin>>} returns.loadedPlugins The array of loaded plugins.
- */
- load( plugins, removePlugins = [] ) {
- const that = this;
- const editor = this._editor;
- const loading = new Set();
- const loaded = [];
- const pluginConstructors = mapToAvailableConstructors( plugins );
- const removePluginConstructors = mapToAvailableConstructors( removePlugins );
- const missingPlugins = getMissingPluginNames( plugins );
- if ( missingPlugins ) {
- // TODO update this error docs with links to docs because it will be a frequent problem.
- /**
- * Some plugins are not available and could not be loaded.
- *
- * Plugin classes (constructors) need to be provided to the editor before they can be loaded by name.
- * This is usually done by the builder by setting the {@link module:core/editor/editor~Editor.build}
- * property.
- *
- * @error plugincollection-plugin-not-found
- * @param {Array.<String>} plugins The name of the plugins which could not be loaded.
- */
- const errorMsg = 'plugincollection-plugin-not-found: Some plugins are not available and could not be loaded.';
- // Log the error so it's more visible on the console. Hopefuly, for better DX.
- log.error( errorMsg, { plugins: missingPlugins } );
- return Promise.reject( new CKEditorError( errorMsg, { plugins: missingPlugins } ) );
- }
- return Promise.all( pluginConstructors.map( loadPlugin ) )
- .then( () => loaded );
- function loadPlugin( PluginConstructor ) {
- if ( removePluginConstructors.includes( PluginConstructor ) ) {
- return;
- }
- // The plugin is already loaded or being loaded - do nothing.
- if ( that.get( PluginConstructor ) || loading.has( PluginConstructor ) ) {
- return;
- }
- return instantiatePlugin( PluginConstructor )
- .catch( err => {
- /**
- * It was not possible to load the plugin.
- *
- * @error plugincollection-load
- * @param {String} plugin The name of the plugin that could not be loaded.
- */
- log.error( 'plugincollection-load: It was not possible to load the plugin.', { plugin: PluginConstructor } );
- throw err;
- } );
- }
- function instantiatePlugin( PluginConstructor ) {
- return new Promise( resolve => {
- loading.add( PluginConstructor );
- assertIsPlugin( PluginConstructor );
- if ( PluginConstructor.requires ) {
- PluginConstructor.requires.forEach( RequiredPluginConstructorOrName => {
- const RequiredPluginConstructor = getPluginConstructor( RequiredPluginConstructorOrName );
- if ( removePlugins.includes( RequiredPluginConstructor ) ) {
- /**
- * Cannot load a plugin because one of its dependencies is listed in the `removePlugins` option.
- *
- * @error plugincollection-required
- * @param {Function} plugin The required plugin.
- * @param {Function} requiredBy The parent plugin.
- */
- throw new CKEditorError(
- 'plugincollection-required: Cannot load a plugin because one of its dependencies is listed in' +
- 'the `removePlugins` option.',
- { plugin: RequiredPluginConstructor, requiredBy: PluginConstructor }
- );
- }
- loadPlugin( RequiredPluginConstructor );
- } );
- }
- const plugin = new PluginConstructor( editor );
- that._add( PluginConstructor, plugin );
- loaded.push( plugin );
- resolve();
- } );
- }
- function getPluginConstructor( PluginConstructorOrName ) {
- if ( typeof PluginConstructorOrName == 'function' ) {
- return PluginConstructorOrName;
- }
- return that._availablePlugins.get( PluginConstructorOrName );
- }
- function assertIsPlugin( PluginConstructor ) {
- if ( !( PluginConstructor.prototype instanceof Plugin ) ) {
- /**
- * The loaded plugin module is not an instance of {@link module:core/plugin~Plugin}.
- *
- * @error plugincollection-instance
- * @param {*} plugin The constructor which is meant to be loaded as a plugin.
- */
- throw new CKEditorError(
- 'plugincollection-instance: The loaded plugin module is not an instance of Plugin.',
- { plugin: PluginConstructor }
- );
- }
- }
- function getMissingPluginNames( plugins ) {
- const missingPlugins = [];
- for ( const pluginNameOrConstructor of plugins ) {
- if ( !getPluginConstructor( pluginNameOrConstructor ) ) {
- missingPlugins.push( pluginNameOrConstructor );
- }
- }
- return missingPlugins.length ? missingPlugins : null;
- }
- function mapToAvailableConstructors( plugins ) {
- return plugins
- .map( pluginNameOrConstructor => getPluginConstructor( pluginNameOrConstructor ) )
- .filter( PluginConstructor => !!PluginConstructor );
- }
- }
- /**
- * Adds the plugin to the collection. Exposed mainly for testing purposes.
- *
- * @protected
- * @param {Function} PluginConstructor The plugin constructor.
- * @param {module:core/plugin~Plugin} plugin The instance of the plugin.
- */
- _add( PluginConstructor, plugin ) {
- this._plugins.set( PluginConstructor, plugin );
- if ( PluginConstructor.pluginName ) {
- this._plugins.set( PluginConstructor.pluginName, plugin );
- }
- }
- }
|