BodyCollection

class

This is a special 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 editor.ui.view.body property. Any plugin can add a 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:

<body>
	<!-- Content of the webpage... -->

	<!-- The shared wrapper for all body collection containers. -->
	<div class="ck-body-wrapper">
		<!-- The container of the first body collection instance. -->
		<div class="ck ck-body ...">
			<!-- View elements belonging to the first body collection -->
		</div>

		<!-- The container of the second body collection instance. -->
		<div class="ck ck-body ...">...</div>

		<!-- More body collection containers for the rest of instances... -->
	</div>
</body>

By default, the editor.ui.view manages the life cycle of the editor.ui.view.body collection, attaching and detaching it when the editor gets created or destroyed.

Custom body collection instances

Even though most editor instances come with a built-in body collection (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:

A body collection will render itself automatically in the DOM as soon as you call attachToDom.
Calling detachFromDom will remove the collection from the DOM.

Note: The shared collection wrapper (<div class="ck-body-wrapper">...</div>) gets automatically removed from DOM when the last body collection is detached and does not require any special handling.

See source

Properties

Methods

constructor( locale, initialItems )

Creates a new instance of the BodyCollection.
See source (with github icon)
Parameters
locale : Locale
The editor's locale instance.
initialItems : Iterable<View<HTMLElement>>
The initial items of the collection.

Defaults to []
Symbol.iterator() → Iterator<View<HTMLElement>>
inherited

Iterable interface.
See source (with github icon)
Returns
Iterator<View<HTMLElement>>
add( item, [ index ] ) → this
inherited
module:ui/editorui/bodycollection~BodyCollection#add
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.
See source (with github icon)
Parameters
item : View
[ index ] : number
The position of the item in the collection. The item is pushed to the collection when index not specified.
Returns
this
Fires
- add
- change
addMany( items, [ index ] ) → this
inherited
module:ui/editorui/bodycollection~BodyCollection#addMany
Adds multiple items into the collection.
Any item not containing an id will get an automatically generated one.
See source (with github icon)
Parameters
items : Iterable<View<HTMLElement>>
[ index ] : number
The position of the insertion. Items will be appended if no index is specified.
Returns
this
Fires
- add
- change
attachToDom() → void

Attaches the body collection to the DOM body element. You need to execute this method to render the content of the body collection.
See source (with github icon)
Returns
void

`bindTo( externalCollection ) → CollectionBindToChain<S, View<HTMLElement>>`
inherited

module:ui/editorui/bodycollection~BodyCollection#bindTo

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.

See source

Type parameters

S : extends Record<string, any>: The type of externalCollection element.

Parameters

externalCollection : Collection<S>: A collection to be bound.

Returns

CollectionBindToChain<S, View<HTMLElement>>: The binding chain object.

clear() → void
inherited
module:ui/editorui/bodycollection~BodyCollection#clear
Removes all items from the collection and destroys the binding created using bindTo.
See source (with github icon)
Returns
void
Fires
- remove
- change
delegate( events ) → EmitterMixinDelegateChain
inherited
module:ui/editorui/bodycollection~BodyCollection#delegate
Delegates selected events coming from within views in the collection to any 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 );
```
Copy code
the eventX is delegated (fired by) viewB and viewC along with customData:
```
viewA.fire( 'eventX', customData );
```
Copy code
and eventY is delegated (fired by) viewC along with customData:
```
viewA.fire( 'eventY', customData );
```
Copy code
See delegate.
See source (with github icon)
Parameters
events : Array<string>
View event names to be delegated to another Emitter.
Returns
EmitterMixinDelegateChain
Object with to property, a function which accepts the destination of delegated events.
destroy() → void
inherited

Destroys the view collection along with child views. See the view destroy method.
See source (with github icon)
Returns
void
detachFromDom() → void

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.
See source (with github icon)
Returns
void
filter( callback, [ ctx ] ) → Array<View<HTMLElement>>
inherited

Returns an array with items for which the callback returned a true value.
See source (with github icon)
Parameters
callback : ( item: View, index: number ) => boolean
[ ctx ] : any
Context in which the callback will be called.
Returns
Array<View<HTMLElement>>
The array with matching items.
find( callback, [ ctx ] ) → undefined | View<HTMLElement>
inherited

Finds the first item in the collection for which the callback returns a true value.
See source (with github icon)
Parameters
callback : ( item: View, index: number ) => boolean
[ ctx ] : any
Context in which the callback will be called.
Returns
undefined | View<HTMLElement>
The item for which callback returned a true value.
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
inherited

Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
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 the evt.return's property (the event info is the first param of every callback).
forEach( callback, [ ctx ] ) → void
inherited

Performs the specified action for each item in the collection.
See source (with github icon)
Parameters
callback : ( item: View, index: number ) => unknown
[ ctx ] : any
Context in which the callback will be called.
Returns
void
get( idOrIndex ) → null | View<HTMLElement>
inherited

Gets an item by its ID or index.
See source (with github icon)
Parameters
idOrIndex : string | number
The item ID or index in the collection.
Returns
null | View<HTMLElement>
The requested item or null if such item does not exist.
getIndex( itemOrId ) → number
inherited

Gets an index of an item in the collection. When an item is not defined in the collection, the index will equal -1.
See source (with github icon)
Parameters
itemOrId : string | View<HTMLElement>
The item or its ID in the collection.
Returns
number
The index of a given item.
has( itemOrId ) → boolean
inherited

Returns a Boolean indicating whether the collection contains an item.
See source (with github icon)
Parameters
itemOrId : string | View<HTMLElement>
The item or its ID in the collection.
Returns
boolean
true if the collection contains the item, false otherwise.
listenTo( emitter, event, callback, [ options ] ) → void
inherited
module:ui/editorui/bodycollection~BodyCollection#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' );
```
Copy code
An event callback can stop the event and set the return value of the fire method.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
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
map( callback, [ ctx ] ) → Array<U>
inherited

Executes the callback for each item in the collection and composes an array or values returned by this callback.
See source (with github icon)
Type parameters
U
The result type of the callback.
Parameters
callback : ( item: View, index: number ) => U
[ ctx ] : any
Context in which the callback will be called.
Returns
Array<U>
The result of mapping.
off( event, callback ) → void
inherited

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).
See source (with github icon)
Parameters
event : string
The name of the event.
callback : Function
The function to stop being called.
Returns
void
on( event, callback, [ options ] ) → void
inherited

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).
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
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
once( event, callback, [ options ] ) → void
inherited

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.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
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
remove( subject ) → View
inherited

Removes a child view from the collection. If the parent element of the collection has been set, the element of the view is also removed in DOM, reflecting the order of the collection.
See the add method.
See source (with github icon)
Parameters
subject : string | number | View<HTMLElement>
The view to remove, its id or index in the collection.
Returns
View
The removed view.
setParent( elementOrDocFragment ) → void
inherited

Sets the parent HTML element of this collection. When parent is set, adding and removing views in the collection synchronizes their elements in the parent element.
See source (with github icon)
Parameters
elementOrDocFragment : HTMLElement | DocumentFragment
A new parent element or document fragment.
Returns
void
stopDelegating( [ event ], [ emitter ] ) → void
inherited
module:ui/editorui/bodycollection~BodyCollection#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.
See source (with github icon)
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 of event to all emitters.
Returns
void
stopListening( [ emitter ], [ event ], [ callback ] ) → void
inherited
module:ui/editorui/bodycollection~BodyCollection#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.
See source (with github icon)
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 from emitter.
[ callback ] : Function
(Requires the event) The function to be removed from the call list for the given event.
Returns
void

BodyCollection

Custom body collection instances

Properties

bodyCollectionContainer : undefined | HTMLElementreadonly

first : null | Treadonlyinherited

id : string | undefinedinherited

last : null | Treadonlyinherited

length : numberreadonlyinherited

locale : Localereadonly

_bodyCollectionContainer : HTMLElement | undefined Lock iconprivate

Static properties

_bodyWrapper : HTMLElement | undefined Lock iconprivatestatic

Methods

constructor( locale, initialItems )

Parameters

Symbol.iterator() → Iterator<View<HTMLElement>>inherited

Returns

add( item, [ index ] ) → thisinherited

Parameters

Returns

Fires

addMany( items, [ index ] ) → thisinherited

Parameters

Returns

Fires

attachToDom() → void

Returns

bindTo( externalCollection ) → CollectionBindToChain<S, View<HTMLElement>>inherited

Type parameters

Parameters

Returns

clear() → voidinherited

Returns

Fires

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

destroy() → voidinherited

Returns

detachFromDom() → void

Returns

filter( callback, [ ctx ] ) → Array<View<HTMLElement>>inherited

Parameters

Returns

find( callback, [ ctx ] ) → undefined | View<HTMLElement>inherited

Parameters

Returns

fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]inherited

Type parameters

Parameters

Returns

forEach( callback, [ ctx ] ) → voidinherited

Parameters

Returns

get( idOrIndex ) → null | View<HTMLElement>inherited

Parameters

Returns

getIndex( itemOrId ) → numberinherited

Parameters

Returns

has( itemOrId ) → booleaninherited

Parameters

Returns

listenTo( emitter, event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

map( callback, [ ctx ] ) → Array<U>inherited

Type parameters

Parameters

Returns

off( event, callback ) → voidinherited

Parameters

Returns

on( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

once( event, callback, [ options ] ) → voidinherited

Type parameters

`bodyCollectionContainer : undefined | HTMLElement`
readonly

`first : null | T`
readonlyinherited

`id : string | undefined`
inherited

`last : null | T`
readonlyinherited

`length : number`
readonlyinherited

`locale : Locale`
readonly

`_bodyCollectionContainer : HTMLElement | undefined`
private

`_bodyWrapper : HTMLElement | undefined`
privatestatic

`constructor( locale, initialItems )`

`Symbol.iterator() → Iterator<View<HTMLElement>>`
inherited

`add( item, [ index ] ) → this`
inherited

`addMany( items, [ index ] ) → this`
inherited

`attachToDom() → void`

`bindTo( externalCollection ) → CollectionBindToChain<S, View<HTMLElement>>`
inherited

`clear() → void`
inherited

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`destroy() → void`
inherited

`detachFromDom() → void`

`filter( callback, [ ctx ] ) → Array<View<HTMLElement>>`
inherited

`find( callback, [ ctx ] ) → undefined | View<HTMLElement>`
inherited

`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`
inherited

`forEach( callback, [ ctx ] ) → void`
inherited

`get( idOrIndex ) → null | View<HTMLElement>`
inherited

`getIndex( itemOrId ) → number`
inherited

`has( itemOrId ) → boolean`
inherited

`listenTo( emitter, event, callback, [ options ] ) → void`
inherited

`map( callback, [ ctx ] ) → Array<U>`
inherited

`off( event, callback ) → void`
inherited

`on( event, callback, [ options ] ) → void`
inherited

`once( event, callback, [ options ] ) → void`
inherited

`remove( subject ) → View`
inherited

`setParent( elementOrDocFragment ) → void`
inherited

`stopDelegating( [ event ], [ emitter ] ) → void`
inherited

`stopListening( [ emitter ], [ event ], [ callback ] ) → void`
inherited

`add( eventInfo, item, index )`
inherited

`change( eventInfo, data )`
inherited

`remove( eventInfo, item, index )`
inherited