Report an issue
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 it's 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

  • childCount : Number

    readonly

    Number of this document fragment's children.

  • isEmpty : Boolean

    readonly

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

  • markers : Map.<String, Range>

    readonly

    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.

  • maxOffset : Number

    readonly

    Sum of {module:engine/model/node~Node#offsetSize offset sizes} of all of this document fragment's children.

  • parent : null

    readonly

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

  • root : DocumentFragment

    readonly

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

  • _children : NodeList

    private

    List of nodes contained inside the document fragment.

Methods

  • constructor( [ children ] )

    protected

    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() → Iterable.<Node>

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

    Returns

    Iterable.<Node>
  • getChild( index ) → Node | null

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

    Parameters

    index : Number

    Index of child.

    Returns

    Node | null

    Child node.

  • getChildIndex( node ) → Number | null

    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

    Number | null

    Child node's index.

  • getChildStartOffset( node ) → Number | null

    Returns the starting offset of given child. Starting offset is equal to the sum of {module:engine/model/node~Node#offsetSize 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

    Number | null

    Child node's starting offset.

  • getChildren() → Iterable.<Node>

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

    Returns

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

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

    Returns

    Array
  • is( type ) → Boolean

    Checks whether given model tree object is of given type.

    Read more in is.

    Parameters

    type : String

    Returns

    Boolean
  • 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() → Object

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

    Returns

    Object

    DocumentFragment instance converted to plain object.

  • _appendChild( items )

    protected

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

    Parameters

    items : Item | Iterable.<Item>

    Items to be inserted.

  • _insertChild( index, items )

    protected

    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 : Item | Iterable.<Item>

    Items to be inserted.

  • _removeChildren( index, [ howMany ] ) → Array.<Node>

    protected

    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

  • fromJSON( json ) → DocumentFragment

    static

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

    Parameters

    json : Object

    Plain object to be converted to DocumentFragment.

    Returns

    DocumentFragment

    DocumentFragment instance created using given plain object.