CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

ModelDocumentFragment (engine/model)

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

class
See source

ModelDocumentFragment represents a part of model which does not have a common root but its top-level nodes can be seen as siblings. In other words, it is a detached part of model tree, without a root.

ModelDocumentFragment has own MarkerCollection. Markers from this collection will be set to the model markers by a insert function.

Filtering

Properties

  • readonly

    childCount : number

    See source

    Number of this document fragment's children.

  • readonly

    document : null

    See source

    Artificial owner of ModelDocumentFragment. Returns null. Added for compatibility reasons.

  • readonly

    isEmpty : boolean

    See source

    Is true if there are no nodes inside this document fragment, false otherwise.

  • readonly

    markers : Map<string, ModelRange>

    See source

    ModelDocumentFragment static markers map. This is a list of names and ranges which will be set as Markers to model markers collection when ModelDocumentFragment will be inserted to the document.

  • readonly

    maxOffset : number

    See source

    Sum of offset sizes of all of this document fragment's children.

  • name : undefined

    See source

    Artificial element name. Returns undefined. Added for compatibility reasons.

  • readonly

    nextSibling : null

    See source

    Artificial next sibling. Returns null. Added for compatibility reasons.

  • readonly

    parent : null

    See source

    Artificial parent of ModelDocumentFragment. Returns null. Added for compatibility reasons.

  • readonly

    previousSibling : null

    See source

    Artificial previous sibling. Returns null. Added for compatibility reasons.

  • readonly

    root : ModelDocumentFragment

    See source

    Artificial root of ModelDocumentFragment. Returns itself. Added for compatibility reasons.

  • rootName : undefined

    See source

    Artificial root name. Returns undefined. Added for compatibility reasons.

  • private readonly

    _children : ModelNodeList

    See source

    List of nodes contained inside the document fragment.

Methods

  • internal

    constructor( [ children ] )

    See source

    Creates an empty ModelDocumentFragment.

    Note: Constructor of this class shouldn't be used directly in the code. Use the createDocumentFragment method instead.

    Parameters

    [ children ] : ModelNode | Iterable<ModelNode>

    Nodes to be contained inside the ModelDocumentFragment.

  • Symbol.iterator() → IterableIterator<ModelNode>

    See source

    Returns an iterator that iterates over all nodes contained inside this document fragment.

    Returns

    IterableIterator<ModelNode>

  • getAncestors() → Array<never>

    See source

    Returns empty array. Added for compatibility reasons.

    Returns

    Array<never>

  • getChild( index ) → null | ModelNode

    See source

    Gets the child at the given index. Returns null if incorrect index was passed.

    Parameters

    index : number

    Index in this document fragment.

    Returns

    null | ModelNode

    Child node.

  • getChildAtOffset( offset ) → null | ModelNode

    See source

    Gets the child at the given offset. Returns null if incorrect index was passed.

    Parameters

    offset : number

    Offset in this document fragment.

    Returns

    null | ModelNode

    Child node.

  • getChildIndex( node ) → null | number

    See source

    Returns an index of the given child node. Returns null if given node is not a child of this document fragment.

    Parameters

    node : ModelNode

    Child node to look for.

    Returns

    null | number

    Child node's index.

  • getChildStartOffset( node ) → null | number

    See source

    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 document fragment.

    Parameters

    node : ModelNode

    Child node to look for.

    Returns

    null | number

    Child node's starting offset.

  • getChildren() → IterableIterator<ModelNode>

    See source

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

    Returns

    IterableIterator<ModelNode>

  • getNodeByPath( relativePath ) → ModelNode | ModelDocumentFragment

    See source

    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

    ModelNode | ModelDocumentFragment

  • getPath() → Array<number>

    See source

    Returns path to a ModelDocumentFragment, which is an empty array. Added for compatibility reasons.

    Returns

    Array<number>

  • inherited

    is( type ) → this is ModelElement | ModelRootElement

    See source

    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

  • inherited

    is( type ) → this is ModelText

    See source

    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

  • inherited

    is( type ) → this is ModelPosition | ModelLivePosition

    See source

    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

  • inherited

    is( type ) → this is ModelRootElement

    See source

    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

  • inherited

    is( type ) → this is ModelLiveRange

    See source

    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

  • inherited

    is( type ) → this is Marker

    See source

    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

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker

  • inherited

    is( type ) → this is ModelTextProxy

    See source

    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

  • inherited

    is( type ) → this is ModelDocumentSelection

    See source

    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

  • inherited

    is( type ) → this is ModelSelection | ModelDocumentSelection

    See source

    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

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is ModelSelection | ModelDocumentSelection

  • inherited

    is( type ) → this is ModelDocumentFragment

    See source

    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

  • inherited

    is( type ) → this is ModelRange | ModelLiveRange

    See source

    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

  • inherited

    is( type ) → this is ModelLivePosition

    See source

    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

  • inherited

    is( type, name ) → boolean

    See source

    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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

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

    See source

    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

    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

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is ModelNode | ModelText | ModelElement | ModelRootElement

  • isAttached() → false

    See source

    Returns false as ModelDocumentFragment by definition is not attached to a document. Added for compatibility reasons.

    Returns

    false

  • offsetToIndex( offset ) → number

    See source

    Converts offset "position" to index "position".

    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 docFrag = new ModelDocumentFragment( [ textNode, pElement ] );
docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
docFrag.offsetToIndex( 2 ); // Returns 0.
docFrag.offsetToIndex( 3 ); // Returns 1.
docFrag.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

    Index of a node that occupies given offset.

  • toJSON() → unknown

    See source

    Converts ModelDocumentFragment instance to plain object and returns it. Takes care of converting all of this document fragment's children.

    Returns

    unknown

    ModelDocumentFragment instance converted to plain object.

  • internal

    _appendChild( items ) → void

    See source

    Inserts one or more nodes at the end of this document fragment.

    Parameters

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

    Items to be inserted.

    Returns

    void

  • internal

    _insertChild( index, items ) → void

    See source

    Inserts one or more nodes at the given index and sets parent of these nodes to this document fragment.

    Parameters

    index : number

    Index at which nodes should be inserted.

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

    Items to be inserted.

    Returns

    void

  • internal

    _removeChildren( index, howMany ) → Array<ModelNode>

    See source

    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.

  • internal

    _removeChildrenArray( nodes ) → void

    See source

    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

Static methods

  • static

    fromJSON( json ) → ModelDocumentFragment

    See source

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

    Parameters

    json : any

    Plain object to be converted to ModelDocumentFragment.

    Returns

    ModelDocumentFragment

    ModelDocumentFragment instance created using given plain object.