RootElement (engine/model)
@ckeditor/ckeditor5-engine/src/model/rootelement
Type of Element
that is a root of a model tree.
Filtering
Properties
-
Number of this element's children.
-
Document that owns this root element.
-
Offset at which this node ends in its 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 of this node in its parent or
null
if the node has no parent. -
Is
true
if there are no nodes inside this element,false
otherwise. -
Sum of offset sizes of all of this element's children.
-
Element name.
-
Node's next sibling or
null
if 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 its parent. It is important for position. When node has
offsetSize
greater than1
, position can be placed between that node start and end.offsetSize
greater than1
is for nodes that represents more than one entity, i.e. a text node. -
readonly inherited
parent : null | Element | DocumentFragment
module:engine/model/rootelement~RootElement#parent
Parent of this node. It could be
Element
orDocumentFragment
. Equals tonull
if the node has no parent. -
readonly inherited
previousSibling : null | Node
module:engine/model/rootelement~RootElement#previousSibling
Node's previous sibling or
null
if 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'sroot
is equal to thatDocumentFragment
. -
Unique root name used to identify this root element by
Document
. -
readonly inherited
startOffset : null | number
module:engine/model/rootelement~RootElement#startOffset
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. -
Index of this node in its parent or
null
if the node has no parent. -
Informs if the root element is loaded (default).
-
internal inherited
_startOffset : null | number
module:engine/model/rootelement~RootElement#_startOffset
Offset at which this node starts in its parent or
null
if the node has no parent. -
Document that is an owner of this root.
Methods
-
constructor( document, name, rootName )
module:engine/model/rootelement~RootElement#constructor
Creates root element.
Parameters
-
inherited
findAncestor( parentName, options = { [options.includeSelf] } ) → null | Element
module:engine/model/rootelement~RootElement#findAncestor
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
{}
Returns
null | Element
-
inherited
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>
module:engine/model/rootelement~RootElement#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.
-
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
.
-
inherited
getAttributeKeys() → IterableIterator<string>
module:engine/model/rootelement~RootElement#getAttributeKeys
Returns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
-
inherited
getAttributes() → IterableIterator<tuple>
module:engine/model/rootelement~RootElement#getAttributes
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 inNode
constructor.Returns
IterableIterator<tuple>
-
Gets the child at the given index. Returns
null
if incorrect index was passed.Parameters
index : number
Index in this element.
Returns
null | Node
Child node.
-
inherited
getChildAtOffset( offset ) → null | Node
module:engine/model/rootelement~RootElement#getChildAtOffset
Gets the child at the given offset. Returns
null
if incorrect index was passed.Parameters
offset : number
Offset in this element.
Returns
null | Node
Child node.
-
inherited
getChildIndex( node ) → null | number
module:engine/model/rootelement~RootElement#getChildIndex
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
null | number
Child node's index in this element.
-
inherited
getChildStartOffset( node ) → null | number
module:engine/model/rootelement~RootElement#getChildStartOffset
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
null | number
Child node's starting offset.
-
inherited
getChildren() → IterableIterator<Node>
module:engine/model/rootelement~RootElement#getChildren
Returns an iterator that iterates over all of this element's children.
Returns
IterableIterator<Node>
-
inherited
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragment
module:engine/model/rootelement~RootElement#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
-
inherited
getNodeByPath( relativePath ) → Node
module:engine/model/rootelement~RootElement#getNodeByPath
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
-
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>
-
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
module:engine/model/rootelement~RootElement#is:ELEMENT
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
-
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 RootElement
module:engine/model/rootelement~RootElement#is:ROOT_ELEMENT
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
-
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 Range | LiveRange
module:engine/model/rootelement~RootElement#is:RANGE
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
-
inherited
is( type ) → this is LivePosition
module:engine/model/rootelement~RootElement#is:LIVE_POSITION
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 ) → this is Position | LivePosition
module:engine/model/rootelement~RootElement#is:POSITION
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 DocumentFragment
module:engine/model/rootelement~RootElement#is:DOCUMENT_FRAGMENT
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
-
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, name ) → boolean
module:engine/model/rootelement~RootElement#is:ROOT_ELEMENT_NAME
Checks whether the object is of type
RootElement
and has the specifiedname
.rootElement.is( 'rootElement', '$root' );
Type parameters
N : extends string
Parameters
type : 'rootElement' | 'model:rootElement'
name : N
Returns
boolean
-
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.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 DocumentSelection
module:engine/model/rootelement~RootElement#is:DOCUMENT_SELECTION
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 ) → this is Selection | DocumentSelection
module:engine/model/rootelement~RootElement#is:SELECTION
Checks whether the object is of type
Selection
orDocumentSelection
.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 Node | Text | Element | RootElement
module:engine/model/rootelement~RootElement#is:NODE
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 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 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' ); // -> 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
-
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/model/rootelement~RootElement#isAttached
Informs if the root element is currently attached to the document, or not.
A detached root is equivalent to being removed and cannot contain any children or markers.
By default, a newly added root is attached. It can be detached using
Writer#detachRoot
. A detached root can be re-attached again usingWriter#addRoot
.Returns
boolean
-
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
-
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
Returns
number
-
toJSON() → unknown
module:engine/model/rootelement~RootElement#toJSON
Converts
RootElement
instance tostring
containing its name.Returns
unknown
RootElement
instance converted tostring
.
-
internal inherited
_appendChild( nodes ) → void
module:engine/model/rootelement~RootElement#_appendChild
-
internal inherited
_clearAttributes() → void
module:engine/model/rootelement~RootElement#_clearAttributes
-
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 tofalse
, element will be cloned without any child.Defaults to
false
Returns
-
internal inherited
_insertChild( index, items ) → void
module:engine/model/rootelement~RootElement#_insertChild
-
-
internal inherited
_removeAttribute( key ) → boolean
module:engine/model/rootelement~RootElement#_removeAttribute
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 inherited
_removeChildren( index, howMany ) → Array<Node>
module:engine/model/rootelement~RootElement#_removeChildren
-
internal inherited
_setAttribute( key, value ) → void
module:engine/model/rootelement~RootElement#_setAttribute
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 inherited
_setAttributesTo( attrs ) → void
module:engine/model/rootelement~RootElement#_setAttributesTo
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:
Static methods
-
Creates an
Element
instance from given plain object (i.e. parsed JSON string). ConvertsElement
children to proper nodes.Parameters
json : any
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 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.