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: number
The 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: number
The 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: any
Context 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: any
Context in which the callback will be called.
The item for which callback returned a true value.
Performs the specified action for each item in the collection.
Optionalctx: any
Context 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.
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.
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.
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.