CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Module

engine/model/utils/insertobject

@ckeditor/ckeditor5-engine/src/model/utils/insertobject

module

Filtering

Functions

  • insertObject( model, object, [ selectable ], placeOrOffset, [ options ] = { [options.findOptimalPosition], [options.setSelection] } ) → Range

    Inserts an object element at a specific position in the editor content.

    See source

    Note: Use insertObject instead of this function. This function is only exposed to be reusable in algorithms which change the insertObject method's behavior.

    Note: For more documentation and examples, see insertObject.

    Parameters

    model : Model

    The model in context of which the insertion should be performed.

    object : Element

    An object to be inserted into the model document.

    [ selectable ] : Selectable

    A selectable where the content should be inserted. If not specified, the current document selection will be used instead.

    Defaults to model.document.selection

    placeOrOffset : Number | 'before' | 'end' | 'after' | 'on' | 'in'

    Specifies the exact place or offset for the insertion to take place, relative to selectable.

    [ options ] : Object

    Additional options.

    Properties
    [ options.findOptimalPosition ] : 'auto' | 'before' | 'after'

    An option that, when set, adjusts the insertion position (relative to selectable and placeOrOffset) so that the content of selectable is not split upon insertion (a.k.a. non-destructive insertion).

    • When 'auto', the algorithm will decide whether to insert the object before or after selectable to avoid content splitting.
    • When 'before', the closest position before selectable will be used that will not result in content splitting.
    • When 'after', the closest position after selectable will be used that will not result in content splitting.

    Note that this option works only for block objects. Inline objects are inserted into text and do not split blocks.

    [ options.setSelection ] : 'on' | 'after'

    An option that, when set, moves the document selection after inserting the object.

    • When 'on', the document selection will be set on the inserted object.
    • When 'after', the document selection will move to the closest text node after the inserted object. If there is no such text node, a paragraph will be created and the document selection will be moved inside it.

    Returns

    Range

    A range which contains all the performed changes. This is a range that, if removed, would return the model to the state before the insertion. If no changes were preformed by insertObject(), returns a range collapsed at the insertion position.