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 : numberreadonlymodule:engine/model/element~ModelElement#childCountNumber of this element's children.
document : null | ModelDocumentreadonlyinheritedmodule:engine/model/element~ModelElement#documentDocument that owns this root element.
endOffset : null | numberreadonlyinheritedmodule:engine/model/element~ModelElement#endOffsetOffset 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
nullif the node has no parent.index : null | numberreadonlyinheritedmodule:engine/model/element~ModelElement#indexIndex of this node in its parent or
nullif the node has no parent.isEmpty : booleanreadonlymodule:engine/model/element~ModelElement#isEmptyIs
trueif there are no nodes inside this element,falseotherwise.maxOffset : numberreadonlymodule:engine/model/element~ModelElement#maxOffsetSum of offset sizes of all of this element's children.
name : stringreadonlymodule:engine/model/element~ModelElement#nameElement name.
nextSibling : null | ModelNodereadonlyinheritedmodule:engine/model/element~ModelElement#nextSiblingNode's next sibling or
nullif the node is a last child of it's parent or if the node has no parent.offsetSize : numberreadonlyinheritedmodule:engine/model/element~ModelElement#offsetSizeOffset 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
offsetSizegreater than1, position can be placed between that node start and end.offsetSizegreater than1is for nodes that represents more than one entity, i.e. a text node.parent : null | ModelElement | ModelDocumentFragmentreadonlyinheritedmodule:engine/model/element~ModelElement#parentParent of this node. It could be
ModelElementorModelDocumentFragment. Equals tonullif the node has no parent.previousSibling : null | ModelNodereadonlyinheritedmodule:engine/model/element~ModelElement#previousSiblingNode's previous sibling or
nullif the node is a first child of it's parent or if the node has no parent.root : ModelNode | ModelDocumentFragmentreadonlyinheritedmodule:engine/model/element~ModelElement#rootThe 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'srootis equal to thatDocumentFragment.rootName : undefined | stringreadonlyinheritedmodule:engine/model/element~ModelElement#rootNameUnique root name used to identify this root element by
ModelDocument.startOffset : null | numberreadonlyinheritedmodule:engine/model/element~ModelElement#startOffsetOffset at which this node starts in its parent. It is equal to the sum of offsetSize of all its previous siblings. Equals to
nullif node has no parent._index : null | numberinternalinheritedmodule:engine/model/element~ModelElement#_indexIndex of this node in its parent or
nullif the node has no parent._startOffset : null | numberinternalinheritedmodule:engine/model/element~ModelElement#_startOffsetOffset at which this node starts in its parent or
nullif the node has no parent._children : ModelNodeListprivatereadonlymodule:engine/model/element~ModelElement#_childrenList of children nodes.
Methods
constructor( name, [ attrs ], [ children ] )internalmodule:engine/model/element~ModelElement#constructorCreates a model element.
Note: Constructor of this class shouldn't be used directly in the code. Use the
createElementmethod instead.Parameters
name : stringElement's name.
[ attrs ] : ModelNodeAttributesElement's attributes. See
toMapfor 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 | ModelElementmodule:engine/model/element~ModelElement#findAncestorReturns the parent element of the given name. Returns null if the element is not inside the desired parent.
Parameters
parentName : stringThe name of the parent element to find.
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
truethis 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#getAncestorsReturns ancestors array of this node.
Parameters
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
truethis node will be also included in parent's array.[ options.parentFirst ] : booleanWhen 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 ) → unknowninheritedmodule:engine/model/element~ModelElement#getAttributeGets an attribute value for given key or
undefinedif that attribute is not set on node.Parameters
key : stringKey of attribute to look for.
Returns
unknownAttribute value or
undefined.
getAttributeKeys() → IterableIterator<string>inheritedmodule:engine/model/element~ModelElement#getAttributeKeysReturns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
getAttributes() → IterableIterator<tuple>inheritedmodule:engine/model/element~ModelElement#getAttributesReturns 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
Mapobject and also can be passed inNodeconstructor.Returns
IterableIterator<tuple>
module:engine/model/element~ModelElement#getChildGets the child at the given index. Returns
nullif incorrect index was passed.Parameters
index : numberIndex in this element.
Returns
null | ModelNodeChild node.
getChildAtOffset( offset ) → null | ModelNodemodule:engine/model/element~ModelElement#getChildAtOffsetGets the child at the given offset. Returns
nullif incorrect index was passed.Parameters
offset : numberOffset in this element.
Returns
null | ModelNodeChild node.
getChildIndex( node ) → null | numbermodule:engine/model/element~ModelElement#getChildIndexReturns an index of the given child node. Returns
nullif given node is not a child of this element.Parameters
node : ModelNodeChild node to look for.
Returns
null | numberChild node's index in this element.
getChildStartOffset( node ) → null | numbermodule:engine/model/element~ModelElement#getChildStartOffsetReturns 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
nullif given node is not a child of this element.Parameters
node : ModelNodeChild node to look for.
Returns
null | numberChild node's starting offset.
getChildren() → IterableIterator<ModelNode>module:engine/model/element~ModelElement#getChildrenReturns an iterator that iterates over all of this element's children.
Returns
IterableIterator<ModelNode>
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | ModelElement | ModelDocumentFragmentinheritedmodule:engine/model/element~ModelElement#getCommonAncestorReturns a
ModelElementorModelDocumentFragmentwhich is a common ancestor of both nodes.Parameters
node : ModelNodeThe second node.
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
trueboth 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 ) → ModelNodemodule:engine/model/element~ModelElement#getNodeByPathReturns 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"Copy codeParameters
relativePath : Array<number>Path of the node to find, relative to this element.
Returns
getPath() → Array<number>inheritedmodule:engine/model/element~ModelElement#getPathGets 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 [].Copy codeReturns
Array<number>
hasAttribute( key ) → booleaninheritedmodule:engine/model/element~ModelElement#hasAttributeChecks if the node has an attribute with given key.
Parameters
key : stringKey of attribute to check.
Returns
booleantrueif attribute with given key is set on node,falseotherwise.
is( type ) → this is ModelElement | ModelRootElementinheritedmodule:engine/model/element~ModelElement#is:ELEMENTChecks whether the object is of type
ModelElementor 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' ); // -> falseCopy codeAssuming 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' ); -> falseCopy codeParameters
type : 'element' | 'model:element'
Returns
this is ModelElement | ModelRootElement
module:engine/model/element~ModelElement#is:TEXTChecks 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' ); // -> falseCopy codeNote: 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 ModelRootElementinheritedmodule:engine/model/element~ModelElement#is:ROOT_ELEMENTChecks 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' ); // -> falseCopy codeAssuming that the object being checked is an element, you can also check its name:
rootElement.is( 'rootElement', '$root' ); // -> same as aboveCopy codeParameters
type : 'rootElement' | 'model:rootElement'
Returns
this is ModelRootElement
is( type ) → this is ModelLiveRangeinheritedmodule:engine/model/element~ModelElement#is:LIVE_RANGEChecks 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' ); // -> falseCopy codeParameters
type : 'liveRange' | 'model:liveRange'
Returns
this is ModelLiveRange
is( type ) → this is ModelDocumentFragmentinheritedmodule:engine/model/element~ModelElement#is:DOCUMENT_FRAGMENTChecks 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' ); // -> falseCopy codeParameters
type : 'documentFragment' | 'model:documentFragment'
Returns
this is ModelDocumentFragment
is( type ) → this is ModelRange | ModelLiveRangeinheritedmodule:engine/model/element~ModelElement#is:RANGEChecks whether the object is of type
ModelRangeor its subclass.range.is( 'range' ); // -> true range.is( 'model:range' ); // -> true range.is( 'view:range' ); // -> false range.is( 'documentSelection' ); // -> falseCopy codeParameters
type : 'range' | 'model:range'
Returns
this is ModelRange | ModelLiveRange
is( type ) → this is ModelLivePositioninheritedmodule:engine/model/element~ModelElement#is:LIVE_POSITIONChecks 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' ); // -> falseCopy codeParameters
type : 'livePosition' | 'model:livePosition'
Returns
this is ModelLivePosition
is( type ) → this is ModelPosition | ModelLivePositioninheritedmodule:engine/model/element~ModelElement#is:POSITIONChecks whether the object is of type
ModelPositionor its subclass.position.is( 'position' ); // -> true position.is( 'model:position' ); // -> true position.is( 'view:position' ); // -> false position.is( 'documentSelection' ); // -> falseCopy codeParameters
type : 'position' | 'model:position'
Returns
this is ModelPosition | ModelLivePosition
module:engine/model/element~ModelElement#is:MARKERis( type, name ) → booleaninheritedmodule:engine/model/element~ModelElement#is:ROOT_ELEMENT_NAMEChecks whether the object is of type
ModelRootElementand has the specifiedname.rootElement.is( 'rootElement', '$root' );Copy codeType parameters
N : extends string
Parameters
type : 'rootElement' | 'model:rootElement'name : N
Returns
boolean
is( type, name ) → booleaninheritedmodule:engine/model/element~ModelElement#is:ELEMENT_NAMEChecks whether the object is of type
ModelElementor its subclass and has the specifiedname.element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element text.is( 'element', 'imageBlock' ); -> falseCopy codeType parameters
N : extends string
Parameters
type : 'element' | 'model:element'name : N
Returns
boolean
is( type ) → this is ModelTextProxyinheritedmodule:engine/model/element~ModelElement#is:TEXT_PROXYChecks whether the object is of type
ModelTextProxy.textProxy.is( '$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> false textProxy.is( 'range' ); // -> falseCopy codeNote: 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 ModelDocumentSelectioninheritedmodule:engine/model/element~ModelElement#is:DOCUMENT_SELECTIONChecks 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' ); // -> falseCopy codeParameters
type : 'documentSelection' | 'model:documentSelection'
Returns
this is ModelDocumentSelection
is( type ) → this is ModelSelection | ModelDocumentSelectioninheritedmodule:engine/model/element~ModelElement#is:SELECTIONChecks whether the object is of type
ModelSelectionorModelDocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'model:selection' ); // -> true selection.is( 'view:selection' ); // -> false selection.is( 'range' ); // -> falseCopy codeParameters
type : 'selection' | 'model:selection'
Returns
this is ModelSelection | ModelDocumentSelection
is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElementinheritedmodule:engine/model/element~ModelElement#is:NODEChecks whether the object is of type
ModelNodeor its subclass.This method is useful when processing model objects that are of unknown type. For example, a function may return a
ModelDocumentFragmentor aModelNodethat 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 fragmentCopy codeSince 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' ); // -> falseCopy codeBy 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 preciseCopy codeParameters
type : 'node' | 'model:node'
Returns
this is ModelNode | ModelText | ModelElement | ModelRootElement
isAfter( node ) → booleaninheritedmodule:engine/model/element~ModelElement#isAfterReturns whether this node is after given node.
falseis returned if nodes are in different trees (for example, in differentModelDocumentFragments).Parameters
node : ModelNodeNode to compare with.
Returns
boolean
isAttached() → booleaninheritedmodule:engine/model/element~ModelElement#isAttachedReturns
trueif the node is inside a document root that is attached to the document.Returns
boolean
isBefore( node ) → booleaninheritedmodule:engine/model/element~ModelElement#isBeforeReturns whether this node is before given node.
falseis returned if nodes are in different trees (for example, in differentModelDocumentFragments).Parameters
node : ModelNodeNode to compare with.
Returns
boolean
offsetToIndex( offset ) → numbermodule:engine/model/element~ModelElement#offsetToIndexReturns 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.Copy codeParameters
offset : number
Returns
number
toJSON() → unknownmodule:engine/model/element~ModelElement#toJSONConverts
Elementinstance to plain object and returns it. Takes care of converting all of this element's children.Returns
unknownElementinstance converted to plain object.
_appendChild( nodes ) → voidinternalmodule:engine/model/element~ModelElement#_appendChild_clearAttributes() → voidinternalinheritedmodule:engine/model/element~ModelElement#_clearAttributesRemoves all attributes from the node.
Returns
void
Related:
_clone( deep ) → ModelElementinternalmodule:engine/model/element~ModelElement#_cloneCreates 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 : booleanIf set to
trueclones element and all its children recursively. When set tofalse, element will be cloned without any child.Defaults to
false
Returns
_insertChild( index, items ) → voidinternalmodule:engine/model/element~ModelElement#_insertChild_remove() → voidinternalinheritedmodule:engine/model/element~ModelElement#_removeRemoves this node from its parent.
Returns
void
Related:
_removeAttribute( key ) → booleaninternalinheritedmodule:engine/model/element~ModelElement#_removeAttributeRemoves an attribute with given key from the node.
Parameters
key : stringKey of attribute to remove.
Returns
booleantrueif the attribute was set on the element,falseotherwise.
Related:
_removeChildren( index, howMany ) → Array<ModelNode>internalmodule:engine/model/element~ModelElement#_removeChildren_removeChildrenArray( nodes ) → voidinternalmodule:engine/model/element~ModelElement#_removeChildrenArray_setAttribute( key, value ) → voidinternalinheritedmodule:engine/model/element~ModelElement#_setAttributeSets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
Parameters
key : stringKey of attribute to set.
value : unknownAttribute value.
Returns
void
Related:
_setAttributesTo( attrs ) → voidinternalinheritedmodule:engine/model/element~ModelElement#_setAttributesToRemoves all attributes from the node and sets given attributes.
Parameters
attrs : ModelNodeAttributesAttributes to set. See
toMapfor a list of accepted values.
Returns
void
Related:
Static methods
fromJSON( json ) → ModelElementstaticmodule:engine/model/element~ModelElement.fromJSONCreates an
Elementinstance from given plain object (i.e. parsed JSON string). ConvertsElementchildren to proper nodes.Parameters
json : anyPlain object to be converted to
Element.
Returns
ModelElementElementinstance created using given plain object.