ViewCollection (ui)
@ckeditor/ckeditor5-ui/src/viewcollection
Collects View instances.
const parentView = new ParentView( locale );
const collection = new ViewCollection( locale );
collection.setParent( parentView.element );
const viewA = new ChildView( locale );
const viewB = new ChildView( locale );
View collection renders and manages view elements:
collection.add( viewA );
collection.add( viewB );
console.log( parentView.element.firsChild ); // -> viewA.element
console.log( parentView.element.lastChild ); // -> viewB.element
It propagates DOM events too:
// Delegate #click and #keydown events from viewA and viewB to the parentView.
collection.delegate( 'click' ).to( parentView );
parentView.on( 'click', ( evt ) => {
console.log( `${ evt.source } has been clicked.` );
} );
// This event will be delegated to the parentView.
viewB.fire( 'click' );
Note: A view collection can be used directly in the definition of a template.
Filtering
Type parameters
-
TView : extends View
Properties
-
Returns the first item from the collection or null when collection is empty.
-
id : string | undefinedmodule:ui/viewcollection~ViewCollection#id -
Returns the last item from the collection or null when collection is empty.
-
The number of items available in the collection.
-
private
_parentElement : null | HTMLElement | DocumentFragmentmodule:ui/viewcollection~ViewCollection#_parentElementA parent element within which child views are rendered and managed in DOM.
Methods
-
constructor( initialItems )module:ui/viewcollection~ViewCollection#constructorCreates a new instance of the
ViewCollection.Type parameters
TView : extends [object Object] = default
Parameters
initialItems : Iterable<TView>The initial items of the collection.
Defaults to
[]
-
inherited
Symbol.iterator() → Iterator<TView, any, undefined>module:ui/viewcollection~ViewCollection#Symbol.iterator -
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.
Parameters
item : TView[ index ] : numberThe position of the item in the collection. The item is pushed to the collection when
indexnot specified.
Returns
ViewCollection<TView>
Fires
-
inherited
addMany( items, [ index ] ) → ViewCollection<TView>module:ui/viewcollection~ViewCollection#addManyAdds multiple items into the collection.
Any item not containing an id will get an automatically generated one.
Parameters
items : Iterable<TView>[ index ] : numberThe position of the insertion. Items will be appended if no
indexis specified.
Returns
ViewCollection<TView>
Fires
-
inherited
bindTo( externalCollection ) → CollectionBindToChain<S, TView>module:ui/viewcollection~ViewCollection#bindToBinds 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 ); // trueor 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 ); // 1Note:
clearcan be used to break the binding.Type parameters
S : extends Record<string, any>The type of
externalCollectionelement.
Parameters
externalCollection : Collection<S>A collection to be bound.
Returns
CollectionBindToChain<S, TView>The binding chain object.
-
Removes all items from the collection and destroys the binding created using
bindTo.Returns
void
Fires
-
delegate( events ) → EmitterMixinDelegateChainmodule:ui/viewcollection~ViewCollection#delegateDelegates 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 );the
eventXis delegated (fired by)viewBandviewCalong withcustomData:viewA.fire( 'eventX', customData );and
eventYis delegated (fired by)viewCalong withcustomData:viewA.fire( 'eventY', customData );See
delegate.Parameters
Returns
EmitterMixinDelegateChainObject with
toproperty, a function which accepts the destination of delegated events.
-
destroy() → voidmodule:ui/viewcollection~ViewCollection#destroy -
Returns an array with items for which the
callbackreturned a true value.Parameters
callback : ( TView, number ) => boolean[ ctx ] : anyContext in which the
callbackwill be called.
Returns
Array<TView>The array with matching items.
-
Finds the first item in the collection for which the
callbackreturns a true value.Parameters
callback : ( TView, number ) => boolean[ ctx ] : anyContext in which the
callbackwill be called.
Returns
undefined | TViewThe item for which
callbackreturned a true value.
-
inherited
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]module:ui/viewcollection~ViewCollection#fireFires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfoobject, followed by the optionalargsprovided in thefire()method call.Type parameters
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>The name of the event or
EventInfoobject 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 theevt.return's property (the event info is the first param of every callback).
-
Performs the specified action for each item in the collection.
Parameters
callback : ( TView, number ) => unknown[ ctx ] : anyContext in which the
callbackwill be called.
Returns
void
-
Gets an item by its ID or index.
Parameters
idOrIndex : string | numberThe item ID or index in the collection.
Returns
null | TViewThe requested item or
nullif 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.
Parameters
itemOrId : string | TViewThe item or its ID in the collection.
Returns
numberThe index of a given item.
-
Returns a Boolean indicating whether the collection contains an item.
Parameters
itemOrId : string | TViewThe item or its ID in the collection.
Returns
booleantrueif the collection contains the item,falseotherwise.
-
inherited
listenTo( emitter, event, callback, [ options ] ) → voidmodule:ui/viewcollection~ViewCollection#listenTo:BASE_EMITTERRegisters 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 stop the event and set the return value of the
firemethod.Type parameters
Parameters
emitter : EmitterThe 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
-
Executes the callback for each item in the collection and composes an array or values returned by this callback.
Type parameters
UThe result type of the callback.
Parameters
callback : ( TView, number ) => U[ ctx ] : anyContext in which the
callbackwill be called.
Returns
Array<U>The result of mapping.
-
Stops executing the callback on the given event. Shorthand for
this.stopListening( this, event, callback ).Parameters
event : stringThe name of the event.
callback : FunctionThe function to stop being called.
Returns
void
-
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).Type parameters
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
-
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling
onfollowed byoffin the callback.Type parameters
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 ) → TViewmodule:ui/viewcollection~ViewCollection#removeRemoves 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
addmethod.Parameters
subject : string | number | TViewThe view to remove, its id or index in the collection.
Returns
TViewThe removed view.
-
setParent( elementOrDocFragment ) → voidmodule:ui/viewcollection~ViewCollection#setParent -
inherited
stopDelegating( [ event ], [ emitter ] ) → voidmodule:ui/viewcollection~ViewCollection#stopDelegatingStops 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.
Parameters
[ event ] : stringThe 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 ofeventto all emitters.
Returns
void
-
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → voidmodule:ui/viewcollection~ViewCollection#stopListening:BASE_STOPStops 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.
Parameters
[ emitter ] : EmitterThe 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 fromemitter.[ callback ] : Function(Requires the
event) The function to be removed from the call list for the givenevent.
Returns
void
-
private
_renderViewIntoCollectionParent( view, [ index ] ) → voidmodule:ui/viewcollection~ViewCollection#_renderViewIntoCollectionParentThis method renders a new view added to the collection.
If the parent element of the collection is set, this method also adds the view's
elementas a child of the parent in DOM at a specified index.Note: If index is not specified, the view's element is pushed as the last child of the parent element.
Parameters
view : View<HTMLElement>A new view added to the collection.
[ index ] : numberAn index the view holds in the collection. When not specified, the view is added at the end.
Returns
void
Events
-
Fired when an item is added to the collection.
Parameters
eventInfo : EventInfoAn object containing information about the fired event.
item : TThe added item.
index : numberAn index where the addition occurred.
-
Fired when the collection was changed due to adding or removing items.
Parameters
eventInfo : EventInfoAn object containing information about the fired event.
data : CollectionChangeEventData<T>Changed items.
-
Fired when an item is removed from the collection.
Parameters
eventInfo : EventInfoAn object containing information about the fired event.
item : TThe removed item.
index : numberIndex from which item was removed.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.