Class

DocumentFragment (engine/model)

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

class

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

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

Filtering

Properties

  • readonly

    childCount : number

    Number of this document fragment's children.

  • readonly

    document : null

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

  • readonly

    isEmpty : boolean

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

  • readonly

    markers : Map<string, Range>

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

  • readonly

    maxOffset : number

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

  • name : undefined

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

  • readonly

    nextSibling : null

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

  • readonly

    parent : null

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

  • readonly

    previousSibling : null

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

  • readonly

    root : DocumentFragment

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

  • rootName : undefined

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

  • private readonly

    _children : NodeList

    List of nodes contained inside the document fragment.

Methods

  • internal

    constructor( [ children ] )

    Creates an empty DocumentFragment.

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

    Parameters

    [ children ] : Node | Iterable<Node>

    Nodes to be contained inside the DocumentFragment.

  • Symbol.iterator() → IterableIterator<Node>

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

    Returns

    IterableIterator<Node>
  • getAncestors() → Array<never>

    Returns empty array. Added for compatibility reasons.

    Returns

    Array<never>
  • getChild( index ) → null | Node

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

    Parameters

    index : number

    Index of child.

    Returns

    null | Node

    Child node.

  • getChildIndex( node ) → null | number

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

    Parameters

    node : Node

    Child node to look for.

    Returns

    null | number

    Child node's index.

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

    Parameters

    node : Node

    Child node to look for.

    Returns

    null | number

    Child node's starting offset.

  • getChildren() → IterableIterator<Node>

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

    Returns

    IterableIterator<Node>
  • getNodeByPath( relativePath ) → Node | DocumentFragment

    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

    Node | DocumentFragment
  • getPath() → Array<number>

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

    Returns

    Array<number>
  • inherited

    is( type ) → this is Element | RootElement

    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
  • inherited

    is( type ) → this is Text

    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

    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
  • inherited

    is( type ) → this is Position | LivePosition

    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

    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
  • inherited

    is( type ) → this is Marker

    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 DocumentSelection

    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

    Checks whether the object is of type Selection or DocumentSelection.

    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 LiveRange

    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

    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

    this is Range | LiveRange
  • inherited

    is( type ) → this is LivePosition

    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 TextProxy

    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

    Checks whether the object is of type RootElement 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, name ) → boolean

    Checks whether the object is of type Element 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 ) → this is Node | Text | Element | RootElement

    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 a Node 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 Node | Text | Element | RootElement
  • isAttached() → false

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

    Returns

    false
  • offsetToIndex( offset ) → number

    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 DocumentFragment( [ 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

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

    Returns

    unknown

    DocumentFragment instance converted to plain object.

  • internal

    _appendChild( items ) → void

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

    Parameters

    items : string | Item | Iterable<string | Item>

    Items to be inserted.

    Returns

    void
  • internal

    _insertChild( index, items ) → void

    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 | Item | Iterable<string | Item>

    Items to be inserted.

    Returns

    void
  • internal

    _removeChildren( index, howMany ) → Array<Node>

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

    Array containing removed nodes.

Static methods

  • static

    fromJSON( json ) → DocumentFragment

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

    Parameters

    json : any

    Plain object to be converted to DocumentFragment.

    Returns

    DocumentFragment

    DocumentFragment instance created using given plain object.