Class

Node (engine/model)

@ckeditor/ckeditor5-engine/src/model/node

class

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:

  1. You can create a Node instance, modify it using it's API.
  2. Add Node to the model using Batch API.
  3. Change Node that was already added to the model using Batch API.

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

  • readonly

    document : null | Document

    Document that owns this root element.

  • readonly

    endOffset : null | number

    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 null if the node has no parent.

  • readonly

    index : null | number

    Index of this node in its parent 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 model tree got broken.

  • readonly

    nextSibling : null | Node

    Node's next sibling or null if the node is a last child of it's parent or if the node has no parent.

  • readonly

    offsetSize : number

    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 offsetSize greater than 1, position can be placed between that node start and end. offsetSize greater than 1 is for nodes that represents more than one entity, i.e. text node.

  • readonly

    parent : null | Element | DocumentFragment

    Parent of this node. It could be Element or DocumentFragment. Equals to null if the node has no parent.

  • readonly

    previousSibling : null | Node

    Node's previous sibling or null if the node is a first child of it's parent or if the node has no parent.

  • readonly

    root : Node | DocumentFragment

    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's root is equal to that DocumentFragment.

  • readonly

    rootName : undefined | string

    Unique root name used to identify this root element by Document.

  • readonly

    startOffset : null | number

    Offset at which this node starts in its parent. It is equal to the sum of offsetSize of all its previous siblings. Equals to null if 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.

  • private

    _attrs : Map<string, unknown>

    Attributes set on this node.

Methods

  • constructor( [ attrs ] )

    Creates a model node.

    This is an abstract class, so this constructor should not be used directly.

    Parameters

    [ attrs ] : NodeAttributes

    Node's attributes. See toMap for a list of accepted values.

  • getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>

    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.

  • getAttribute( key ) → unknown

    Gets an attribute value for given key or undefined if that attribute is not set on node.

    Parameters

    key : string

    Key of attribute to look for.

    Returns

    unknown

    Attribute value or undefined.

  • getAttributeKeys() → IterableIterator<string>

    Returns iterator that iterates over this node's attribute keys.

    Returns

    IterableIterator<string>
  • getAttributes() → IterableIterator<tuple>

    Returns 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 Map object and also can be passed in Node constructor.

    Returns

    IterableIterator<tuple>
  • getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragment

    Returns a Element or DocumentFragment 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>

    Gets 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 ) → boolean

    Checks if the node has an attribute with given key.

    Parameters

    key : string

    Key of attribute to check.

    Returns

    boolean

    true if attribute with given key is set on node, false otherwise.

  • inherited

    is( type ) → this is Element | RootElement

    Checks whether the object is of type Element or 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' ); // -> false
    

    Assuming 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' ); -> false
    

    Parameters

    type : 'element' | 'model:element'

    Returns

    this is Element | RootElement
  • inherited

    is( type ) → this is 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' ); // -> false
    

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

    rootElement.is( 'rootElement', '$root' ); // -> same as above
    

    Parameters

    type : 'rootElement' | 'model:rootElement'

    Returns

    this is RootElement
  • inherited

    is( type ) → this is Position | LivePosition

    Checks whether the object is of type Position or its subclass.

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

    Parameters

    type : 'position' | 'model:position'

    Returns

    this is Position | LivePosition
  • inherited

    is( type ) → this is Text

    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' ); // -> false
    

    Note: 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
  • inherited

    is( type ) → this is Range | LiveRange

    Checks whether the object is of type Range or its subclass.

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

    Parameters

    type : 'range' | 'model:range'

    Returns

    this is Range | LiveRange
  • inherited

    is( type ) → this is DocumentSelection

    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' ); // -> false
    

    Parameters

    type : 'documentSelection' | 'model:documentSelection'

    Returns

    this is DocumentSelection
  • inherited

    is( type, name ) → boolean

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

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

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'model:element'
    name : N

    Returns

    boolean
  • inherited

    is( type ) → this is TextProxy

    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' ); // -> false
    

    Note: 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 Marker

    Checks whether the object is of type Marker.

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

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker
  • inherited

    is( type ) → this is Selection | DocumentSelection

    Checks whether the object is of type Selection or DocumentSelection.

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

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is Selection | DocumentSelection
  • inherited

    is( type ) → this is DocumentFragment

    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' ); // -> false
    

    Parameters

    type : 'documentFragment' | 'model:documentFragment'

    Returns

    this is DocumentFragment
  • inherited

    is( type ) → this is LiveRange

    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' ); // -> false
    

    Parameters

    type : 'liveRange' | 'model:liveRange'

    Returns

    this is LiveRange
  • inherited

    is( type ) → this is LivePosition

    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' ); // -> false
    

    Parameters

    type : 'livePosition' | 'model:livePosition'

    Returns

    this is LivePosition
  • inherited

    is( type, name ) → boolean

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

    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 | RootElement

    Checks whether the object is of type Node or its subclass.

    This method is useful when processing model objects that are of unknown type. For example, a function may return a DocumentFragment or a Node 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 view 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:

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

    By 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 precise
    

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is Node | Text | Element | RootElement
  • isAfter( node ) → boolean

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean
  • isAttached() → boolean

    Returns true if the node is inside a document root that is attached to the document.

    Returns

    boolean
  • isBefore( node ) → boolean

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean
  • toJSON() → unknown

    Converts Node to plain object and returns it.

    Returns

    unknown

    Node converted to plain object.

  • internal

    _clearAttributes() → void

    Removes all attributes from the node.

    Returns

    void

    Related:

  • internal

    _clone( [ _deep ] ) → Node

    Creates a copy of this node, that is a node with exactly same attributes, and returns it.

    Parameters

    [ _deep ] : boolean

    Returns

    Node

    Node with same attributes as this node.

  • internal

    _remove() → void

    Removes this node from it's parent.

    Returns

    void

    Related:

  • internal

    _removeAttribute( key ) → boolean

    Removes an attribute with given key from the node.

    Parameters

    key : string

    Key of attribute to remove.

    Returns

    boolean

    true if the attribute was set on the element, false otherwise.

    Related:

  • internal

    _setAttribute( key, value ) → void

    Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.

    Parameters

    key : string

    Key of attribute to set.

    value : unknown

    Attribute value.

    Returns

    void

    Related:

  • internal

    _setAttributesTo( attrs ) → void

    Removes all attributes from the node and sets given attributes.

    Parameters

    attrs : NodeAttributes

    Attributes to set. See toMap for a list of accepted values.

    Returns

    void

    Related: