ViewEditableElement

Set of classes associated with element instance.

Note that this is just an alias for this._attrs.get( 'class' );

Normalized styles.

Note that this is just an alias for this._attrs.get( 'style' );

Number of element's children.

The document instance to which this node belongs.

Index of the node in the parent element or null if the node has no parent.

Accessing this property throws an error if this node's parent element does not contain it. This means that view tree got broken.

Is true if there are no nodes inside this element, false otherwise.

Whether the editable is focused.

This property updates when document.isFocused or view selection is changed.

Whether the editable is in read-write or read-only mode.

Name of the element.

Node's next sibling, or null if it is the last child.

Parent element. Null by default. Set by _insertChild.

Placeholder of editable element.

editor.editing.view.document.getRoot( 'main' ).placeholder = 'New placeholder';

Node's previous sibling, or null if it is the first child.

Top-most ancestor of the node. If the node has no parent it is the root itself.

A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms implemented in the ViewDomConverter (for instance, shouldRenderAttribute) would filter them out.

These attributes can be specified as an option when the element is created by the ViewDowncastWriter. To check whether an unsafe an attribute should be permitted, use the shouldRenderUnsafeAttribute method.

Creates an editable element.

Parameters

document : ViewDocument

The document instance to which this element belongs.

name : string

Node name.

[ attributes ] : ViewElementAttributes

Collection of attributes.

[ children ] : ViewNode | Iterable<ViewNode>

A list of nodes to be inserted into created element.

Related:

• ViewDowncastWriter#createEditableElement

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 associated command (both Observable).

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 equals command.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 (also Observables) 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 );

Type parameters

K1

K2

Parameters

bindProperty1 : K1

Observable property that will be bound to other observable(s).

bindProperty2 : K2

Observable property that will be bound to other observable(s).

Returns

ObservableDualBindChain<K1, ViewEditableElement[ K1 ], K2, ViewEditableElement[ K2 ]>

The bind chain with the to() and toMany() methods.

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 associated command (both Observable).

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 equals command.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 (also Observables) 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 : Array<'index' | 'name' | 'off' | 'set' | 'bind' | 'unbind' | 'decorate' | 'stopListening' | 'on' | 'once' | 'listenTo' | 'fire' | 'delegate' | 'stopDelegating' | 'document' | 'parent' | 'nextSibling' | 'previousSibling' | 'getAttribute' | 'hasAttribute' | 'destroy' | 'root' | 'isReadOnly' | 'isFocused' | 'placeholder' | 'toJSON' | '_unsafeAttributesToRender' | 'childCount' | 'isEmpty' | 'getChild' | 'getChildIndex' | 'getChildren' | 'getAttributeKeys' | 'getAttributes' | 'isSimilar' | 'hasClass' | 'getClassNames' | 'getStyle' | 'getNormalizedStyle' | 'getStyleNames' | 'hasStyle' | 'findAncestor' | 'getCustomProperty' | 'getCustomProperties' | 'getIdentity' | 'shouldRenderUnsafeAttribute' | '_clone' | '_appendChild' | '_insertChild' | '_removeChildren' | '_setAttribute' | '_removeAttribute' | '_addClass' | '_removeClass' | '_setStyle' | '_removeStyle' | '_collectAttributesMatch' | '_getConsumables' | '_canMergeAttributesFrom' | '_mergeAttributesFrom' | '_canSubtractAttributesOf' | '_subtractAttributesOf' | '_setCustomProperty' | '_removeCustomProperty' | 'getFillerOffset' | 'isAttached' | 'getPath' | 'getAncestors' | 'getCommonAncestor' | 'isBefore' | 'isAfter' | '_remove' | '_fireChange' | 'is'>

Observable properties that will be bound to other observable(s).

Returns

ObservableMultiBindChain

The bind chain with the to() and toMany() methods.

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 associated command (both Observable).

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 equals command.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 (also Observables) 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 );

Type parameters

K

Parameters

bindProperty : K

Observable property that will be bound to other observable(s).

Returns

ObservableSingleBindChain<K, ViewEditableElement[ K ]>

The bind chain with the to() and toMany() methods.

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 extends ObservableMixin() {
	constructor() {
		super();
		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 : 'index' | 'name' | 'off' | 'set' | 'bind' | 'unbind' | 'decorate' | 'stopListening' | 'on' | 'once' | 'listenTo' | 'fire' | 'delegate' | 'stopDelegating' | 'document' | 'parent' | 'nextSibling' | 'previousSibling' | 'getAttribute' | 'hasAttribute' | 'destroy' | 'root' | 'isReadOnly' | 'isFocused' | 'placeholder' | 'toJSON' | '_unsafeAttributesToRender' | 'childCount' | 'isEmpty' | 'getChild' | 'getChildIndex' | 'getChildren' | 'getAttributeKeys' | 'getAttributes' | 'isSimilar' | 'hasClass' | 'getClassNames' | 'getStyle' | 'getNormalizedStyle' | 'getStyleNames' | 'hasStyle' | 'findAncestor' | 'getCustomProperty' | 'getCustomProperties' | 'getIdentity' | 'shouldRenderUnsafeAttribute' | '_clone' | '_appendChild' | '_insertChild' | '_removeChildren' | '_setAttribute' | '_removeAttribute' | '_addClass' | '_removeClass' | '_setStyle' | '_removeStyle' | '_collectAttributesMatch' | '_getConsumables' | '_canMergeAttributesFrom' | '_mergeAttributesFrom' | '_canSubtractAttributesOf' | '_subtractAttributesOf' | '_setCustomProperty' | '_removeCustomProperty' | 'getFillerOffset' | 'isAttached' | 'getPath' | 'getAncestors' | 'getCommonAncestor' | 'isBefore' | 'isAfter' | '_remove' | '_fireChange' | 'is'

Name of the method to decorate.

Returns

void

Delegates selected events to another Emitter. For instance:

emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

then eventX is delegated (fired by) emitterB and emitterC along with data:

emitterA.fire( 'eventX', data );

and eventY is delegated (fired by) emitterC along with data:

emitterA.fire( 'eventY', data );

Parameters

events : Array<string>

Event names that will be delegated to another emitter.

Returns

EmitterMixinDelegateChain

Returns

void

Returns ancestor element that match specified pattern. Provided patterns should be compatible with Matcher as it is used internally.

Parameters

patterns : Array<MatcherPattern | ( element: ViewElement ) => boolean>

Patterns used to match correct ancestor. See Matcher.

Returns

null | ViewElement

Found element or null if no matching ancestor was found.

Related:

• Matcher

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.

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).

Returns ancestors array of this node.

Parameters

options : object

Options object.

Properties

[ options.includeSelf ] : boolean

When set to true this node will be also included in parent's array.

[ options.parentFirst ] : boolean

When set to true, array will be sorted from node's parent to root element, otherwise root element will be the first item in the array.

Defaults to {}

Returns

Array<ViewNode | ViewDocumentFragment>

Array with ancestors.

Gets attribute by key. If attribute is not present - returns undefined.

Parameters

key : string

Attribute key.

Returns

undefined | string

Attribute value.

Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.

Returns

IterableIterator<string>

Keys for attributes.

Returns iterator that iterates over this element's attributes.

Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native Map object and also can be passed in Node constructor.

Returns

IterableIterator<tuple>

Gets child at the given index.

Parameters

index : number

Index of child.

Returns

undefined | ViewNode

Child node.

Gets index of the given child node. Returns -1 if child node is not found.

Parameters

node : ViewNode

Child node.

Returns

number

Index of the child node.

Gets child nodes iterator.

Returns

IterableIterator<ViewNode>

Child nodes iterator.

Returns iterator that contains all class names.

Returns

IterableIterator<string>

Returns a ViewElement or ViewDocumentFragment which is a common ancestor of both nodes.

Parameters

node : ViewNode

The second node.

options : object

Options object.

Properties

[ options.includeSelf ] : boolean

When set to true both nodes will be considered "ancestors" too. Which means that if e.g. node A is inside B, then their common ancestor will be B.

Defaults to {}

Returns

null | ViewElement | ViewDocumentFragment

Returns an iterator which iterates over this element's custom properties. Iterator provides [ key, value ] pairs for each stored property.

Returns

IterableIterator<tuple>

Returns the custom property value for the given key.

Parameters

key : string | symbol

Returns

unknown

Returns block filler offset or null if block filler is not needed.

Returns

null | number

Returns identity string based on element's name, styles, classes and other attributes. Two elements that are similar will have same identity string. It has the following format:

'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'

For example:

const element = writer.createContainerElement( 'foo', {
	banana: '10',
	apple: '20',
	style: 'color: red; border-color: white;',
	class: 'baz'
} );

// returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"'
element.getIdentity();

Note: Classes, styles and other attributes are sorted alphabetically.

Returns

string

Returns a normalized style object or single style value.

For an element with style set to: margin:1px 2px 3em;

element.getNormalizedStyle( 'margin' ) );

will return:

{
	top: '1px',
	right: '2px',
	bottom: '3em',
	left: '2px'    // a normalized value from margin shorthand
}

and reading for single style value:

styles.getNormalizedStyle( 'margin-left' );

Will return a 2px string.

Note: This method will return normalized values only if a particular style processor rule is enabled. See StylesMap#getNormalized() for details.

Parameters

property : string

Name of CSS property

Returns

undefined | StyleValue

Gets a path to the node. The path is an array containing indices of consecutive ancestors of this node, beginning from root, down to this node's index.

const abc = downcastWriter.createText( 'abc' );
const foo = downcastWriter.createText( 'foo' );
const h1 = downcastWriter.createElement( 'h1', null, downcastWriter.createText( 'header' ) );
const p = downcastWriter.createElement( 'p', null, [ abc, foo ] );
const div = downcastWriter.createElement( 'div', null, [ h1, p ] );
foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
h1.getPath(); // Returns [ 0 ].
div.getPath(); // Returns [].

Returns

Array<number>

The path.

Returns style value for the given property name. If the style does not exist undefined is returned.

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#getAsString() for details.

For an element with style set to 'margin:1px':

// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginStylesRules );

const element = view.change( writer => {
	const element = writer.createElement();
	writer.setStyle( 'margin', '1px' );
	writer.setStyle( 'margin-bottom', '3em' );

	return element;
} );

element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'

Parameters

property : string

Returns

undefined | string

Returns an array that contains all style names.

Parameters

[ expand ] : boolean

Expand shorthand style properties and return all equivalent style representations.

Returns

Array<string>

Returns a boolean indicating whether an attribute with the specified key exists in the element.

Parameters

key : string

Attribute key.

[ token ] : string

Returns

boolean

true if attribute with the specified key exists in the element, false otherwise.

Returns true if class is present. If more then one class is provided - returns true only when all classes are present.

element.hasClass( 'foo' ); // Returns true if 'foo' class is present.
element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.

Parameters

className : Array<string>

Returns

boolean

Returns true if style keys are present. If more then one style property is provided - returns true only when all properties are present.

element.hasStyle( 'color' ); // Returns true if 'border-top' style is present.
element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.

Parameters

property : Array<string>

Returns

boolean

Checks whether this object is of type ViewElement or its subclass.

element.is( 'element' ); // -> true
element.is( 'node' ); // -> true
element.is( 'view:element' ); // -> true
element.is( 'view:node' ); // -> true

element.is( 'model:element' ); // -> false
element.is( 'documentSelection' ); // -> false

Assuming that the object being checked is an element, you can also check its name:

element.is( 'element', 'img' ); // -> true if this is an <img> element
text.is( 'element', 'img' ); -> false

Parameters

type : 'element' | 'view:element'

Returns

this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement

Checks whether this object is of type ViewContainerElement or its subclass.

containerElement.is( 'containerElement' ); // -> true
containerElement.is( 'element' ); // -> true
containerElement.is( 'node' ); // -> true
containerElement.is( 'view:containerElement' ); // -> true
containerElement.is( 'view:element' ); // -> true
containerElement.is( 'view:node' ); // -> true

containerElement.is( 'model:element' ); // -> false
containerElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is a container element, you can also check its name:

containerElement.is( 'element', 'div' ); // -> true if this is a div container element
containerElement.is( 'contaienrElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

Parameters

type : 'containerElement' | 'view:containerElement'

Returns

this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement

Checks whether this object is of type ViewAttributeElement.

attributeElement.is( 'attributeElement' ); // -> true
attributeElement.is( 'element' ); // -> true
attributeElement.is( 'node' ); // -> true
attributeElement.is( 'view:attributeElement' ); // -> true
attributeElement.is( 'view:element' ); // -> true
attributeElement.is( 'view:node' ); // -> true

attributeElement.is( 'model:element' ); // -> false
attributeElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is an attribute element, you can also check its name:

attributeElement.is( 'element', 'b' ); // -> true if this is a bold element
attributeElement.is( 'attributeElement', 'b' ); // -> same as above
text.is( 'element', 'b' ); -> false

Parameters

type : 'attributeElement' | 'view:attributeElement'

Returns

this is ViewAttributeElement

Checks whether this object is of type ViewRootEditableElement.

rootEditableElement.is( 'rootElement' ); // -> true
rootEditableElement.is( 'editableElement' ); // -> true
rootEditableElement.is( 'element' ); // -> true
rootEditableElement.is( 'node' ); // -> true
rootEditableElement.is( 'view:editableElement' ); // -> true
rootEditableElement.is( 'view:element' ); // -> true
rootEditableElement.is( 'view:node' ); // -> true

rootEditableElement.is( 'model:element' ); // -> false
rootEditableElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is a root editable element, you can also check its name:

rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element
rootEditableElement.is( 'rootElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

Parameters

type : 'rootElement' | 'view:rootElement'

Returns

this is ViewRootEditableElement

Checks whether this object is of type ViewRawElement.

rawElement.is( 'rawElement' ); // -> true
rawElement.is( 'element' ); // -> true
rawElement.is( 'node' ); // -> true
rawElement.is( 'view:rawElement' ); // -> true
rawElement.is( 'view:element' ); // -> true
rawElement.is( 'view:node' ); // -> true

rawElement.is( 'model:element' ); // -> false
rawElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is a raw element, you can also check its name:

rawElement.is( 'img' ); // -> true if this is an img element
rawElement.is( 'rawElement', 'img' ); // -> same as above
text.is( 'img' ); -> false

Parameters

type : 'rawElement' | 'view:rawElement'

Returns

this is ViewRawElement

Checks whether this object is of type ViewEmptyElement.

emptyElement.is( 'emptyElement' ); // -> true
emptyElement.is( 'element' ); // -> true
emptyElement.is( 'node' ); // -> true
emptyElement.is( 'view:emptyElement' ); // -> true
emptyElement.is( 'view:element' ); // -> true
emptyElement.is( 'view:node' ); // -> true

emptyElement.is( 'model:element' ); // -> false
emptyElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is an empty element, you can also check its name:

emptyElement.is( 'element', 'img' ); // -> true if this is a img element
emptyElement.is( 'emptyElement', 'img' ); // -> same as above
text.is( 'element', 'img' ); -> false

Parameters

type : 'emptyElement' | 'view:emptyElement'

Returns

this is ViewEmptyElement

Checks whether this object is of type ViewEditableElement or its subclass.

editableElement.is( 'editableElement' ); // -> true
editableElement.is( 'element' ); // -> true
editableElement.is( 'node' ); // -> true
editableElement.is( 'view:editableElement' ); // -> true
editableElement.is( 'view:element' ); // -> true
editableElement.is( 'view:node' ); // -> true

editableElement.is( 'model:element' ); // -> false
editableElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is an editbale element, you can also check its name:

editableElement.is( 'element', 'div' ); // -> true if this is a div element
editableElement.is( 'editableElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

Parameters

type : 'editableElement' | 'view:editableElement'

Returns

this is ViewEditableElement | ViewRootEditableElement

Checks whether this object is of type ViewSelection or ViewDocumentSelection.

selection.is( 'selection' ); // -> true
selection.is( 'view:selection' ); // -> true

selection.is( 'model:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'range' ); // -> false

Parameters

type : 'selection' | 'view:selection'

Returns

this is ViewSelection | ViewDocumentSelection

Checks whether the object is of type ViewElement or its subclass and has the specified name.

Type parameters

N : extends string

Parameters

type : 'element' | 'view:element'

name : N

Returns

boolean

Checks whether this object is of type ViewDocumentSelection.

`docSelection.is( 'selection' ); // -> true
docSelection.is( 'documentSelection' ); // -> true
docSelection.is( 'view:selection' ); // -> true
docSelection.is( 'view:documentSelection' ); // -> true

docSelection.is( 'model:documentSelection' ); // -> false
docSelection.is( 'element' ); // -> false
docSelection.is( 'node' ); // -> false

Parameters

type : 'documentSelection' | 'view:documentSelection'

Returns

this is ViewDocumentSelection

Checks whether this object is of type ViewRange.

range.is( 'range' ); // -> true
range.is( 'view:range' ); // -> true

range.is( 'model:range' ); // -> false
range.is( 'element' ); // -> false
range.is( 'selection' ); // -> false

Parameters

type : 'range' | 'view:range'

Returns

this is ViewRange

Checks whether this object is of type ViewPosition.

position.is( 'position' ); // -> true
position.is( 'view:position' ); // -> true

position.is( 'model:position' ); // -> false
position.is( 'element' ); // -> false
position.is( 'range' ); // -> false

Parameters

type : 'position' | 'view:position'

Returns

this is ViewPosition

Checks whether this object is of type ViewTextProxy.

textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'view:$textProxy' ); // -> true

textProxy.is( 'model:$textProxy' ); // -> false
textProxy.is( 'element' ); // -> false
textProxy.is( 'range' ); // -> false

Note: Until version 20.0.0 this method wasn't accepting '$textProxy' type. The legacy 'textProxy' type is still accepted for backward compatibility.

Parameters

type : '$textProxy' | 'view:$textProxy'

Returns

this is ViewTextProxy

hecks whether this object is of type ViewDocumentFragment.

docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'view:documentFragment' ); // -> true

docFrag.is( 'model:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false

Parameters

type : 'documentFragment' | 'view:documentFragment'

Returns

this is ViewDocumentFragment

Checks whether this object is of type ViewText.

text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'view:$text' ); // -> true
text.is( 'view:node' ); // -> true

text.is( 'model:$text' ); // -> false
text.is( 'element' ); // -> false
text.is( 'range' ); // -> false

Parameters

type : '$text' | 'view:$text'

Returns

this is ViewText

Checks whether this object is of type ViewUIElement.

uiElement.is( 'uiElement' ); // -> true
uiElement.is( 'element' ); // -> true
uiElement.is( 'node' ); // -> true
uiElement.is( 'view:uiElement' ); // -> true
uiElement.is( 'view:element' ); // -> true
uiElement.is( 'view:node' ); // -> true

uiElement.is( 'model:element' ); // -> false
uiElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is an ui element, you can also check its name:

uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
uiElement.is( 'uiElement', 'span' ); // -> same as above
text.is( 'element', 'span' ); -> false

Parameters

type : 'uiElement' | 'view:uiElement'

Returns

this is ViewUIElement

Checks whether the object is of type ViewContainerElement or its subclass and has the specified name.

Type parameters

N : extends string

Parameters

type : 'containerElement' | 'view:containerElement'

name : N

Returns

boolean

Checks whether the object is of type ViewRootEditableElement and has the specified name.

Type parameters

N : extends string

Parameters

type : 'rootElement' | 'view:rootElement'

name : N

Returns

boolean

Checks whether the object is of type ViewUIElement and has the specified name.

Type parameters

N : extends string

Parameters

type : 'uiElement' | 'view:uiElement'

name : N

Returns

boolean

Checks whether the object is of type ViewRawElement and has the specified name.

Type parameters

N : extends string

Parameters

type : 'rawElement' | 'view:rawElement'

name : N

Returns

boolean

Checks whether the object is of type ViewEmptyElement has the specified name.

Type parameters

N : extends string

Parameters

type : 'emptyElement' | 'view:emptyElement'

name : N

Returns

boolean

Checks whether the object is of type ViewEditableElement or its subclass and has the specified name.

Type parameters

N : extends string

Parameters

type : 'editableElement' | 'view:editableElement'

name : N

Returns

boolean

Checks whether the object is of type ViewAttributeElement and has the specified name.

Type parameters

N : extends string

Parameters

type : 'attributeElement' | 'view:attributeElement'

name : N

Returns

boolean

Checks whether this object is of type ViewNode or its subclass.

This method is useful when processing view objects that are of unknown type. For example, a function may return a ViewDocumentFragment or a ViewNode that can be either a text node or an element. This method can be used to check what kind of object is returned.

someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment

Since this method is also available on a range of model objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:

viewElement.is( 'view:element' ); // -> true
viewElement.is( 'model:element' ); // -> false

By using this method it is also possible to check a name of an element:

imgElement.is( 'element', 'img' ); // -> true
imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise

Parameters

type : 'node' | 'view:node'

Returns

this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement

Returns whether this node is after given node. false is returned if nodes are in different trees (for example, in different ViewDocumentFragments).

Parameters

node : ViewNode

Node to compare with.

Returns

boolean

Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).

Returns

boolean

Returns whether this node is before given node. false is returned if nodes are in different trees (for example, in different ViewDocumentFragments).

Parameters

node : ViewNode

Node to compare with.

Returns

boolean

Checks if this element is similar to other element. Both elements should have the same name and attributes to be considered as similar. Two similar elements can contain different set of children nodes.

Parameters

otherElement : ViewItem

Returns

boolean

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.

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

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.

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

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

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.

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

Creates and sets the value of an observable properties of this object. Such a property becomes a part of the state and is observable.

It accepts 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 that foo.set( 'bar', 1 ) may be slightly slower than foo.bar = 1.

In TypeScript, those properties should be declared in class using declare keyword. In example:

public declare myProp1: number;
public declare myProp2: string;

constructor() {
	this.set( {
		'myProp1: 2,
		'myProp2: 'foo'
	} );
}

Parameters

values : object

An object with name=>value pairs.

Returns

void

Creates and sets the value of an observable property of this object. Such a property becomes a part of the state and is observable.

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 that foo.set( 'bar', 1 ) may be slightly slower than foo.bar = 1.

In TypeScript, those properties should be declared in class using declare keyword. In example:

public declare myProp: number;

constructor() {
	this.set( 'myProp', 2 );
}

Type parameters

K

Parameters

name : K

The property's name.

value : ViewEditableElement[ K ]

The property's value.

Returns

void

Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms like shouldRenderAttribute say it should not.

Unsafe attribute names can be specified when creating an element via ViewDowncastWriter.

Parameters

attributeName : string

The name of the attribute to be checked.

Returns

boolean

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 of event to all emitters.

Returns

void

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 from emitter.

[ callback ] : Function

(Requires the event) The function to be removed from the call list for the given event.

Returns

void

Converts ViewEditableElement instance to plain object and returns it.

Returns

unknown

ViewEditableElement instance converted to plain object.

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 : Array<'index' | 'name' | 'off' | 'set' | 'bind' | 'unbind' | 'decorate' | 'stopListening' | 'on' | 'once' | 'listenTo' | 'fire' | 'delegate' | 'stopDelegating' | 'document' | 'parent' | 'nextSibling' | 'previousSibling' | 'getAttribute' | 'hasAttribute' | 'destroy' | 'root' | 'isReadOnly' | 'isFocused' | 'placeholder' | 'toJSON' | '_unsafeAttributesToRender' | 'childCount' | 'isEmpty' | 'getChild' | 'getChildIndex' | 'getChildren' | 'getAttributeKeys' | 'getAttributes' | 'isSimilar' | 'hasClass' | 'getClassNames' | 'getStyle' | 'getNormalizedStyle' | 'getStyleNames' | 'hasStyle' | 'findAncestor' | 'getCustomProperty' | 'getCustomProperties' | 'getIdentity' | 'shouldRenderUnsafeAttribute' | '_clone' | '_appendChild' | '_insertChild' | '_removeChildren' | '_setAttribute' | '_removeAttribute' | '_addClass' | '_removeClass' | '_setStyle' | '_removeStyle' | '_collectAttributesMatch' | '_getConsumables' | '_canMergeAttributesFrom' | '_mergeAttributesFrom' | '_canSubtractAttributesOf' | '_subtractAttributesOf' | '_setCustomProperty' | '_removeCustomProperty' | 'getFillerOffset' | 'isAttached' | 'getPath' | 'getAncestors' | 'getCommonAncestor' | 'isBefore' | 'isAfter' | '_remove' | '_fireChange' | 'is'>

Observable properties to be unbound. All the bindings will be released if no properties are provided.

Returns

void

Adds specified class.

element._addClass( 'foo' ); // Adds 'foo' class.
element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.

Parameters

className : ArrayOrItem<string>

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#addClass

Insert a child node or a list of child nodes at the end of this node and sets the parent of these nodes to this element.

Parameters

items : string | ViewItem | Iterable<( string | ViewItem )>

Items to be inserted.

Returns

number

Number of appended nodes.

Fires

• change

Related:

• ViewDowncastWriter#insert

Verify if the given element can be merged without conflicts into the element.

Note that this method is extended by the ViewAttributeElement implementation.

This method is used by the ViewDowncastWriter while down-casting an ViewAttributeElement to merge it with other ViewAttributeElement.

Parameters

otherElement : ViewElement

Returns

boolean

Returns true if elements can be merged.

Verify if the given element attributes can be fully subtracted from the element.

Note that this method is extended by the ViewAttributeElement implementation.

This method is used by the ViewDowncastWriter while down-casting an ViewAttributeElement to unwrap the ViewAttributeElement.

Parameters

otherElement : ViewElement

Returns

boolean

Returns true if elements attributes can be fully subtracted.

Clones provided element.

Parameters

deep : boolean

If set to true clones element and all its children recursively. When set to false, element will be cloned without any children.

Defaults to false

Returns

this

Clone of this element.

Used by the Matcher to collect matching attribute tuples (attribute name and optional token).

Normalized patterns can be used in following ways:

• to match any attribute name with any or no value:

patterns: [
	[ true, true ]
]

• to match a specific attribute with any value:

patterns: [
	[ 'required', true ]
]

• to match an attribute name with a RegExp with any value:

patterns: [
	[ /h[1-6]/, true ]
]

- to match a specific attribute with the exact value:

patterns: [
	[ 'rel', 'nofollow' ]
]

- to match a specific attribute with a value matching a RegExp:

patterns: [
	[ 'src', /^https/ ]
]

- to match an attribute name with a RegExp and the exact value:

patterns: [
	[ /^data-property-/, 'foobar' ],
]

- to match an attribute name with a RegExp and match a value with another RegExp:

patterns: [
	[ /^data-property-/, /^foo/ ]
]

- to match a specific style property with the value matching a RegExp:

patterns: [
	[ 'style', 'font-size', /px$/ ]
]

- to match a specific class (class attribute is tokenized so it matches tokens individually):

patterns: [
	[ 'class', 'foo' ]
]

Parameters

patterns : Array<NormalizedPropertyPattern>

An array of normalized patterns (tuples of 2 or 3 items depending on if tokenized attribute value match is needed).

match : Array<tuple>

An array to populate with matching tuples.

[ exclude ] : Array<string>

Array of attribute names to exclude from match.

Returns

boolean

true if element matches all patterns. The matching tuples are pushed to the match array.

Parameters

type : ViewDocumentChangeType

Type of the change.

node : ViewNode

Changed node.

[ data ] : object

Additional data.

Properties

data.index : number

Returns

void

Fires

• change

Used by the ViewConsumable to collect the ViewNormalizedConsumables for the element.

When key and token parameters are provided the output is filtered for the specified attribute and it's tokens and related tokens.

Parameters

[ key ] : string

Attribute name.

[ token ] : string

Reference token to collect all related tokens.

Returns

ViewNormalizedConsumables

Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to this element.

Parameters

index : number

Position where nodes should be inserted.

items : string | ViewItem | Iterable<( string | ViewItem )>

Items to be inserted.

Returns

number

Number of inserted nodes.

Fires

• change

Related:

• ViewDowncastWriter#insert

Merges attributes of a given element into the element. This includes also tokenized attributes like style and class.

Note that you should make sure there are no conflicts before merging (see _canMergeAttributesFrom).

This method is used by the ViewDowncastWriter while down-casting an ViewAttributeElement to merge it with other ViewAttributeElement.

Parameters

otherElement : ViewElement

Returns

void

Removes node from parent.

Returns

void

Removes attribute from the element.

Parameters

key : string

Attribute key.

[ tokens ] : ArrayOrItem<string>

Attribute value tokens to remove. The whole attribute is removed if not specified.

Returns

boolean

Returns true if an attribute existed and has been removed.

Fires

• change

Related:

• ViewDowncastWriter#removeAttribute

Removes number of child nodes starting at the given index and set the parent of these nodes to null.

Parameters

index : number

Number of the first node to remove.

howMany : number

Number of nodes to remove.

Defaults to 1

Returns

Array<ViewNode>

The array of removed nodes.

Fires

• change

Related:

• ViewDowncastWriter#remove

Removes specified class.

element._removeClass( 'foo' );  // Removes 'foo' class.
element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.

Parameters

className : ArrayOrItem<string>

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#removeClass

Removes the custom property stored under the given key.

Parameters

key : string | symbol

Returns

boolean

Returns true if property was removed.

Related:

• ViewDowncastWriter#removeCustomProperty

Removes specified style.

element._removeStyle( 'color' );  // Removes 'color' style.
element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#remove() for details.

Parameters

property : ArrayOrItem<string>

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#removeStyle

Adds or overwrite attribute with a specified key and value.

Parameters

key : string

Attribute key.

value : unknown

Attribute value.

overwrite : boolean

Whether tokenized attribute should override the attribute value or just add a token.

Defaults to true

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#setAttribute

Sets a custom property. Unlike attributes, custom properties are not rendered to the DOM, so they can be used to add special data to elements.

Parameters

key : string | symbol

value : unknown

Returns

void

Related:

• ViewDowncastWriter#setCustomProperty

Adds style to the element.

element._setStyle( {
	color: 'red',
	position: 'fixed'
} );

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

Parameters

properties : Record<string, string>

Object with key - value pairs.

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#setStyle

Adds style to the element.

element._setStyle( 'color', 'red' );

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

Parameters

property : string

Property name.

value : string

Value to set.

Returns

void

Fires

• change

Related:

• ViewDowncastWriter#setStyle

Removes (subtracts) corresponding attributes of the given element from the element. This includes also tokenized attributes like style and class. All attributes, classes and styles from given element should be present inside the element being unwrapped.

Note that you should make sure all attributes could be subtracted before subtracting them (see _canSubtractAttributesOf).

This method is used by the ViewDowncastWriter while down-casting an ViewAttributeElement to unwrap the ViewAttributeElement.

Parameters

otherElement : ViewElement

Returns

void

Fired when list of elements children, attributes or text changes.

Change event is bubbled – it is fired on all ancestors.

All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : ViewNode

[ data ] : object

Fired when list of elements children, attributes or text changes.

Change event is bubbled – it is fired on all ancestors.

All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : ViewNode

[ data ] : object

Fired when list of elements children, attributes or text changes.

Change event is bubbled – it is fired on all ancestors.

All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : ViewNode

[ data ] : object

Fired when the isFocused property changed value.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (isFocused).

value : boolean

New value of the isFocused property with given key or null, if operation should remove property.

oldValue : boolean

Old value of the isFocused property with given key or null, if property was not set before.

Fired when the isReadOnly property changed value.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (isReadOnly).

value : boolean

New value of the isReadOnly property with given key or null, if operation should remove property.

oldValue : boolean

Old value of the isReadOnly property with given key or null, if property was not set before.

Fired when the placeholder property changed value.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (placeholder).

value : string

New value of the placeholder property with given key or null, if operation should remove property.

oldValue : string

Old value of the placeholder property with given key or null, if property was not set before.

Fired when list of elements children, attributes or text changes.

Change event is bubbled – it is fired on all ancestors.

All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : ViewNode

[ data ] : object

Fired when a property changed value.

observable.set( 'prop', 1 );

observable.on<ObservableChangeEvent<number>>( '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 : TValue

The new property value.

oldValue : TValue

The previous property value.

Fired when the isFocused property is going to be set but is not set yet (before the change event is fired).

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (isFocused).

value : boolean

New value of the isFocused property with given key or null, if operation should remove property.

oldValue : boolean

Old value of the isFocused property with given key or null, if property was not set before.

Fired when the isReadOnly property is going to be set but is not set yet (before the change event is fired).

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (isReadOnly).

value : boolean

New value of the isReadOnly property with given key or null, if operation should remove property.

oldValue : boolean

Old value of the isReadOnly property with given key or null, if property was not set before.

Fired when the placeholder property is going to be set but is not set yet (before the change event is fired).

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

name : string

Name of the changed property (placeholder).

value : string

New value of the placeholder property with given key or null, if operation should remove property.

oldValue : string

Old value of the placeholder property with given key or null, if property was not set before.

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<ObservableSetEvent<number>>( '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<ObservableChangeEvent<number>>( '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 : TValue

The new property value.

oldValue : TValue

The previous property value.