ModelElement
Model element. Type of node that has a name and child nodes.
Important: see ModelNode
to read about restrictions using Element
and Node
API.
Properties
-
childCount : number
readonlymodule:engine/model/element~ModelElement#childCount
Number of this element's children.
-
document : null | ModelDocument
readonlyinheritedmodule:engine/model/element~ModelElement#document
Document that owns this root element.
-
endOffset : null | number
readonlyinheritedmodule:engine/model/element~ModelElement#endOffset
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 : null | number
readonlyinheritedmodule:engine/model/element~ModelElement#index
Index of this node in its parent or
null
if the node has no parent. -
isEmpty : boolean
readonlymodule:engine/model/element~ModelElement#isEmpty
Is
true
if there are no nodes inside this element,false
otherwise. -
maxOffset : number
readonlymodule:engine/model/element~ModelElement#maxOffset
Sum of offset sizes of all of this element's children.
-
name : string
readonlymodule:engine/model/element~ModelElement#name
Element name.
-
nextSibling : null | ModelNode
readonlyinheritedmodule:engine/model/element~ModelElement#nextSibling
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
readonlyinheritedmodule:engine/model/element~ModelElement#offsetSize
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. -
parent : null | ModelElement | ModelDocumentFragment
readonlyinheritedmodule:engine/model/element~ModelElement#parent
Parent of this node. It could be
ModelElement
orModelDocumentFragment
. Equals tonull
if the node has no parent. -
previousSibling : null | ModelNode
readonlyinheritedmodule:engine/model/element~ModelElement#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. -
root : ModelNode | ModelDocumentFragment
readonlyinheritedmodule:engine/model/element~ModelElement#root
The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part of
ModelDocumentFragment
, it'sroot
is equal to thatDocumentFragment
. -
rootName : undefined | string
readonlyinheritedmodule:engine/model/element~ModelElement#rootName
Unique root name used to identify this root element by
ModelDocument
. -
startOffset : null | number
readonlyinheritedmodule:engine/model/element~ModelElement#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 : null | number
internalinheritedmodule:engine/model/element~ModelElement#_index
Index of this node in its parent or
null
if the node has no parent. -
_startOffset : null | number
internalinheritedmodule:engine/model/element~ModelElement#_startOffset
Offset at which this node starts in its parent or
null
if the node has no parent. -
_children : ModelNodeList
privatereadonlymodule:engine/model/element~ModelElement#_children
List of children nodes.
Methods
-
constructor( name, [ attrs ], [ children ] )
internalmodule:engine/model/element~ModelElement#constructor
Creates a model element.
Note: Constructor of this class shouldn't be used directly in the code. Use the
createElement
method instead.Parameters
name : string
Element's name.
[ attrs ] : ModelNodeAttributes
Element's attributes. See
toMap
for a list of accepted values.[ children ] : string | ModelItem | Iterable<( string | ModelItem )>
One or more nodes to be inserted as children of created element.
-
findAncestor( parentName, options = { [options.includeSelf] } ) → null | ModelElement
module:engine/model/element~ModelElement#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 | ModelElement
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<ModelNode | ModelDocumentFragment>
inheritedmodule:engine/model/element~ModelElement#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<ModelNode | ModelDocumentFragment>
Array with ancestors.
-
getAttribute( key ) → unknown
inheritedmodule:engine/model/element~ModelElement#getAttribute
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>
inheritedmodule:engine/model/element~ModelElement#getAttributeKeys
Returns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
-
getAttributes() → IterableIterator<tuple>
inheritedmodule:engine/model/element~ModelElement#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>
-
module:engine/model/element~ModelElement#getChild
Gets the child at the given index. Returns
null
if incorrect index was passed.Parameters
index : number
Index in this element.
Returns
null | ModelNode
Child node.
-
getChildAtOffset( offset ) → null | ModelNode
module:engine/model/element~ModelElement#getChildAtOffset
Gets the child at the given offset. Returns
null
if incorrect index was passed.Parameters
offset : number
Offset in this element.
Returns
null | ModelNode
Child node.
-
getChildIndex( node ) → null | number
module:engine/model/element~ModelElement#getChildIndex
Returns an index of the given child node. Returns
null
if given node is not a child of this element.Parameters
node : ModelNode
Child node to look for.
Returns
null | number
Child node's index in this element.
-
getChildStartOffset( node ) → null | number
module:engine/model/element~ModelElement#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 : ModelNode
Child node to look for.
Returns
null | number
Child node's starting offset.
-
getChildren() → IterableIterator<ModelNode>
module:engine/model/element~ModelElement#getChildren
Returns an iterator that iterates over all of this element's children.
Returns
IterableIterator<ModelNode>
-
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | ModelElement | ModelDocumentFragment
inheritedmodule:engine/model/element~ModelElement#getCommonAncestor
Returns a
ModelElement
orModelDocumentFragment
which is a common ancestor of both nodes.Parameters
node : ModelNode
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 | ModelElement | ModelDocumentFragment
-
getNodeByPath( relativePath ) → ModelNode
module:engine/model/element~ModelElement#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
-
getPath() → Array<number>
inheritedmodule:engine/model/element~ModelElement#getPath
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 ModelElement( 'h1', null, new Text( 'header' ) ); const p = new ModelElement( 'p', null, [ abc, foo ] ); const div = new ModelElement( '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
inheritedmodule:engine/model/element~ModelElement#hasAttribute
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 ) → this is ModelElement | ModelRootElement
inheritedmodule:engine/model/element~ModelElement#is:ELEMENT
Checks whether the object is of type
ModelElement
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 ModelElement | ModelRootElement
-
module:engine/model/element~ModelElement#is:TEXT
Checks whether the object is of type
ModelText
.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 ModelText
-
is( type ) → this is ModelRootElement
inheritedmodule:engine/model/element~ModelElement#is:ROOT_ELEMENT
Checks whether the object is of type
ModelRootElement
.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 ModelRootElement
-
is( type ) → this is ModelLiveRange
inheritedmodule:engine/model/element~ModelElement#is:LIVE_RANGE
Checks whether the object is of type
ModelLiveRange
.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 ModelLiveRange
-
is( type ) → this is ModelDocumentFragment
inheritedmodule:engine/model/element~ModelElement#is:DOCUMENT_FRAGMENT
Checks whether the object is of type
ModelDocumentFragment
.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 ModelDocumentFragment
-
is( type ) → this is ModelRange | ModelLiveRange
inheritedmodule:engine/model/element~ModelElement#is:RANGE
Checks whether the object is of type
ModelRange
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 ModelRange | ModelLiveRange
-
is( type ) → this is ModelLivePosition
inheritedmodule:engine/model/element~ModelElement#is:LIVE_POSITION
Checks whether the object is of type
ModelLivePosition
.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 ModelLivePosition
-
is( type ) → this is ModelPosition | ModelLivePosition
inheritedmodule:engine/model/element~ModelElement#is:POSITION
Checks whether the object is of type
ModelPosition
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 ModelPosition | ModelLivePosition
-
module:engine/model/element~ModelElement#is:MARKER
-
is( type, name ) → boolean
inheritedmodule:engine/model/element~ModelElement#is:ROOT_ELEMENT_NAME
Checks whether the object is of type
ModelRootElement
and has the specifiedname
.rootElement.is( 'rootElement', '$root' );
Type parameters
N : extends string
Parameters
type : 'rootElement' | 'model:rootElement'
name : N
Returns
boolean
-
is( type, name ) → boolean
inheritedmodule:engine/model/element~ModelElement#is:ELEMENT_NAME
Checks whether the object is of type
ModelElement
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
-
is( type ) → this is ModelTextProxy
inheritedmodule:engine/model/element~ModelElement#is:TEXT_PROXY
Checks whether the object is of type
ModelTextProxy
.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 ModelTextProxy
-
is( type ) → this is ModelDocumentSelection
inheritedmodule:engine/model/element~ModelElement#is:DOCUMENT_SELECTION
Checks whether the object is of type
ModelDocumentSelection
.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 ModelDocumentSelection
-
is( type ) → this is ModelSelection | ModelDocumentSelection
inheritedmodule:engine/model/element~ModelElement#is:SELECTION
Checks whether the object is of type
ModelSelection
orModelDocumentSelection
.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 ModelSelection | ModelDocumentSelection
-
is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement
inheritedmodule:engine/model/element~ModelElement#is:NODE
Checks whether the object is of type
ModelNode
or its subclass.This method is useful when processing model objects that are of unknown type. For example, a function may return a
ModelDocumentFragment
or aModelNode
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 ModelNode | ModelText | ModelElement | ModelRootElement
-
isAfter( node ) → boolean
inheritedmodule:engine/model/element~ModelElement#isAfter
Returns whether this node is after given node.
false
is returned if nodes are in different trees (for example, in differentModelDocumentFragment
s).Parameters
node : ModelNode
Node to compare with.
Returns
boolean
-
isAttached() → boolean
inheritedmodule:engine/model/element~ModelElement#isAttached
Returns
true
if the node is inside a document root that is attached to the document.Returns
boolean
-
isBefore( node ) → boolean
inheritedmodule:engine/model/element~ModelElement#isBefore
Returns whether this node is before given node.
false
is returned if nodes are in different trees (for example, in differentModelDocumentFragment
s).Parameters
node : ModelNode
Node to compare with.
Returns
boolean
-
offsetToIndex( offset ) → number
module:engine/model/element~ModelElement#offsetToIndex
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/element~ModelElement#toJSON
Converts
Element
instance to plain object and returns it. Takes care of converting all of this element's children.Returns
unknown
Element
instance converted to plain object.
-
_appendChild( nodes ) → void
internalmodule:engine/model/element~ModelElement#_appendChild
-
_clearAttributes() → void
internalinheritedmodule:engine/model/element~ModelElement#_clearAttributes
Removes all attributes from the node.
Returns
void
Related:
-
_clone( deep ) → ModelElement
internalmodule:engine/model/element~ModelElement#_clone
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
-
_insertChild( index, items ) → void
internalmodule:engine/model/element~ModelElement#_insertChild
-
_remove() → void
internalinheritedmodule:engine/model/element~ModelElement#_remove
Removes this node from its parent.
Returns
void
Related:
-
_removeAttribute( key ) → boolean
internalinheritedmodule:engine/model/element~ModelElement#_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:
-
_removeChildren( index, howMany ) → Array<ModelNode>
internalmodule:engine/model/element~ModelElement#_removeChildren
-
_removeChildrenArray( nodes ) → void
internalmodule:engine/model/element~ModelElement#_removeChildrenArray
-
_setAttribute( key, value ) → void
internalinheritedmodule:engine/model/element~ModelElement#_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:
-
_setAttributesTo( attrs ) → void
internalinheritedmodule:engine/model/element~ModelElement#_setAttributesTo
Removes all attributes from the node and sets given attributes.
Parameters
attrs : ModelNodeAttributes
Attributes to set. See
toMap
for a list of accepted values.
Returns
void
Related:
Static methods
-
fromJSON( json ) → ModelElement
staticmodule:engine/model/element~ModelElement.fromJSON
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
ModelElement
Element
instance created using given plain object.