Node (engine/view)
@ckeditor/ckeditor5-engine/src/view/node
Abstract view node class.
This is an abstract class. Its constructor should not be used directly.
Use the DowncastWriter
or UpcastWriter
to create new instances of view nodes.
Filtering
Properties
-
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.
-
Node's next sibling, or
null
if it is the last child. -
Parent element. Null by default. Set by
_insertChild
. -
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.
Methods
-
Creates a tree view node.
Parameters
document : Document
The document instance to which this node belongs.
-
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
andemitterC
along withdata
:emitterA.fire( 'eventX', data );
and
eventY
is delegated (fired by)emitterC
along withdata
:emitterA.fire( 'eventY', data );
Parameters
events : Array<string>
Event names that will be delegated to another emitter.
Returns
-
inherited
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
module:engine/view/node~Node#fire
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.Type parameters
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 theevt.return
's property (the event info is the first param of every callback).
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>
module:engine/view/node~Node#getAncestors
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<Node | DocumentFragment>
Array with ancestors.
-
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragment
module:engine/view/node~Node#getCommonAncestor
Returns a
Element
orDocumentFragment
which is a common ancestor of both nodes.Parameters
node : Node
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 | Element | DocumentFragment
-
getPath() → Array<number>
module:engine/view/node~Node#getPath
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.
-
inherited
is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/node~Node#is:ELEMENT
Checks whether this object is of type
Element
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 Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
Checks whether this object is of type
AttributeElement
.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 AttributeElement
-
inherited
is( type ) → this is ContainerElement | EditableElement | RootEditableElement
module:engine/view/node~Node#is:CONTAINER_ELEMENT
Checks whether this object is of type
ContainerElement
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 ContainerElement | EditableElement | RootEditableElement
-
Checks whether this object is of type
RootEditableElement
.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 RootEditableElement
-
Checks whether this object is of type
UIElement
.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 UIElement
-
Checks whether this object is of type
RawElement
.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 RawElement
-
Checks whether this object is of type
EmptyElement
.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 EmptyElement
-
inherited
is( type ) → this is EditableElement | RootEditableElement
module:engine/view/node~Node#is:EDITABLE_ELEMENT
Checks whether this object is of type
EditableElement
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 EditableElement | RootEditableElement
-
Checks whether this object is of type
Text
.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 Text
-
Checks whether this object is of type
TextProxy
.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 TextProxy
-
Checks whether this object is of type
DocumentSelection
.`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 DocumentSelection
-
Checks whether the object is of type
AttributeElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EditableElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RawElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'
name : N
Returns
boolean
-
Checks whether the object is of type
UIElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RootEditableElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EmptyElement
has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'
name : N
Returns
boolean
-
Checks whether the object is of type
ContainerElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'
name : N
Returns
boolean
-
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'
name : N
Returns
boolean
-
inherited
is( type ) → this is Selection | DocumentSelection
module:engine/view/node~Node#is:SELECTION
Checks whether this object is of type
Selection
orDocumentSelection
.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 Selection | DocumentSelection
-
Checks whether this object is of type
Position
.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 Position
-
hecks whether this object is of type
DocumentFragment
.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 DocumentFragment
-
inherited
is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/node~Node#is:NODE
Checks whether this object is of type
Node
or its subclass.This method is useful when processing view objects that are of unknown type. For example, a function may return a
DocumentFragment
or aNode
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:
orview:
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 Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
isAfter( node ) → boolean
module:engine/view/node~Node#isAfter
Returns whether this node is after given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
boolean
-
isAttached() → boolean
module:engine/view/node~Node#isAttached
Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).
Returns
boolean
-
isBefore( node ) → boolean
module:engine/view/node~Node#isBefore
Returns whether this node is before given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
boolean
-
isSimilar( other ) → boolean
module:engine/view/node~Node#isSimilar
Checks if provided node is similar to this node.
Parameters
other : Node
Returns
boolean
True if nodes are similar.
-
inherited
listenTo( emitter, event, callback, [ options ] ) → void
module:engine/view/node~Node#listenTo:BASE_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using
:
. When namespaced event is fired, it additionally fires all callbacks for that namespace.// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ). myEmitter.on( 'myGroup', genericCallback ); myEmitter.on( 'myGroup:myEvent', specificCallback ); // genericCallback is fired. myEmitter.fire( 'myGroup' ); // both genericCallback and specificCallback are fired. myEmitter.fire( 'myGroup:myEvent' ); // genericCallback is fired even though there are no callbacks for "foo". myEmitter.fire( 'myGroup:foo' );
An event callback can stop the event and set the return value of the
fire
method.Type parameters
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
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 byoff
in 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
-
inherited
stopDelegating( [ event ], [ emitter ] ) → void
module:engine/view/node~Node#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
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.
Returns
void
-
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → void
module:engine/view/node~Node#stopListening:BASE_STOP
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
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
.
Returns
void
-
toJSON() → unknown
module:engine/view/node~Node#toJSON
Custom toJSON method to solve child-parent circular dependencies.
Returns
unknown
Clone of this object with the parent property removed.
-
-
-
Events
-
change( eventInfo, changedNode )
module:engine/view/node~Node#event:change
Fired when list of elements children, attributes or data changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
-
change:attributes( eventInfo, changedNode )
module:engine/view/node~Node#event:change:attributes
Fired when list of elements children, attributes or data changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
-
change:children( eventInfo, changedNode )
module:engine/view/node~Node#event:change:children
Fired when list of elements children, attributes or data changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
-
change:text( eventInfo, changedNode )
module:engine/view/node~Node#event:change:text
Fired when list of elements children, attributes or data changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
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.