Class

RootElement (engine/model)

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

class

Type of Element that is a root of a model tree.

Filtering

Properties

  • childCount : Number

    readonly inherited

    Number of this element's children.

  • document : Document | null

    readonly

    Document that owns this root element.

  • endOffset : Number | null

    readonly inherited

    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.

  • index : Number | null

    readonly inherited

    Index of this node in it's 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.

  • isEmpty : Boolean

    readonly inherited

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

  • maxOffset : Number

    readonly inherited

    Sum of offset sizes of all of this element's children.

  • name : String

    readonly inherited

    Element name.

  • nextSibling : Node | null

    readonly inherited

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

  • offsetSize : Number

    readonly inherited

    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.

  • parent : Element | DocumentFragment | null

    readonly inherited

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

  • previousSibling : Node | null

    readonly inherited

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

  • root : Node | DocumentFragment

    readonly inherited

    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.

  • rootName : String

    readonly

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

  • startOffset : Number | null

    readonly inherited

    Offset at which this node starts in it's parent. It is equal to the sum of offsetSize of all it's 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.

  • _attrs : Map

    private inherited

    Attributes set on this node.

  • _children : NodeList

    private inherited

    List of children nodes.

  • _document : Document

    private

    Document that is an owner of this root.

Methods

  • constructor( document, name, [ rootName ] )

    Creates root element.

    Parameters

    document : Document

    Document that is an owner of this root.

    name : String

    Node name.

    [ rootName ] : String

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

    Defaults to 'main'

  • findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | null

    inherited

    Returns the parent element of the given name. Returns null if the element is not inside the desired parent.

    Parameters

    parentName : String

    The name of the parent element to find.

    [ options ] : Object

    Options object.

    Properties
    [ options.includeSelf ] : Boolean

    When set to true this node will be also included while searching.

    Defaults to false

    Returns

    Element | null
  • getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array

    inherited

    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.

    Defaults to false

    [ 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 false

    Returns

    Array

    Array with ancestors.

  • getAttribute( key ) → *

    inherited

    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

    *

    Attribute value or undefined.

  • getAttributeKeys() → Iterable.<String>

    inherited

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

    Returns

    Iterable.<String>
  • getAttributes() → Iterable.<*>

    inherited

    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

    Iterable.<*>
  • getChild( index ) → Node

    inherited

    Gets the child at the given index.

    Parameters

    index : Number

    Index of child.

    Returns

    Node

    Child node.

  • getChildIndex( node ) → Number

    inherited

    Returns an index of the given child node. Returns null if given node is not a child of this element.

    Parameters

    node : Node

    Child node to look for.

    Returns

    Number

    Child node's index in this element.

  • getChildStartOffset( node ) → Number

    inherited

    Returns the starting offset of given child. Starting offset is equal to the sum of offset sizes of all node's siblings that are before it. Returns null if given node is not a child of this element.

    Parameters

    node : Node

    Child node to look for.

    Returns

    Number

    Child node's starting offset.

  • getChildren() → Iterable.<Node>

    inherited

    Returns an iterator that iterates over all of this element's children.

    Returns

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

    inherited

    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 false

    Returns

    Element | DocumentFragment | null
  • getNodeByPath( relativePath ) → Node

    inherited

    Returns a descendant node by its path relative to this element.

    // <this>a<b>c</b></this>
    this.getNodeByPath( [ 0 ] );     // -> "a"
    this.getNodeByPath( [ 1 ] );     // -> <b>
    this.getNodeByPath( [ 1, 0 ] );  // -> "c"

    Parameters

    relativePath : Array.<Number>

    Path of the node to find, relative to this element.

    Returns

    Node
  • getPath() → Array.<Number>

    inherited

    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>

    The path.

  • hasAttribute( key ) → Boolean

    inherited

    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.

  • is( type ) → Boolean

    inherited

    Checks whether this object is of the given type.

    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
    

    The list of model objects which implement the is() method:

    Parameters

    type : String

    Type to check.

    Returns

    Boolean
  • isAfter( node ) → Boolean

    inherited

    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

    inherited

    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

    inherited

    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
  • offsetToIndex( offset ) → Number

    inherited

    Returns index of a node that occupies given offset. If given offset is too low, returns 0. If given offset is too high, returns index after last child.

    const textNode = new Text( 'foo' );
    const pElement = new Element( 'p' );
    const divElement = new Element( [ textNode, pElement ] );
    divElement.offsetToIndex( -1 ); // Returns 0, because offset is too low.
    divElement.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
    divElement.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
    divElement.offsetToIndex( 2 ); // Returns 0.
    divElement.offsetToIndex( 3 ); // Returns 1.
    divElement.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.

    Parameters

    offset : Number

    Offset to look for.

    Returns

    Number
  • toJSON() → Object

    inherited

    Converts Node to plain object and returns it.

    Returns

    Object

    Node converted to plain object.

  • _appendChild( nodes )

    protected inherited

    Inserts one or more nodes at the end of this element.

    Parameters

    nodes : Item | Iterable.<Item>

    Nodes to be inserted.

    Related:

  • _clearAttributes()

    protected inherited

    Removes all attributes from the node.

  • _clone( [ deep ] )

    protected inherited

    Creates a copy of this element and returns it. Created element has the same name and attributes as the original element. If clone is deep, the original element's children are also cloned. If not, then empty element is returned.

    Parameters

    [ deep ] : Boolean

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

    Defaults to false

  • _insertChild( index, items )

    protected inherited

    Inserts one or more nodes at the given index and sets parent of these nodes to this element.

    Parameters

    index : Number

    Index at which nodes should be inserted.

    items : Item | Iterable.<Item>

    Items to be inserted.

    Related:

  • _remove()

    protected inherited

    Removes this node from it's parent.

    Related:

  • _removeAttribute( key ) → Boolean

    protected inherited

    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:

  • _removeChildren( index, [ howMany ] ) → Array.<Node>

    protected inherited

    Removes one or more nodes starting at the given index and sets parent of these nodes to null.

    Parameters

    index : Number

    Index of the first node to remove.

    [ howMany ] : Number

    Number of nodes to remove.

    Defaults to 1

    Returns

    Array.<Node>

    Array containing removed nodes.

    Related:

  • _setAttribute( key, value )

    protected inherited

    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 : *

    Attribute value.

    Related:

  • _setAttributesTo( [ attrs ] )

    protected inherited

    Removes all attributes from the node and sets given attributes.

    Parameters

    [ attrs ] : Object

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

    Related:

Static methods

  • fromJSON( json ) → Element

    inherited static

    Creates an Element instance from given plain object (i.e. parsed JSON string). Converts Element children to proper nodes.

    Parameters

    json : Object

    Plain object to be converted to Element.

    Returns

    Element

    Element instance created using given plain object.