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

bodyCollectionContainer : undefined | HTMLElement
readonly

The element holding elements of the body collection.

See source (with github icon)
first : null | T
readonlyinherited

Returns the first item from the collection or null when collection is empty.

See source (with github icon)
id : string | undefined
inherited

See source (with github icon)
last : null | T
readonlyinherited

Returns the last item from the collection or null when collection is empty.

See source (with github icon)
length : number
readonlyinherited

The number of items available in the collection.

See source (with github icon)
locale : Locale
readonly

The editor's locale instance. See the view locale property.

See source (with github icon)
_bodyCollectionContainer : HTMLElement | undefined
private

The element holding elements of the body collection.

See source (with github icon)

Static properties

_bodyWrapper : HTMLElement | undefined
privatestatic

The wrapper element that holds all of the _bodyCollectionContainer elements.

See source (with github icon)

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

Events

add( eventInfo, item, index )
inherited

Fired when an item is added to the collection.

See source (with github icon)

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

item : T

The added item.

index : number

An index where the addition occurred.
change( eventInfo, data )
inherited

Fired when the collection was changed due to adding or removing items.

See source (with github icon)

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

data : CollectionChangeEventData<T>

Changed items.
remove( eventInfo, item, index )
inherited

Fired when an item is removed from the collection.

See source (with github icon)

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

item : T

The removed item.

index : number

Index from which item was removed.

BodyCollection

Custom body collection instances

Properties

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 Lock icon private

Static properties

_bodyWrapper : HTMLElement | undefined Lock icon privatestatic

Methods

constructor( locale, initialItems )

Parameters

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

Returns

add( item, [ index ] ) → this inherited

Parameters

Returns

Fires

addMany( items, [ index ] ) → this inherited

Parameters

Returns

Fires

attachToDom() → void

Returns

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

Type parameters

Parameters

Returns

clear() → void inherited

Returns

Fires

delegate( events ) → EmitterMixinDelegateChain inherited

Parameters

Returns

destroy() → void inherited

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 ] ) → void inherited

Parameters

Returns

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

Parameters

Returns

getIndex( itemOrId ) → number inherited

Parameters

Returns

has( itemOrId ) → boolean inherited

Parameters

Returns

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

Type parameters

Parameters

Returns

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

Type parameters

Parameters

Returns

off( event, callback ) → void inherited

Parameters

Returns

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

Type parameters

Parameters

Returns

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

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