CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
Home/CKEditor 5/API
Class

DocumentFragment (engine/model)

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

class
See source

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

  • childCount : Number

    readonly

    Number of this document fragment's children.

    See source

  • isEmpty : Boolean

    readonly

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

    See source

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

    See source

  • maxOffset : Number

    readonly

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

    See source

  • parent : null

    readonly

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

    See source

  • root : DocumentFragment

    readonly

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

    See source

  • _children : NodeList

    private

    List of nodes contained inside the document fragment.

    See source

Methods

  • constructor( [ children ] )

    protected

    Creates an empty DocumentFragment.

    See source

    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.

    See source

    Returns

    Iterable.<Node>

  • getChild( index ) → Node | null

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

    See source

    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.

    See source

    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 offset sizes of all node's siblings that are before it. Returns null if given node is not a child of this document fragment.

    See source

    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.

    See source

    Returns

    Iterable.<Node>

  • getNodeByPath( relativePath ) → Node | DocumentFragment

    Returns a descendant node by its path relative to this element.

    See source
    // <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.

    See source

    Returns

    Array

  • is( type ) → Boolean

    Checks whether this object is of the given type.

    See source
    docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true

docFrag.is( 'view:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false

    Check the entire list of model objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

  • offsetToIndex( offset ) → Number

    Converts offset "position" to index "position".

    See source

    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.

    See source

    Returns

    Object

    DocumentFragment instance converted to plain object.

  • _appendChild( items )

    protected

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

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    Parameters

    json : Object

    Plain object to be converted to DocumentFragment.

    Returns

    DocumentFragment

    DocumentFragment instance created using given plain object.