Node (engine/model)
@ckeditor/ckeditor5-engine/src/model/node
Model node. Most basic structure of model tree.
This is an abstract class that is a base for other classes representing different nodes in model.
Note: If a node is detached from the model tree, you can manipulate it using it's API. However, it is very important that nodes already attached to model tree should be only changed through Writer API.
Changes done by Node methods, like _insertChild or
_setAttribute
do not generate operations
which are essential for correct editor work if you modify nodes in document root.
The flow of working on Node (and classes that inherits from it) is as such:
- You can create a
Nodeinstance, modify it using it's API. - Add
Nodeto the model usingBatchAPI. - Change
Nodethat was already added to the model usingBatchAPI.
Similarly, you cannot use Batch API on a node that has not been added to the model tree, with the exception
of inserting that node to the model tree.
Be aware that using remove from Batch API does not allow to use Node API because
the information about Node is still kept in model document.
In case of element node, adding and removing children also counts as changing a node and follows same rules.
Filtering
Properties
-
Document that owns this root element.
-
Offset at which this node ends in it's parent. It is equal to the sum of this node's start offset and offset size. Equals to
nullif the node has no parent. -
Index of this node in its parent or
nullif the node has no parent.Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
-
Node's next sibling or
nullif the node is a last child of it's parent or if the node has no parent. -
Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent. It is important for position. When node has
offsetSizegreater than1, position can be placed between that node start and end.offsetSizegreater than1is for nodes that represents more than one entity, i.e. text node. -
Parent of this node. It could be
ElementorDocumentFragment. Equals tonullif the node has no parent. -
Node's previous sibling or
nullif the node is a first child of it's parent or if the node has no parent. -
The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part of
DocumentFragment, it'srootis equal to thatDocumentFragment. -
Unique root name used to identify this root element by
Document. -
Offset at which this node starts in its parent. It is equal to the sum of offsetSize of all its previous siblings. Equals to
nullif node has no parent.Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
-
Attributes set on this node.
Methods
-
constructor( [ attrs ] )module:engine/model/node~Node#constructorCreates a model node.
This is an abstract class, so this constructor should not be used directly.
Parameters
[ attrs ] : NodeAttributesNode's attributes. See
toMapfor a list of accepted values.
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>module:engine/model/node~Node#getAncestorsReturns ancestors array of this node.
Parameters
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
truethis node will be also included in parent's array.[ options.parentFirst ] : booleanWhen 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.
-
getAttribute( key ) → unknownmodule:engine/model/node~Node#getAttributeGets an attribute value for given key or
undefinedif that attribute is not set on node.Parameters
key : stringKey of attribute to look for.
Returns
unknownAttribute value or
undefined.
-
getAttributeKeys() → IterableIterator<string>module:engine/model/node~Node#getAttributeKeysReturns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
-
getAttributes() → IterableIterator<tuple>module:engine/model/node~Node#getAttributesReturns iterator that iterates over this node'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
Mapobject and also can be passed inNodeconstructor.Returns
IterableIterator<tuple>
-
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragmentmodule:engine/model/node~Node#getCommonAncestorReturns a
ElementorDocumentFragmentwhich is a common ancestor of both nodes.Parameters
node : NodeThe second node.
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
trueboth 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/model/node~Node#getPathGets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node, beginning from root, down to this node's starting offset. The path can be used to create Position instance.
const abc = new Text( 'abc' ); const foo = new Text( 'foo' ); const h1 = new Element( 'h1', null, new Text( 'header' ) ); const p = new Element( 'p', null, [ abc, foo ] ); const div = new Element( '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>
-
hasAttribute( key ) → booleanmodule:engine/model/node~Node#hasAttributeChecks if the node has an attribute with given key.
Parameters
key : stringKey of attribute to check.
Returns
booleantrueif attribute with given key is set on node,falseotherwise.
-
Checks whether the object is of type
Elementor its subclass.element.is( 'element' ); // -> true element.is( 'node' ); // -> true element.is( 'model:element' ); // -> true element.is( 'model:node' ); // -> true element.is( 'view:element' ); // -> false element.is( 'documentSelection' ); // -> falseAssuming that the object being checked is an element, you can also check its name:
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element text.is( 'element', 'imageBlock' ); -> falseParameters
type : 'element' | 'model:element'
Returns
this is Element | RootElement
-
Checks whether the object is of type
RootElement.rootElement.is( 'rootElement' ); // -> true rootElement.is( 'element' ); // -> true rootElement.is( 'node' ); // -> true rootElement.is( 'model:rootElement' ); // -> true rootElement.is( 'model:element' ); // -> true rootElement.is( 'model:node' ); // -> true rootElement.is( 'view:element' ); // -> false rootElement.is( 'documentFragment' ); // -> falseAssuming that the object being checked is an element, you can also check its name:
rootElement.is( 'rootElement', '$root' ); // -> same as aboveParameters
type : 'rootElement' | 'model:rootElement'
Returns
this is RootElement
-
Checks whether the object is of type
Positionor its subclass.position.is( 'position' ); // -> true position.is( 'model:position' ); // -> true position.is( 'view:position' ); // -> false position.is( 'documentSelection' ); // -> falseParameters
type : 'position' | 'model:position'
Returns
this is Position | LivePosition
-
Checks whether the object is of type
Text.text.is( '$text' ); // -> true text.is( 'node' ); // -> true text.is( 'model:$text' ); // -> true text.is( 'model:node' ); // -> true text.is( 'view:$text' ); // -> false text.is( 'documentSelection' ); // -> falseNote: Until version 20.0.0 this method wasn't accepting
'$text'type. The legacy'text'type is still accepted for backward compatibility.Parameters
type : '$text' | 'model:$text'
Returns
this is Text
-
Checks whether the object is of type
Rangeor its subclass.range.is( 'range' ); // -> true range.is( 'model:range' ); // -> true range.is( 'view:range' ); // -> false range.is( 'documentSelection' ); // -> falseParameters
type : 'range' | 'model:range'
Returns
-
Checks whether the object is of type
DocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'documentSelection' ); // -> true selection.is( 'model:selection' ); // -> true selection.is( 'model:documentSelection' ); // -> true selection.is( 'view:selection' ); // -> false selection.is( 'element' ); // -> false selection.is( 'node' ); // -> falseParameters
type : 'documentSelection' | 'model:documentSelection'
Returns
this is DocumentSelection
-
Checks whether the object is of type
Elementor its subclass and has the specifiedname.element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element text.is( 'element', 'imageBlock' ); -> falseType parameters
N : extends string
Parameters
type : 'element' | 'model:element'name : N
Returns
boolean
-
Checks whether the object is of type
TextProxy.textProxy.is( '$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> false textProxy.is( 'range' ); // -> falseNote: Until version 20.0.0 this method wasn't accepting
'$textProxy'type. The legacy'textProxt'type is still accepted for backward compatibility.Parameters
type : '$textProxy' | 'model:$textProxy'
Returns
this is TextProxy
-
inherited
is( type ) → this is Selection | DocumentSelectionmodule:engine/model/node~Node#is:SELECTIONChecks whether the object is of type
SelectionorDocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'model:selection' ); // -> true selection.is( 'view:selection' ); // -> false selection.is( 'range' ); // -> falseParameters
type : 'selection' | 'model:selection'
Returns
this is Selection | DocumentSelection
-
Checks whether the object is of type
DocumentFragment.docFrag.is( 'documentFragment' ); // -> true docFrag.is( 'model:documentFragment' ); // -> true docFrag.is( 'view:documentFragment' ); // -> false docFrag.is( 'element' ); // -> false docFrag.is( 'node' ); // -> falseParameters
type : 'documentFragment' | 'model:documentFragment'
Returns
this is DocumentFragment
-
Checks whether the object is of type
LiveRange.liveRange.is( 'range' ); // -> true liveRange.is( 'model:range' ); // -> true liveRange.is( 'liveRange' ); // -> true liveRange.is( 'model:liveRange' ); // -> true liveRange.is( 'view:range' ); // -> false liveRange.is( 'documentSelection' ); // -> falseParameters
type : 'liveRange' | 'model:liveRange'
Returns
this is LiveRange
-
Checks whether the object is of type
LivePosition.livePosition.is( 'position' ); // -> true livePosition.is( 'model:position' ); // -> true livePosition.is( 'liveposition' ); // -> true livePosition.is( 'model:livePosition' ); // -> true livePosition.is( 'view:position' ); // -> false livePosition.is( 'documentSelection' ); // -> falseParameters
type : 'livePosition' | 'model:livePosition'
Returns
this is LivePosition
-
Checks whether the object is of type
RootElementand has the specifiedname.rootElement.is( 'rootElement', '$root' );Type parameters
N : extends string
Parameters
type : 'rootElement' | 'model:rootElement'name : N
Returns
boolean
-
inherited
is( type ) → this is Node | Text | Element | RootElementmodule:engine/model/node~Node#is:NODEChecks whether the object is of type
Nodeor its subclass.This method is useful when processing model objects that are of unknown type. For example, a function may return a
DocumentFragmentor aNodethat 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 fragmentSince this method is also available on a range of view 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:modelElement.is( 'model:element' ); // -> true modelElement.is( 'view:element' ); // -> falseBy using this method it is also possible to check a name of an element:
imageElement.is( 'element', 'imageBlock' ); // -> true imageElement.is( 'element', 'imageBlock' ); // -> same as above imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more preciseParameters
type : 'node' | 'model:node'
Returns
this is Node | Text | Element | RootElement
-
isAfter( node ) → booleanmodule:engine/model/node~Node#isAfterReturns whether this node is after given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments).Parameters
node : NodeNode to compare with.
Returns
boolean
-
isAttached() → booleanmodule:engine/model/node~Node#isAttachedReturns
trueif the node is inside a document root that is attached to the document.Returns
boolean
-
isBefore( node ) → booleanmodule:engine/model/node~Node#isBeforeReturns whether this node is before given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments).Parameters
node : NodeNode to compare with.
Returns
boolean
-
toJSON() → unknownmodule:engine/model/node~Node#toJSONConverts
Nodeto plain object and returns it.Returns
unknownNodeconverted to plain object.
-
-
Creates a copy of this node, that is a node with exactly same attributes, and returns it.
Parameters
[ _deep ] : boolean
Returns
NodeNode with same attributes as this node.
-
-
Removes an attribute with given key from the node.
Parameters
key : stringKey of attribute to remove.
Returns
booleantrueif the attribute was set on the element,falseotherwise.
Related:
-
Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
Parameters
key : stringKey of attribute to set.
value : unknownAttribute value.
Returns
void
Related:
-
Removes all attributes from the node and sets given attributes.
Parameters
attrs : NodeAttributesAttributes to set. See
toMapfor a list of accepted values.
Returns
void
Related:
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.