CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

UpcastConversionApi (engine/conversion)

@ckeditor/ckeditor5-engine/src/conversion/upcastdispatcher

interface
See source

Conversion interface that is registered for given UpcastDispatcher and is passed as one of parameters when dispatcher fires it's events.

Filtering

Properties

  • consumable : ViewConsumable

    Stores information about what parts of processed view item are still waiting to be handled. After a piece of view item was converted, appropriate consumable value should be consumed.

    See source

  • schema : Schema

    The model's schema instance.

    See source

  • store : Object

    Custom data stored by converters for conversion process. Custom properties of this object can be defined and use to pass parameters between converters.

    See source

    The difference between this property and data parameter of event-element is that data parameters allows you to pass parameters within a single event and store within the whole conversion.

  • writer : Writer

    The Writer instance used to manipulate data during conversion.

    See source

Methods

  • convertChildren( viewItem, modelCursor ) → Object

    Starts conversion of all children of given item by firing appropriate events for all those children.

    See source

    Parameters

    viewItem : Item

    Element which children should be converted.

    modelCursor : Position

    Position of conversion.

    Returns

    Object

    result Conversion result.

    Range

    result.modelRange Model range containing results of conversion of all children of given item. When no children was converted then range is collapsed.

    Position

    result.modelCursor Position where conversion should be continued.

    Fires

  • convertItem( viewItem, modelCursor ) → Object

    Starts conversion of given item by firing an appropriate event.

    See source

    Every fired event is passed (as first parameter) an object with modelRange property. Every event may set and/or modify that property. When all callbacks are done, the final value of modelRange property is returned by this method. The modelRange must be model range or null (as set by default).

    Parameters

    viewItem : Item

    Item to convert.

    modelCursor : Position

    Position of conversion.

    Returns

    Object

    result Conversion result.

    Range | null

    result.modelRange Model range containing result of item conversion, created and modified by callbacks attached to fired event, or null if the conversion result was incorrect.

    Position

    result.modelCursor Position where conversion should be continued.

    Fires

  • getSplitParts( element ) → Array.<Element>

    Returns all the split parts of given element that were created during upcasting through using splitToAllowedParent. It enables you to easily track those elements and continue processing them after they are split during their children conversion.

    See source
    <paragraph>Foo<image />bar<image />baz</paragraph> ->
<paragraph>Foo</paragraph><image /><paragraph>bar</paragraph><image /><paragraph>baz</paragraph>

    For a reference to any of above paragraphs, the function will return all three paragraphs (the original element included), sorted in the order of their creation (the original element is the first one).

    If given element was not split, an array with single element is returned.

    Example of a usage in a converter code:

    const myElement = conversionApi.writer.createElement( 'myElement' );

// Children conversion may split `myElement`.
conversionApi.convertChildren( myElement, modelCursor );

const splitParts = conversionApi.getSplitParts( myElement );
const lastSplitPart = splitParts[ splitParts.length - 1 ];

// Setting `data.modelRange` basing on split parts:
data.modelRange = conversionApi.writer.createRange(
    conversionApi.writer.createPositionBefore( myElement ),
    conversionApi.writer.createPositionAfter( lastSplitPart )
);

// Setting `data.modelCursor` to continue after the last split element:
data.modelCursor = conversionApi.writer.createPositionAfter( lastSplitPart );

    Tip: if you are unable to get a reference to the original element (for example because the code is split into multiple converters or even classes) but it was already converted, you might want to check first element in data.modelRange. This is a common situation if an attribute converter is separated from an element converter.

    Parameters

    element : Element

    Returns

    Array.<Element>

  • splitToAllowedParent( position, node ) → Object | null

    Checks schema to find allowed parent for element that we are going to insert starting from given position. If current parent does not allow to insert element but one of the ancestors does then split nodes to allowed parent.

    See source

    If schema allows to insert node in given position, nothing is split and object with that position is returned.

    If it was not possible to find allowed parent, null is returned, nothing is split.

    Otherwise, ancestors are split and object with position and the copy of the split element is returned.

    For instance, if <image> is not allowed in <paragraph> but is allowed in $root:

    <paragraph>foo[]bar</paragraph>

 -> split for `<image>` ->

 <paragraph>foo</paragraph>[]<paragraph>bar</paragraph>

    In the sample above position between <paragraph> elements will be returned as position and the second paragraph as cursorParent.

    Parameters

    position : Position

    Position on which element is going to be inserted.

    node : Node

    Node to insert.

    Returns

    Object | null

    Split result. If it was not possible to find allowed position null is returned.

    Position

    position between split elements.

    Element

    [cursorParent] Element inside which cursor should be placed to continue conversion. When element is not defined it means that there was no split.