Home/CKEditor 5/API

RootElement (engine/model)

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

class

Hierarchy

Node
- Element
  - RootElement

See source

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

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

childCount : Number

readonly inherited

Number of this element's children.

See source
document : Document | null

readonly

Document that owns this root element.

See source
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.

See source
index : Number | null

readonly inherited

Index of this node in it's parent or null if the node has no parent.

See source

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.

See source
maxOffset : Number

readonly inherited

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

See source
name : String

readonly inherited

Element name.

See source
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.

See source
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.

See source
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.

See source
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.

See source
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.

See source
rootName : String

readonly

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

See source
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.

See source

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.

See source
_children : NodeList

private inherited

List of children nodes.

See source
_document : Document

private

Document that is an owner of this root.

See source

Methods

constructor( document, name, [ rootName ] )

Creates root element.

See source

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.

See source

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.

See source

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.

See source

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.

See source

Returns

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

inherited

Returns iterator that iterates over this node's attributes.

See source

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.

See source

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.

See source

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.

See source

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.

See source

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.

See source

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.

See source
```
// <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.

See source

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.

See source

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.

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

See source

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

See source

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

See source

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.

See source

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.

See source

Returns

Object

Node converted to plain object.
_appendChild( nodes )

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

See source
Parameters

nodes : Item | Iterable.<Item>

Nodes to be inserted.

Related:
- Writer#append
_clearAttributes()

protected inherited
Removes all attributes from the node.

See source
Related:
- Writer#clearAttributes
_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.

See source

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.

See source
Parameters

index : Number

Index at which nodes should be inserted.

items : Item | Iterable.<Item>

Items to be inserted.

Related:
- Writer#insert
_remove()

protected inherited
Removes this node from it's parent.

See source
Related:
- Writer#remove
_removeAttribute( key ) → Boolean

protected inherited
Removes an attribute with given key from the node.

See source
Parameters

key : String

Key of attribute to remove.

Returns

Boolean

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

Related:
- Writer#removeAttribute
_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.

See source
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:
- Writer#remove
_setAttribute( key, value )

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

See source
Parameters

key : String

Key of attribute to set.

value : *

Attribute value.

Related:
- Writer#setAttribute
_setAttributesTo( [ attrs ] )

protected inherited
Removes all attributes from the node and sets given attributes.

See source
Parameters

[ attrs ] : Object

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

Related:
- Writer#setAttributes

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.

See source

Parameters

json : Object

Plain object to be converted to Element.

Returns

Element

Element instance created using given plain object.

Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.

RootElement (engine/model)

Filtering

Properties

childCount : Numbermodule:engine/model/rootelement~RootElement#childCount

document : Document | nullmodule:engine/model/rootelement~RootElement#document

endOffset : Number | nullmodule:engine/model/rootelement~RootElement#endOffset

index : Number | nullmodule:engine/model/rootelement~RootElement#index

isEmpty : Booleanmodule:engine/model/rootelement~RootElement#isEmpty

maxOffset : Numbermodule:engine/model/rootelement~RootElement#maxOffset

name : Stringmodule:engine/model/rootelement~RootElement#name

nextSibling : Node | nullmodule:engine/model/rootelement~RootElement#nextSibling

offsetSize : Numbermodule:engine/model/rootelement~RootElement#offsetSize

parent : Element | DocumentFragment | nullmodule:engine/model/rootelement~RootElement#parent

previousSibling : Node | nullmodule:engine/model/rootelement~RootElement#previousSibling

root : Node | DocumentFragmentmodule:engine/model/rootelement~RootElement#root

rootName : Stringmodule:engine/model/rootelement~RootElement#rootName

startOffset : Number | nullmodule:engine/model/rootelement~RootElement#startOffset

_attrs : Mapmodule:engine/model/rootelement~RootElement#_attrs

_children : NodeListmodule:engine/model/rootelement~RootElement#_children

_document : Documentmodule:engine/model/rootelement~RootElement#_document

Methods

constructor( document, name, [ rootName ] )module:engine/model/rootelement~RootElement#constructor

Parameters

findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | nullmodule:engine/model/rootelement~RootElement#findAncestor

Parameters

Returns

getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Arraymodule:engine/model/rootelement~RootElement#getAncestors

Parameters

Returns

getAttribute( key ) → *module:engine/model/rootelement~RootElement#getAttribute

Parameters

Returns

getAttributeKeys() → Iterable.<String>module:engine/model/rootelement~RootElement#getAttributeKeys

Returns

getAttributes() → Iterable.<*>module:engine/model/rootelement~RootElement#getAttributes

Returns

getChild( index ) → Nodemodule:engine/model/rootelement~RootElement#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/model/rootelement~RootElement#getChildIndex

Parameters

Returns

getChildStartOffset( node ) → Numbermodule:engine/model/rootelement~RootElement#getChildStartOffset

Parameters

Returns

getChildren() → Iterable.<Node>module:engine/model/rootelement~RootElement#getChildren

Returns

getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | nullmodule:engine/model/rootelement~RootElement#getCommonAncestor

Parameters

Returns

getNodeByPath( relativePath ) → Nodemodule:engine/model/rootelement~RootElement#getNodeByPath

Parameters

Returns

getPath() → Array.<Number>module:engine/model/rootelement~RootElement#getPath

Returns

hasAttribute( key ) → Booleanmodule:engine/model/rootelement~RootElement#hasAttribute

Parameters

Returns

is( type ) → Booleanmodule:engine/model/rootelement~RootElement#is

Parameters

Returns

isAfter( node ) → Booleanmodule:engine/model/rootelement~RootElement#isAfter

Parameters

Returns

isAttached() → Booleanmodule:engine/model/rootelement~RootElement#isAttached

Returns

isBefore( node ) → Booleanmodule:engine/model/rootelement~RootElement#isBefore

Parameters

Returns

offsetToIndex( offset ) → Numbermodule:engine/model/rootelement~RootElement#offsetToIndex

Parameters

Returns

toJSON() → Objectmodule:engine/model/rootelement~RootElement#toJSON

Returns

_appendChild( nodes )module:engine/model/rootelement~RootElement#_appendChild

Parameters

Related:

_clearAttributes()module:engine/model/rootelement~RootElement#_clearAttributes

Related:

_clone( [ deep ] )module:engine/model/rootelement~RootElement#_clone

`childCount : Number`

`document : Document | null`

`endOffset : Number | null`

`index : Number | null`

`isEmpty : Boolean`

`maxOffset : Number`

`name : String`

`nextSibling : Node | null`

`offsetSize : Number`

`parent : Element | DocumentFragment | null`

`previousSibling : Node | null`

`root : Node | DocumentFragment`

`rootName : String`

`startOffset : Number | null`

`_attrs : Map`

`_children : NodeList`

`_document : Document`

`constructor( document, name, [ rootName ] )`

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

`getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array`

`getAttribute( key ) → *`

`getAttributeKeys() → Iterable.<String>`

`getAttributes() → Iterable.<*>`

`getChild( index ) → Node`

`getChildIndex( node ) → Number`

`getChildStartOffset( node ) → Number`

`getChildren() → Iterable.<Node>`

`getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null`

`getNodeByPath( relativePath ) → Node`

`getPath() → Array.<Number>`

`hasAttribute( key ) → Boolean`

`is( type ) → Boolean`

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`offsetToIndex( offset ) → Number`

`toJSON() → Object`

`_appendChild( nodes )`

`_clearAttributes()`

`_clone( [ deep ] )`

`_insertChild( index, items )`

`_remove()`

`_removeAttribute( key ) → Boolean`

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

`_setAttribute( key, value )`

`_setAttributesTo( [ attrs ] )`

`fromJSON( json ) → Element`