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 destroy will remove the collection from the DOM and destroy its views.

Note: The shared collection wrapper (<div class="ck-body-wrapper">...</div>) gets automatically removed from DOM when the last body collection is destroyed 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( target? ) → void

Attaches the body collection to the DOM. You need to execute this method to render the content of the body collection.
By default the collection mounts in a shared wrapper under the document.body. Pass a target to mount it elsewhere – for example inside the shadow root an editor lives in, so that floating UI (balloons, dialogs, tooltips) can be styled within that boundary. The target may be a regular element or a shadow root, open or closed. Calling this method again with a different target re-mounts the already rendered collection into the new location.
See source (with github icon)
Parameters
target?: ShadowRoot | HTMLElement
The element or shadow root to mount the body collection in. Defaults to document.body.
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

Destroys the body collection: destroys its views and removes their shared container from the DOM. Use this method when you do not need the body collection anymore. For a reversible removal that keeps the views so the collection can be attached again, use unmountFromDom instead.
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? ) → View<HTMLElement> | undefined
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
View<HTMLElement> | undefined
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 ) → View<HTMLElement> | null
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
View<HTMLElement> | null
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: DocumentFragment | HTMLElement
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
syncMountTarget( target ) → void

Keeps the collection mounted in the given target: attaches it there when the target differs from the current mountTarget (see attachToDom), unmounts it on a null target (see unmountFromDom), and leaves the DOM untouched when the collection already sits in the target.
Designed for repeated calls with a freshly resolved target (for example on every editor UI update, or with the result of getOverlayMountRoot), as opposed to attachToDom, which re-appends the container even when the target did not change.
See source (with github icon)
Parameters
target: ShadowRoot | HTMLElement | null
The element or shadow root to mount the body collection in, or null to unmount it.
Returns
void
unmountFromDom() → void

Removes the collection's container from the DOM without destroying its views, so it can be attached again later with attachToDom – for example when the editor is temporarily disconnected from the document. For permanent teardown use destroy instead.
See source (with github icon)
Returns
void
_removeFromDom() → void
private

Removes the collection's container (and the shared wrapper, if now empty) from the DOM, keeping the container instance so it can be re-attached.
See source (with github icon)
Returns
void

Static methods

_getBodyWrapper( mountTarget ) → HTMLElement
privatestatic

Returns the shared wrapper element for the given mount target, creating (and attaching) it if it does not exist yet or is no longer contained by the target. Body collections sharing a target share a wrapper.
The staleness check asks whether the target still contains the wrapper rather than testing isConnected, so a wrapper stays reused when the target itself is legitimately detached from the document (for example a configured ui.overlayContainer that is inserted later). Testing isConnected there would treat the still-attached wrapper as stale and build a duplicate wrapper for every body collection sharing that target.
See source (with github icon)
Parameters
mountTarget: ShadowRoot | HTMLElement
The element or shadow root the wrapper is (or should be) attached to.
Returns
HTMLElement
_removeBodyWrapperIfEmpty( mountTarget? ) → void
privatestatic

Removes the shared wrapper for the given mount target (and forgets it) once it holds no more body collections.
See source (with github icon)
Parameters
mountTarget?: ShadowRoot | HTMLElement
The element or shadow root the wrapper is attached to.
Returns
void

BodyCollection

Custom body collection instances

Properties

bodyCollectionContainer: HTMLElementreadonly

first: T | nullreadonlyinherited

id?: stringinherited

last: T | nullreadonlyinherited

length: numberreadonlyinherited

locale: Localereadonly

mountTarget: ShadowRoot | HTMLElement | undefinedreadonly

_bodyCollectionContainer?: HTMLElement Lock iconprivate

_mountTarget?: ShadowRoot | HTMLElement Lock iconprivate

Static properties

_bodyWrappers: Map<ShadowRoot | HTMLElement, HTMLElement> 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( target? ) → void

Parameters

Returns

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

Type parameters

Parameters

Returns

clear() → voidinherited

Returns

Fires

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

destroy() → void

Returns

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

Parameters

Returns

find( callback, ctx? ) → View<HTMLElement> | undefinedinherited

Parameters

Returns

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

Type parameters

Parameters

Returns

forEach( callback, ctx? ) → voidinherited

Parameters

Returns

get( idOrIndex ) → View<HTMLElement> | nullinherited

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

`bodyCollectionContainer: HTMLElement`
readonly

`first: T | null`
readonlyinherited

`id?: string`
inherited

`last: T | null`
readonlyinherited

`length: number`
readonlyinherited

`locale: Locale`
readonly

`mountTarget: ShadowRoot | HTMLElement | undefined`
readonly

`_bodyCollectionContainer?: HTMLElement`
private

`_mountTarget?: ShadowRoot | HTMLElement`
private

`_bodyWrappers: Map<ShadowRoot | HTMLElement, HTMLElement>`
privatestatic

`constructor( locale, initialItems )`

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

`add( item, index? ) → this`
inherited

`addMany( items, index? ) → this`
inherited

`attachToDom( target? ) → void`

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

`clear() → void`
inherited

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`destroy() → void`

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

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

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

`forEach( callback, ctx? ) → void`
inherited

`get( idOrIndex ) → View<HTMLElement> | null`
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

`syncMountTarget( target ) → void`

`unmountFromDom() → void`

`_removeFromDom() → void`
private

`_getBodyWrapper( mountTarget ) → HTMLElement`
privatestatic

`_removeBodyWrapperIfEmpty( mountTarget? ) → void`
privatestatic

`add( eventInfo, item, index )`
inherited

`change( eventInfo, data )`
inherited

`remount( eventInfo )`

`remove( eventInfo, item, index )`
inherited