Creates a new instance of the module:ui/editorui/bodycollection~BodyCollection.
The module:core/editor/editor~Editor editor's locale instance.
OptionalinitialItems: Iterable<View<HTMLElement>>The initial items of the collection.
OptionalidReadonlylocaleThe module:core/editor/editor~Editor#locale editor's locale instance. See the view module:ui/view~View#locale locale property.
The element holding elements of the body collection.
Returns the first item from the collection or null when collection is empty.
Returns the last item from the collection or null when collection is empty.
The number of items available in the collection.
Iterable interface.
Adds an item into the collection.
If the item does not have an id, then it will be automatically generated and set on the item.
Optionalindex: numberThe position of the item in the collection. The item
is pushed to the collection when index not specified.
Adds multiple items into the collection.
Any item not containing an id will get an automatically generated one.
Optionalindex: numberThe position of the insertion. Items will be appended if no index is specified.
Attaches the body collection to the DOM body element. You need to execute this method to render the content of the body collection.
Binds and synchronizes the collection with another one.
The binding can be a simple factory:
class FactoryClass {
public label: string;
constructor( data: { label: string } ) {
this.label = data.label;
}
}
const source = new Collection<{ label: string }>( { idProperty: 'label' } );
const target = new Collection<FactoryClass>();
target.bindTo( source ).as( FactoryClass );
source.add( { label: 'foo' } );
source.add( { label: 'bar' } );
console.log( target.length ); // 2
console.log( target.get( 1 ).label ); // 'bar'
source.remove( 0 );
console.log( target.length ); // 1
console.log( target.get( 0 ).label ); // 'bar'
or the factory driven by a custom callback:
class FooClass {
public label: string;
constructor( data: { label: string } ) {
this.label = data.label;
}
}
class BarClass {
public label: string;
constructor( data: { label: string } ) {
this.label = data.label;
}
}
const source = new Collection<{ label: string }>( { idProperty: 'label' } );
const target = new Collection<FooClass | BarClass>();
target.bindTo( source ).using( ( item ) => {
if ( item.label == 'foo' ) {
return new FooClass( item );
} else {
return new BarClass( item );
}
} );
source.add( { label: 'foo' } );
source.add( { label: 'bar' } );
console.log( target.length ); // 2
console.log( target.get( 0 ) instanceof FooClass ); // true
console.log( target.get( 1 ) instanceof BarClass ); // true
or the factory out of property name:
const source = new Collection<{ nested: { value: string } }>();
const target = new Collection<{ value: string }>();
target.bindTo( source ).using( 'nested' );
source.add( { nested: { value: 'foo' } } );
source.add( { nested: { value: 'bar' } } );
console.log( target.length ); // 2
console.log( target.get( 0 ).value ); // 'foo'
console.log( target.get( 1 ).value ); // 'bar'
It's possible to skip specified items by returning null value:
const source = new Collection<{ hidden: boolean }>();
const target = new Collection<{ hidden: boolean }>();
target.bindTo( source ).using( item => {
if ( item.hidden ) {
return null;
}
return item;
} );
source.add( { hidden: true } );
source.add( { hidden: false } );
console.log( source.length ); // 2
console.log( target.length ); // 1
Note: #clear can be used to break the binding.
The type of externalCollection element.
A collection to be bound.
The binding chain object.
Delegates selected events coming from within views in the collection to any module:utils/emittermixin~Emitter.
For the following views and collection:
const viewA = new View();
const viewB = new View();
const viewC = new View();
const views = parentView.createCollection();
views.delegate( 'eventX' ).to( viewB );
views.delegate( 'eventX', 'eventY' ).to( viewC );
views.add( viewA );
the eventX is delegated (fired by) viewB and viewC along with customData:
viewA.fire( 'eventX', customData );
and eventY is delegated (fired by) viewC along with customData:
viewA.fire( 'eventY', customData );
See module:utils/emittermixin~Emitter#delegate.
module:ui/view~View event names to be delegated to another module:utils/emittermixin~Emitter.
Object with to property, a function which accepts the destination
of module:utils/emittermixin~Emitter#delegate delegated events.
Destroys the view collection along with child views. See the view module:ui/view~View#destroy method.
Detaches the collection from the DOM structure. Use this method when you do not need to use the body collection anymore to clean-up the DOM structure.
Returns an array with items for which the callback returned a true value.
Optionalctx: anyContext in which the callback will be called.
The array with matching items.
Finds the first item in the collection for which the callback returns a true value.
Optionalctx: anyContext in which the callback will be called.
The item for which callback returned a true value.
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an module:utils/eventinfo~EventInfo object,
followed by the optional args provided in the fire() method call.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The name of the event or EventInfo object if event is delegated.
Additional arguments to be passed to the callbacks.
By default the method returns undefined. However, the return value can be changed by listeners
through modification of the module:utils/eventinfo~EventInfo#return evt.return's property (the event info
is the first param of every callback).
Performs the specified action for each item in the collection.
Optionalctx: anyContext in which the callback will be called.
Gets an item by its ID or index.
The item ID or index in the collection.
The requested item or null if such item does not exist.
Gets an index of an item in the collection. When an item is not defined in the collection, the index will equal -1.
The item or its ID in the collection.
The index of a given item.
Returns a Boolean indicating whether the collection contains an item.
The item or its ID in the collection.
true if the collection contains the item, false otherwise.
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 module:utils/eventinfo~EventInfo#stop stop the event and set the module:utils/eventinfo~EventInfo#return return value of the #fire method.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The object that fires the event.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Executes the callback for each item in the collection and composes an array or values returned by this callback.
The result type of the callback.
The result of mapping.
Stops executing the callback on the given event.
Shorthand for #stopListening this.stopListening( this, event, callback ).
The name of the event.
The function to stop being called.
Registers a callback function to be executed when an event is fired.
Shorthand for #listenTo this.listenTo( this, event, callback, options ) (it makes the emitter
listen on itself).
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling #on followed by #off in the callback.
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Removes a child view from the collection. If the #setParent parent element of the collection has been set, the module:ui/view~View#element element of the view is also removed in DOM, reflecting the order of the collection.
See the #add method.
The view to remove, its id or index in the collection.
The removed view.
Sets the parent HTML element of this collection. When parent is set, #add adding and #remove removing views in the collection synchronizes their module:ui/view~View#element elements in the parent element.
A new parent element or document fragment.
Stops delegating events. It can be used at different levels:
Optionalevent: stringThe name of the event to stop delegating. If omitted, stops it all delegations.
Optionalemitter: Emitter(requires event) The object to stop delegating a particular event to.
If omitted, stops delegation of event to all emitters.
Stops listening for events. It can be used at different levels:
Optionalemitter: EmitterThe object to stop listening to. If omitted, stops it for all objects.
Optionalevent: string(Requires the emitter) The name of the event to stop listening to. If omitted, stops it
for all events from emitter.
Optionalcallback: Function(Requires the event) The function to be removed from the call list for the given
event.
This is a special module:ui/viewcollection~ViewCollection dedicated to elements that are detached from the DOM structure of the editor, like floating panels, floating toolbars, dialogs, etc.
The body collection is available under the module:ui/editorui/editoruiview~EditorUIView#body
editor.ui.view.bodyproperty. Any plugin can add a module:ui/view~View view to this collection.All views added to a body collection render in a dedicated DOM container (
<div class="ck ck-body ...">...</div>). All body collection containers render in a common shared (<div class="ck-body-wrapper">...</div>) in the DOM to limit the pollution of the<body>element. The resulting DOM structure is as follows:By default, the module:ui/editorui/editoruiview~EditorUIView
editor.ui.viewmanages the life cycle of the module:ui/editorui/editoruiview~EditorUIView#bodyeditor.ui.view.bodycollection, attaching and detaching it when the editor gets created or module:core/editor/editor~Editor#destroy destroyed.Custom body collection instances
Even though most editor instances come with a built-in body collection (module:ui/editorui/editoruiview~EditorUIView#body
editor.ui.view.body), you can create your own instance of this class if you need to control their life cycle.The life cycle of a custom body collection must be handled manually by the developer using the dedicated API:
Note: The shared collection wrapper (
<div class="ck-body-wrapper">...</div>) gets automatically removed from DOM when the last body collection is ~BodyCollection#detachFromDom detached and does not require any special handling.