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
Properties
-
first
module:ui/viewcollection~ViewCollection#first
inherited
Returns the first item from the collection or null when collection is empty.
-
last
module:ui/viewcollection~ViewCollection#last
inherited
Returns the last item from the collection or null when collection is empty.
-
length : Number
module:ui/viewcollection~ViewCollection#length
inherited
The number of items available in the collection.
-
_bindToCollection : Collection
module:ui/viewcollection~ViewCollection#_bindToCollection
protected inherited
A collection instance this collection is bound to as a result of calling
bindTo
method. -
_bindToExternalToInternalMap : WeakMap
module:ui/viewcollection~ViewCollection#_bindToExternalToInternalMap
protected inherited
A helper mapping external items of a bound collection (
bindTo
) and actual items of this collection. It provides information necessary to properly remove items bound to another collection. -
_bindToInternalToExternalMap : WeakMap
module:ui/viewcollection~ViewCollection#_bindToInternalToExternalMap
protected inherited
A helper mapping items of this collection to external items of a bound collection (
bindTo
). It provides information necessary to manage the bindings, e.g. to avoid loops in two–way bindings. -
_parentElement : HTMLElement
module:ui/viewcollection~ViewCollection#_parentElement
protected
A parent element within which child views are rendered and managed in DOM.
-
_idProperty : String
module:ui/viewcollection~ViewCollection#_idProperty
private inherited
The name of the property which is considered to identify an item.
-
_itemMap : Map
module:ui/viewcollection~ViewCollection#_itemMap
private inherited
The internal map of items in the collection.
-
_items : Array.<Object>
module:ui/viewcollection~ViewCollection#_items
private inherited
The internal list of items in the collection.
-
_skippedIndexesFromExternal : Array
module:ui/viewcollection~ViewCollection#_skippedIndexesFromExternal
private inherited
Stores indexes of skipped items from bound external collection.
Methods
-
constructor( [ initialItems ] )
module:ui/viewcollection~ViewCollection#constructor
Creates a new instance of the
ViewCollection
.Parameters
[ initialItems ] : Iterable.<View>
The initial items of the collection.
-
Symbol.iterator() → Iterable.<*>
module:ui/viewcollection~ViewCollection.iterator
inherited
Iterable interface.
Returns
Iterable.<*>
-
add( item, [ index ] )
module:ui/viewcollection~ViewCollection#add
inherited
Adds an item into the collection.
-
addMany( item, [ index ] )
module:ui/viewcollection~ViewCollection#addMany
inherited
Adds multiple items into the collection.
-
bind( bindProperties ) → Object
module:ui/viewcollection~ViewCollection#bind
mixed
Binds observable properties to other objects implementing the
Observable
interface.Read more in the dedicated guide covering the topic of property bindings with some additional examples.
Consider two objects: a
button
and an associatedcommand
(bothObservable
).A simple property binding could be as follows:
button.bind( 'isEnabled' ).to( command, 'isEnabled' );
or even shorter:
button.bind( 'isEnabled' ).to( command );
which works in the following way:
button.isEnabled
instantly equalscommand.isEnabled
,- whenever
command.isEnabled
changes,button.isEnabled
will immediately reflect its value.
Note: To release the binding, use
unbind
.You can also "rename" the property in the binding by specifying the new name in the
to()
chain:button.bind( 'isEnabled' ).to( command, 'isWorking' );
It is possible to bind more than one property at a time to shorten the code:
button.bind( 'isEnabled', 'value' ).to( command );
which corresponds to:
button.bind( 'isEnabled' ).to( command ); button.bind( 'value' ).to( command );
The binding can include more than one observable, combining multiple data sources in a custom callback:
button.bind( 'isEnabled' ).to( command, 'isEnabled', ui, 'isVisible', ( isCommandEnabled, isUIVisible ) => isCommandEnabled && isUIVisible );
Using a custom callback allows processing the value before passing it to the target property:
button.bind( 'isEnabled' ).to( command, 'value', value => value === 'heading1' );
It is also possible to bind to the same property in an array of observables. To bind a
button
to multiple commands (alsoObservables
) so that each and every one of them must be enabled for the button to become enabled, use the following code:button.bind( 'isEnabled' ).toMany( [ commandA, commandB, commandC ], 'isEnabled', ( isAEnabled, isBEnabled, isCEnabled ) => isAEnabled && isBEnabled && isCEnabled );
Parameters
bindProperties : String
Observable properties that will be bound to other observable(s).
Returns
Object
The bind chain with the
to()
andtoMany()
methods.
-
bindTo( externalCollection ) → Object
module:ui/viewcollection~ViewCollection#bindTo
inherited
Binds and synchronizes the collection with another one.
The binding can be a simple factory:
class FactoryClass { constructor( data ) { this.label = data.label; } } const source = new Collection( { idProperty: 'label' } ); const target = new Collection(); 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 { constructor( data ) { this.label = data.label; } } class BarClass { constructor( data ) { this.label = data.label; } } const source = new Collection( { idProperty: 'label' } ); const target = new Collection(); 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( { idProperty: 'label' } ); const target = new Collection(); target.bindTo( source ).using( 'label' ); source.add( { label: { value: 'foo' } } ); source.add( { label: { 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 falsy value:
const source = new Collection(); const target = new Collection(); 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.Parameters
externalCollection : Collection
A collection to be bound.
Returns
Object
CollectionBindToChain
The binding chain object.
-
clear()
module:ui/viewcollection~ViewCollection#clear
inherited
Removes all items from the collection and destroys the binding created using
bindTo
. -
decorate( methodName )
module:ui/viewcollection~ViewCollection#decorate
mixed
Turns the given methods of this object into event-based ones. This means that the new method will fire an event (named after the method) and the original action will be plugged as a listener to that event.
Read more in the dedicated guide covering the topic of decorating methods with some additional examples.
Decorating the method does not change its behavior (it only adds an event), but it allows to modify it later on by listening to the method's event.
For example, to cancel the method execution the event can be stopped:
class Foo { constructor() { this.decorate( 'method' ); } method() { console.log( 'called!' ); } } const foo = new Foo(); foo.on( 'method', ( evt ) => { evt.stop(); }, { priority: 'high' } ); foo.method(); // Nothing is logged.
Note: The high priority listener has been used to execute this particular callback before the one which calls the original method (which uses the "normal" priority).
It is also possible to change the returned value:
foo.on( 'method', ( evt ) => { evt.return = 'Foo!'; } ); foo.method(); // -> 'Foo'
Finally, it is possible to access and modify the arguments the method is called with:
method( a, b ) { console.log( `${ a }, ${ b }` ); } // ... foo.on( 'method', ( evt, args ) => { args[ 0 ] = 3; console.log( args[ 1 ] ); // -> 2 }, { priority: 'high' } ); foo.method( 1, 2 ); // -> '3, 2'
Parameters
methodName : String
Name of the method to decorate.
-
delegate( events ) → Object
module:ui/viewcollection~ViewCollection#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 );
the
eventX
is delegated (fired by)viewB
andviewC
along withcustomData
:viewA.fire( 'eventX', customData );
and
eventY
is delegated (fired by)viewC
along withcustomData
:viewA.fire( 'eventY', customData );
See
delegate
.Parameters
Returns
Object
function
return.to A function which accepts the destination of delegated events.
-
destroy()
module:ui/viewcollection~ViewCollection#destroy
Destroys the view collection along with child views. See the view
destroy
method. -
filter( callback, callback.item, callback.index, ctx ) → Array.<Object>
module:ui/viewcollection~ViewCollection#filter
inherited
Returns an array with items for which the
callback
returned a true value.Parameters
callback : function
callback.item : Object
callback.index : Number
ctx : Object
Context in which the
callback
will be called.
Returns
Array.<Object>
The array with matching items.
-
find( callback, callback.item, callback.index, ctx ) → Object
module:ui/viewcollection~ViewCollection#find
inherited
Finds the first item in the collection for which the
callback
returns a true value.Parameters
callback : function
callback.item : Object
callback.index : Number
ctx : Object
Context in which the
callback
will be called.
Returns
Object
The item for which
callback
returned a true value.
-
fire( eventOrInfo, [ args ] ) → *
module:ui/viewcollection~ViewCollection#fire
mixed
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfo
object, followed by the optionalargs
provided in thefire()
method call.Parameters
eventOrInfo : String | EventInfo
The name of the event or
EventInfo
object if event is delegated.[ args ] : *
Additional arguments to be passed to the callbacks.
Returns
*
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).
-
get( idOrIndex ) → Object | null
module:ui/viewcollection~ViewCollection#get
inherited
Gets an item by its ID or index.
Parameters
idOrIndex : String | Number
The item ID or index in the collection.
Returns
Object | null
The requested item or
null
if such item does not exist.
-
getIndex( itemOrId ) → Number
module:ui/viewcollection~ViewCollection#getIndex
inherited
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 : Object | String
The item or its ID in the collection.
Returns
Number
The index of a given item.
-
has( itemOrId ) → Boolean
module:ui/viewcollection~ViewCollection#has
inherited
Returns a Boolean indicating whether the collection contains an item.
Parameters
itemOrId : Object | String
The item or its ID in the collection.
Returns
Boolean
true
if the collection contains the item,false
otherwise.
-
listenTo( emitter, event, callback, [ options ] = { [options.priority] } )
module:ui/viewcollection~ViewCollection#listenTo
mixed
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' );
An event callback can stop the event and set the return value of the
fire
method.Parameters
emitter : Emitter
The object that fires the event.
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
map( callback, callback.item, callback.index, ctx ) → Array
module:ui/viewcollection~ViewCollection#map
inherited
Executes the callback for each item in the collection and composes an array or values returned by this callback.
Parameters
callback : function
callback.item : Object
callback.index : Number
ctx : Object
Context in which the
callback
will be called.
Returns
Array
The result of mapping.
-
off( event, callback )
module:ui/viewcollection~ViewCollection#off
mixed
Stops executing the callback on the given event. Shorthand for
this.stopListening( this, event, callback )
.Parameters
event : String
The name of the event.
callback : function
The function to stop being called.
-
on( event, callback, [ options ] = { [options.priority] } )
module:ui/viewcollection~ViewCollection#on
mixed
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).Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
once( event, callback, [ options ] = { [options.priority] } )
module:ui/viewcollection~ViewCollection#once
mixed
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling
on
followed byoff
in the callback.Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
remove( subject ) → Object
module:ui/viewcollection~ViewCollection#remove
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.
-
set( name, [ value ] )
module:ui/viewcollection~ViewCollection#set
mixed
Creates and sets the value of an observable property of this object. Such a property becomes a part of the state and is observable.
It accepts also a single object literal containing key/value pairs with properties to be set.
This method throws the
observable-set-cannot-override
error if the observable instance already has a property with the given property name. This prevents from mistakenly overriding existing properties and methods, but means thatfoo.set( 'bar', 1 )
may be slightly slower thanfoo.bar = 1
.Parameters
name : String | Object
The property's name or object with
name=>value
pairs.[ value ] : *
The property's value (if
name
was passed in the first parameter).
-
setParent( element )
module:ui/viewcollection~ViewCollection#setParent
-
stopDelegating( [ event ], [ emitter ] )
module:ui/viewcollection~ViewCollection#stopDelegating
mixed
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.
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 ofevent
to all emitters.
-
stopListening( [ emitter ], [ event ], [ callback ] )
module:ui/viewcollection~ViewCollection#stopListening
mixed
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.
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 fromemitter
.[ callback ] : function
(Requires the
event
) The function to be removed from the call list for the givenevent
.
-
unbind( [ unbindProperties ] )
module:ui/viewcollection~ViewCollection#unbind
mixed
Removes the binding created with
bind
.// Removes the binding for the 'a' property. A.unbind( 'a' ); // Removes bindings for all properties. A.unbind();
Parameters
[ unbindProperties ] : String
Observable properties to be unbound. All the bindings will be released if no properties are provided.
-
_addEventListener( event, callback, [ options ] = { [options.priority] } )
module:ui/viewcollection~ViewCollection#_addEventListener
protected mixed
Adds callback to emitter for given event.
Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
_removeEventListener( event, callback )
module:ui/viewcollection~ViewCollection#_removeEventListener
protected mixed
Removes callback from emitter for given event.
Parameters
event : String
The name of the event.
callback : function
The function to stop being called.
-
_setUpBindToBinding( factory )
module:ui/viewcollection~ViewCollection#_setUpBindToBinding
protected inherited
Finalizes and activates a binding initiated by {#bindTo}.
Parameters
factory : function
A function which produces collection items.
-
_getItemIdBeforeAdding( item ) → String
module:ui/viewcollection~ViewCollection#_getItemIdBeforeAdding
private inherited
Returns an unique id property for a given
item
.The method will generate new id and assign it to the
item
if it doesn't have any.Parameters
item : Object
Item to be added.
Returns
String
-
_remove( subject ) → Array
module:ui/viewcollection~ViewCollection#_remove
private inherited
Core
remove
method implementation shared in other functions.In contrast this method does not fire the
event-change
event.Parameters
subject : Object
The item to remove, its id or index in the collection.
Returns
Array
Returns an array with the removed item and its index.
Fires
-
_renderViewIntoCollectionParent( view, [ index ] )
module:ui/viewcollection~ViewCollection#_renderViewIntoCollectionParent
private
This 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
element
as 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
A new view added to the collection.
[ index ] : Number
An index the view holds in the collection. When not specified, the view is added at the end.
Events
-
add( eventInfo, item )
module:ui/viewcollection~ViewCollection#event:add
inherited
Fired when an item is added to the collection.
Parameters
eventInfo : EventInfo
An object containing information about the fired event.
item : Object
The added item.
-
change( eventInfo, added, removed, index )
module:ui/viewcollection~ViewCollection#event:change
inherited
Fired when the collection was changed due to adding or removing items.
Parameters
eventInfo : EventInfo
An object containing information about the fired event.
added : Iterable.<Object>
A list of added items.
removed : Iterable.<Object>
A list of removed items.
index : Number
An index where the addition or removal occurred.
-
change:{property}( eventInfo, name, value, oldValue )
module:ui/viewcollection~ViewCollection#event:change:{property}
mixed
Fired when a property changed value.
observable.set( 'prop', 1 ); observable.on( 'change:prop', ( evt, propertyName, newValue, oldValue ) => { console.log( `${ propertyName } has changed from ${ oldValue } to ${ newValue }` ); } ); observable.prop = 2; // -> 'prop has changed from 1 to 2'
Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : String
The property name.
value : *
The new property value.
oldValue : *
The previous property value.
-
remove( eventInfo, item, index )
module:ui/viewcollection~ViewCollection#event:remove
inherited
Fired when an item is removed from the collection.
Parameters
eventInfo : EventInfo
An object containing information about the fired event.
item : Object
The removed item.
index : Number
Index from which item was removed.
-
set:{property}( eventInfo, name, value, oldValue )
module:ui/viewcollection~ViewCollection#event:set:{property}
mixed
Fired when a property value is going to be set but is not set yet (before the
change
event is fired).You can control the final value of the property by using the event's
return
property.observable.set( 'prop', 1 ); observable.on( 'set:prop', ( evt, propertyName, newValue, oldValue ) => { console.log( `Value is going to be changed from ${ oldValue } to ${ newValue }` ); console.log( `Current property value is ${ observable[ propertyName ] }` ); // Let's override the value. evt.return = 3; } ); observable.on( 'change:prop', ( evt, propertyName, newValue, oldValue ) => { console.log( `Value has changed from ${ oldValue } to ${ newValue }` ); } ); observable.prop = 2; // -> 'Value is going to be changed from 1 to 2' // -> 'Current property value is 1' // -> 'Value has changed from 1 to 3'
Note: The event is fired even when the new value is the same as the old value.
Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : String
The property name.
value : *
The new property value.
oldValue : *
The previous property value.
Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.