Sign up (with export icon)

ModelElement

Api-class icon class

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

Methods

  • Chevron-right icon

    constructor( name, [ attrs ], [ children ] )
    internal

    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.

  • Chevron-right icon

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

    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
  • Chevron-right icon

    getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<ModelNode | ModelDocumentFragment>
    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.

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

  • Chevron-right icon

    getAttribute( key ) → unknown
    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

    unknown

    Attribute value or undefined.

  • Chevron-right icon

    getAttributeKeys() → IterableIterator<string>
    inherited

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

    Returns

    IterableIterator<string>
  • Chevron-right icon

    getAttributes() → IterableIterator<tuple>
    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

    IterableIterator<tuple>
  • Chevron-right icon

    getChild( index ) → null | ModelNode

    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.

  • Chevron-right icon

    getChildAtOffset( offset ) → null | ModelNode

    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.

  • Chevron-right icon

    getChildIndex( node ) → null | number

    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.

  • Chevron-right icon

    getChildStartOffset( node ) → null | number

    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.

  • Chevron-right icon

    getChildren() → IterableIterator<ModelNode>

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

    Returns

    IterableIterator<ModelNode>
  • Chevron-right icon

    getCommonAncestor( node, options = { [options.includeSelf] } ) → null | ModelElement | ModelDocumentFragment
    inherited

    Returns a ModelElement or ModelDocumentFragment 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
  • Chevron-right icon

    getNodeByPath( relativePath ) → ModelNode

    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"
    
    Copy code

    Parameters

    relativePath : Array<number>

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

    Returns

    ModelNode
  • Chevron-right icon

    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 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 code

    Returns

    Array<number>
  • Chevron-right icon

    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.

  • Chevron-right icon

    is( type ) → this is ModelElement | ModelRootElement
    inherited

    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
    
    Copy code

    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
    
    Copy code

    Parameters

    type : 'element' | 'model:element'

    Returns

    this is ModelElement | ModelRootElement
  • Chevron-right icon

    is( type ) → this is ModelText
    inherited

    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
    
    Copy code

    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
  • Chevron-right icon

    is( type ) → this is ModelRootElement
    inherited

    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
    
    Copy code

    Assuming that the object being checked is an element, you can also check its name:

    rootElement.is( 'rootElement', '$root' ); // -> same as above
    
    Copy code

    Parameters

    type : 'rootElement' | 'model:rootElement'

    Returns

    this is ModelRootElement
  • Chevron-right icon

    is( type ) → this is ModelLiveRange
    inherited

    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
    
    Copy code

    Parameters

    type : 'liveRange' | 'model:liveRange'

    Returns

    this is ModelLiveRange
  • Chevron-right icon

    is( type ) → this is ModelDocumentFragment
    inherited

    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
    
    Copy code

    Parameters

    type : 'documentFragment' | 'model:documentFragment'

    Returns

    this is ModelDocumentFragment
  • Chevron-right icon

    is( type ) → this is ModelRange | ModelLiveRange
    inherited

    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
    
    Copy code

    Parameters

    type : 'range' | 'model:range'

    Returns

    this is ModelRange | ModelLiveRange
  • Chevron-right icon

    is( type ) → this is ModelLivePosition
    inherited

    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
    
    Copy code

    Parameters

    type : 'livePosition' | 'model:livePosition'

    Returns

    this is ModelLivePosition
  • Chevron-right icon

    is( type ) → this is ModelPosition | ModelLivePosition
    inherited

    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
    
    Copy code

    Parameters

    type : 'position' | 'model:position'

    Returns

    this is ModelPosition | ModelLivePosition
  • Chevron-right icon

    is( type ) → this is Marker
    inherited

    Checks whether the object is of type Marker.

    marker.is( 'marker' ); // -> true
    marker.is( 'model:marker' ); // -> true
    
    marker.is( 'view:element' ); // -> false
    marker.is( 'documentSelection' ); // -> false
    
    Copy code

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ModelRootElement and has the specified name.

    rootElement.is( 'rootElement', '$root' );
    
    Copy code

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'model:rootElement'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type, name ) → boolean
    inherited

    Checks whether the object is of type ModelElement or its subclass and has the specified name.

    element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
    text.is( 'element', 'imageBlock' ); -> false
    
    Copy code

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'model:element'
    name : N

    Returns

    boolean
  • Chevron-right icon

    is( type ) → this is ModelTextProxy
    inherited

    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
    
    Copy code

    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
  • Chevron-right icon

    is( type ) → this is ModelDocumentSelection
    inherited

    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
    
    Copy code

    Parameters

    type : 'documentSelection' | 'model:documentSelection'

    Returns

    this is ModelDocumentSelection
  • Chevron-right icon

    is( type ) → this is ModelSelection | ModelDocumentSelection
    inherited

    Checks whether the object is of type ModelSelection or ModelDocumentSelection.

    selection.is( 'selection' ); // -> true
    selection.is( 'model:selection' ); // -> true
    
    selection.is( 'view:selection' ); // -> false
    selection.is( 'range' ); // -> false
    
    Copy code

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is ModelSelection | ModelDocumentSelection
  • Chevron-right icon

    is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement
    inherited

    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 a ModelNode 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
    
    Copy code

    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
    
    Copy code

    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
    
    Copy code

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is ModelNode | ModelText | ModelElement | ModelRootElement
  • Chevron-right icon

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

    Parameters

    node : ModelNode

    Node to compare with.

    Returns

    boolean
  • Chevron-right icon

    isAttached() → boolean
    inherited

    Returns true if the node is inside a document root that is attached to the document.

    Returns

    boolean
  • Chevron-right icon

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

    Parameters

    node : ModelNode

    Node to compare with.

    Returns

    boolean
  • Chevron-right icon

    offsetToIndex( offset ) → number

    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.
    
    Copy code

    Parameters

    offset : number

    Returns

    number
  • Chevron-right icon

    toJSON() → unknown

    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.

  • Chevron-right icon

    _appendChild( nodes ) → void
    internal

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

    Parameters

    nodes : string | ModelItem | Iterable<( string | ModelItem )>

    Nodes to be inserted.

    Returns

    void

    Related:

  • Chevron-right icon

    _clearAttributes() → void
    internalinherited

    Removes all attributes from the node.

    Returns

    void

    Related:

  • Chevron-right icon

    _clone( deep ) → ModelElement
    internal

    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

    Returns

    ModelElement
  • Chevron-right icon

    _insertChild( index, items ) → void
    internal

    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 : string | ModelItem | Iterable<( string | ModelItem )>

    Items to be inserted.

    Returns

    void

    Related:

  • Chevron-right icon

    _remove() → void
    internalinherited

    Removes this node from its parent.

    Returns

    void

    Related:

  • Chevron-right icon

    _removeAttribute( key ) → boolean
    internalinherited

    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:

  • Chevron-right icon

    _removeChildren( index, howMany ) → Array<ModelNode>
    internal

    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<ModelNode>

    Array containing removed nodes.

    Related:

  • Chevron-right icon

    _removeChildrenArray( nodes ) → void
    internal

    Removes children nodes provided as an array and sets the parent of these nodes to null.

    These nodes do not need to be direct siblings.

    This method is faster than removing nodes one by one, as it recalculates offsets only once.

    Parameters

    nodes : Array<ModelNode>

    Array of nodes.

    Returns

    void
  • Chevron-right icon

    _setAttribute( key, value ) → void
    internalinherited

    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:

  • Chevron-right icon

    _setAttributesTo( attrs ) → void
    internalinherited

    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

  • Chevron-right icon

    fromJSON( json ) → ModelElement
    static

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

    Parameters

    json : any

    Plain object to be converted to Element.

    Returns

    ModelElement

    Element instance created using given plain object.