# UpcastConversionApi

interface

A set of conversion utilities available as the third parameter of the [upcast dispatcher](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md)'s events.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L683)

<a id="properties">

## Properties

<a id="member-consumable">

### `consumable: ViewConsumable`

Stores information about what parts of the processed view item are still waiting to be handled. After a piece of view item was converted, an appropriate consumable value should be [consumed](module_engine_conversion_viewconsumable-ViewConsumable.md#function-consume).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L690)

<a id="member-schema">

### `schema: ModelSchema`

The model's schema instance.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L695)

<a id="member-store">

### `store: unknown`

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

The difference between this property and the `data` parameter of [event-element](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-element) is that the `data` parameters allow you to pass parameters within a single event and `store` within the whole conversion.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L710)

<a id="member-writer">

### `writer: ModelWriter`

The [`ModelWriter`](module_engine_model_writer-ModelWriter.md) instance used to manipulate the data during conversion.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L700)

<a id="methods">

## Methods

<a id="function-convertChildren">

### `convertChildren( viewElement, positionOrElement ) → object`

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L748)

#### Parameters

* `viewElement: ViewElement | ViewDocumentFragment`

  An element whose children should be converted.

* `positionOrElement: ModelElement | ModelPosition`

  A position or an element of the conversion.

#### Returns

* `object`

  The conversion result:

  * `result.modelRange` The model range containing the results of the conversion of all children of the given item. When no child was converted, the range is collapsed.
  * `result.modelCursor` The position where the conversion should be continued.

#### Fires

* [element](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-element)
* [text](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-text)
* [documentFragment](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-documentFragment)

<a id="function-convertItem">

### `convertItem( viewItem, modelCursor ) → object`

Starts the conversion of a given item by firing an appropriate event.

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L729)

#### Parameters

* `viewItem: ViewItem`

  Item to convert.

* `modelCursor: ModelPosition`

  The conversion position.

#### Returns

* `object`

  The conversion result:

  * `result.modelRange` The model range containing the result of the item conversion, created and modified by callbacks attached to the fired event, or `null` if the conversion result was incorrect.
  * `result.modelCursor` The position where the conversion should be continued.

#### Fires

* [element](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-element)
* [text](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-text)
* [documentFragment](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#event-documentFragment)

<a id="function-getSplitParts">

### `getSplitParts( modelElement ) → Array<ModelElement>`

Returns all the split parts of the given `element` that were created during upcasting through using [`splitToAllowedParent`](#function-splitToAllowedParent). It enables you to easily track these elements and continue processing them after they are split during the conversion of their children.

```
<paragraph>Foo<imageBlock />bar<imageBlock />baz</paragraph> ->
<paragraph>Foo</paragraph><imageBlock /><paragraph>bar</paragraph><imageBlock /><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 the given `element` was not split, an array with a single element is returned.

A usage example in the converter code:

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

// Children conversion may split `myElement`.
conversionApi.convertChildren( data.viewItem, data.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 has already been converted, you may want to check the first element in `data.modelRange`. This is a common situation if an attribute converter is separated from an element converter.

**Note:** This is an advanced method. For most cases [`safeInsert`](#function-safeInsert) and [`updateConversionResult`](#function-updateConversionResult) should be used.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L897)

#### Parameters

* `modelElement: ModelElement`

#### Returns

* `Array<ModelElement>`

<a id="function-keepEmptyElement">

### `keepEmptyElement( modelElement ) → void`

Mark an element that was created during splitting to not get removed on conversion end even if it is empty.

**Note:** This is an advanced method. For most cases you will not need to keep the split empty element.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L904)

#### Parameters

* `modelElement: ModelElement`

#### Returns

* `void`

<a id="function-safeInsert">

### `safeInsert( modelNode, position ) → boolean`

Safely inserts an element to the document, checking the [schema](module_engine_model_schema-ModelSchema.md) to find an allowed parent for an element that you are going to insert, starting from the given position. If the current parent does not allow to insert the element but one of the ancestors does, then splits the nodes to allowed parent.

If the schema allows to insert the node in a given position, nothing is split.

If it was not possible to find an allowed parent, `false` is returned and nothing is split.

Otherwise, ancestors are split.

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

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

-> safe insert for `<imageBlock>` will split ->

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

Example usage:

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

if ( !conversionApi.safeInsert( myElement, data.modelCursor ) ) {
	return;
}
```

The split result is saved and [`updateConversionResult`](#function-updateConversionResult) should be used to update the [conversion data](module_engine_conversion_upcastdispatcher-UpcastConversionData.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L792)

#### Parameters

* `modelNode: ModelNode`

  The node to insert.

* `position: ModelPosition`

  The position where an element is going to be inserted.

#### Returns

* `boolean`

  The split result. If it was not possible to find an allowed position, `false` is returned.

<a id="function-splitToAllowedParent">

### `splitToAllowedParent( modelNode, modelCursor ) → object | null`

Checks the [schema](module_engine_model_schema-ModelSchema.md) to find an allowed parent for an element that is going to be inserted starting from the given position. If the current parent does not allow inserting an element but one of the ancestors does, the method splits nodes to allowed parent.

If the schema allows inserting the node in the given position, nothing is split and an object with that position is returned.

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

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

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

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

-> split for `<imageBlock>` ->

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

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

**Note:** This is an advanced method. For most cases [`safeInsert`](#function-safeInsert) and [`updateConversionResult`](#function-updateConversionResult) should be used.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L850)

#### Parameters

* `modelNode: ModelNode`

  The node to insert.

* `modelCursor: ModelPosition`

  The position where the element is going to be inserted.

#### Returns

* `object | null`

  The split result. If it was not possible to find an allowed position, `null` is returned.

  * `position` The position between split elements.
  * `cursorParent` The element inside which the cursor should be placed to continue the conversion. When the element is not defined it means that there was no split.

<a id="function-updateConversionResult">

### `updateConversionResult( modelElement, data ) → void`

Updates the conversion result and sets a proper [`modelRange`](module_engine_conversion_upcastdispatcher-UpcastConversionData.md#member-modelRange) and the next [`modelCursor`](module_engine_conversion_upcastdispatcher-UpcastConversionData.md#member-modelCursor) after the conversion. Used together with [`safeInsert`](#function-safeInsert), it enables you to easily convert elements without worrying if the node was split during the conversion of its children.

A usage example in converter code:

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

if ( !conversionApi.safeInsert( myElement, data.modelCursor ) ) {
	return;
}

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

conversionApi.updateConversionResult( myElement, data );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts#L815)

#### Parameters

* `modelElement: ModelElement`
* `data: UpcastConversionData`

#### Returns

* `void`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)