PluginCollection (core)
@ckeditor/ckeditor5-core/src/plugincollection
Manages a list of CKEditor plugins, including loading, resolving dependencies and initialization.
Filtering
Type parameters
-
TContext
Properties
-
private
_availablePlugins : Map<string, PluginConstructor<TContext>>
module:core/plugincollection~PluginCollection#_availablePlugins
A map of plugin constructors that can be retrieved by their names.
-
private
_contextPlugins : Map<PluginInterface | PluginConstructor<TContext>, PluginInterface | PluginConstructor<TContext>>
module:core/plugincollection~PluginCollection#_contextPlugins
Map of context plugins which can be retrieved by their constructors or instances.
-
private
_plugins : Map<string | PluginConstructor<TContext>, PluginInterface>
module:core/plugincollection~PluginCollection#_plugins
Methods
-
constructor( context, availablePlugins, contextPlugins )
module:core/plugincollection~PluginCollection#constructor
Creates an instance of the plugin collection class. Allows loading and initializing plugins and their dependencies. Allows providing a list of already loaded plugins. These plugins will not be destroyed along with this collection.
Type parameters
TContext
Parameters
context : TContext
availablePlugins : Iterable<PluginConstructor<TContext>>
Plugins (constructors) which the collection will be able to use when
init
is used with the plugin names (strings, instead of constructors). Usually, the editor will pass its built-in plugins to the collection so they can later be used inconfig.plugins
orconfig.removePlugins
by names.Defaults to
[]
contextPlugins : Iterable<PluginEntry<TContext>>
A list of already initialized plugins represented by a
[ PluginConstructor, pluginInstance ]
pair.Defaults to
[]
-
Symbol.iterator() → IterableIterator<PluginEntry<TContext>>
module:core/plugincollection~PluginCollection#Symbol.iterator
Iterable interface.
Returns
[ PluginConstructor, pluginInstance ]
pairs.Returns
IterableIterator<PluginEntry<TContext>>
-
inherited
delegate( events ) → EmitterMixinDelegateChain
module:core/plugincollection~PluginCollection#delegate
Delegates selected events to another
Emitter
. For instance:emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then
eventX
is delegated (fired by)emitterB
andemitterC
along withdata
:emitterA.fire( 'eventX', data );
and
eventY
is delegated (fired by)emitterC
along withdata
:emitterA.fire( 'eventY', data );
Parameters
events : Array<string>
Event names that will be delegated to another emitter.
Returns
-
destroy() → Promise<unknown>
module:core/plugincollection~PluginCollection#destroy
-
inherited
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
module:core/plugincollection~PluginCollection#fire
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfo
object, followed by the optionalargs
provided in thefire()
method call.Type parameters
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>
The name of the event or
EventInfo
object if event is delegated.args : TEvent[ 'args' ]
Additional arguments to be passed to the callbacks.
Returns
GetEventInfo<TEvent>[ 'return' ]
By default the method returns
undefined
. However, the return value can be changed by listeners through modification of theevt.return
's property (the event info is the first param of every callback).
-
get( key ) → PluginsMap[ TName ]
module:core/plugincollection~PluginCollection#get
Gets the plugin instance by its constructor or name.
// Check if 'Clipboard' plugin was loaded. if ( editor.plugins.has( 'ClipboardPipeline' ) ) { // Get clipboard plugin instance const clipboard = editor.plugins.get( 'ClipboardPipeline' ); this.listenTo( clipboard, 'inputTransformation', ( evt, data ) => { // Do something on clipboard input. } ); }
Note: This method will throw an error if a plugin is not loaded. Use
editor.plugins.has()
to check if a plugin is available.Type parameters
TName : extends string
Parameters
key : TName
The plugin constructor or name.
Returns
PluginsMap[ TName ]
-
get( key ) → InstanceType<TConstructor>
module:core/plugincollection~PluginCollection#get
Gets the plugin instance by its constructor or name.
// Check if 'Clipboard' plugin was loaded. if ( editor.plugins.has( 'ClipboardPipeline' ) ) { // Get clipboard plugin instance const clipboard = editor.plugins.get( 'ClipboardPipeline' ); this.listenTo( clipboard, 'inputTransformation', ( evt, data ) => { // Do something on clipboard input. } ); }
Note: This method will throw an error if a plugin is not loaded. Use
editor.plugins.has()
to check if a plugin is available.Type parameters
TConstructor : extends PluginClassConstructor<TContext>
Parameters
key : TConstructor
The plugin constructor or name.
Returns
InstanceType<TConstructor>
-
has( key ) → boolean
module:core/plugincollection~PluginCollection#has
Checks if a plugin is loaded.
// Check if the 'Clipboard' plugin was loaded. if ( editor.plugins.has( 'ClipboardPipeline' ) ) { // Now use the clipboard plugin instance: const clipboard = editor.plugins.get( 'ClipboardPipeline' ); // ... }
Parameters
key : string | PluginConstructor<TContext>
The plugin constructor or name.
Returns
boolean
-
init( plugins, pluginsToRemove, pluginsSubstitutions ) → Promise<LoadedPlugins>
module:core/plugincollection~PluginCollection#init
Initializes a set of plugins and adds them to the collection.
Parameters
plugins : readonly Array<string | PluginConstructor<TContext>>
An array of plugin constructors or plugin names.
pluginsToRemove : readonly Array<string | PluginConstructor<TContext>>
Names of the plugins or plugin constructors that should not be loaded (despite being specified in the
plugins
array).Defaults to
[]
pluginsSubstitutions : readonly Array<PluginConstructor<TContext>>
An array of plugin constructors that will be used to replace plugins of the same names that were passed in
plugins
or that are in their dependency tree. A useful option for replacing built-in plugins while creating tests (for mocking their APIs). Plugins that will be replaced must follow these rules:- The new plugin must be a class.
- The new plugin must be named.
- Both plugins must not depend on other plugins.
Defaults to
[]
Returns
Promise<LoadedPlugins>
A promise which gets resolved once all plugins are loaded and available in the collection.
-
inherited
listenTo( emitter, event, callback, [ options ] ) → void
module:core/plugincollection~PluginCollection#listenTo:BASE_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using
:
. When namespaced event is fired, it additionally fires all callbacks for that namespace.// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ). myEmitter.on( 'myGroup', genericCallback ); myEmitter.on( 'myGroup:myEvent', specificCallback ); // genericCallback is fired. myEmitter.fire( 'myGroup' ); // both genericCallback and specificCallback are fired. myEmitter.fire( 'myGroup:myEvent' ); // genericCallback is fired even though there are no callbacks for "foo". myEmitter.fire( 'myGroup:foo' );
An event callback can stop the event and set the return value of the
fire
method.Type parameters
Parameters
emitter : Emitter
The object that fires the event.
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
Stops executing the callback on the given event. Shorthand for
this.stopListening( this, event, callback )
.Parameters
event : string
The name of the event.
callback : Function
The function to stop being called.
Returns
void
-
Registers a callback function to be executed when an event is fired.
Shorthand for
this.listenTo( this, event, callback, options )
(it makes the emitter listen on itself).Type parameters
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
inherited
once( event, callback, [ options ] ) → void
module:core/plugincollection~PluginCollection#once
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling
on
followed byoff
in the callback.Type parameters
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
inherited
stopDelegating( [ event ], [ emitter ] ) → void
module:core/plugincollection~PluginCollection#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
Parameters
[ event ] : string
The name of the event to stop delegating. If omitted, stops it all delegations.
[ emitter ] : Emitter
(requires
event
) The object to stop delegating a particular event to. If omitted, stops delegation ofevent
to all emitters.
Returns
void
-
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → void
module:core/plugincollection~PluginCollection#stopListening:BASE_STOP
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
Parameters
[ emitter ] : Emitter
The object to stop listening to. If omitted, stops it for all objects.
[ event ] : string
(Requires the
emitter
) The name of the event to stop listening to. If omitted, stops it for all events fromemitter
.[ callback ] : Function
(Requires the
event
) The function to be removed from the call list for the givenevent
.
Returns
void
-
Adds the plugin to the collection. Exposed mainly for testing purposes.
Parameters
PluginConstructor : PluginConstructor<TContext>
The plugin constructor.
plugin : PluginInterface
The instance of the plugin.
Returns
void
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.