# engine/conversion/downcasthelpers

module

<a id="classes">

## Classes

<a id="class-DowncastHelpers">

### [DowncastHelpers](module_engine_conversion_downcasthelpers-DowncastHelpers.md)

<a id="interfaces">

## Interfaces

<a id="interface-DowncastHighlightDescriptor">

### `DowncastHighlightDescriptor`

<a id="type-definitions">

## Type Definitions

<a id="typedef-ConsumerFunction">

### `ConsumerFunction`

<a id="typedef-DowncastAddHighlightCallback">

### `DowncastAddHighlightCallback`

<a id="typedef-DowncastAttributeCreatorFunction">

### `DowncastAttributeCreatorFunction`

<a id="typedef-DowncastAttributeDescriptor">

### `DowncastAttributeDescriptor`

<a id="typedef-DowncastAttributeElementCreatorFunction">

### `DowncastAttributeElementCreatorFunction`

<a id="typedef-DowncastElementCreatorFunction">

### `DowncastElementCreatorFunction`

<a id="typedef-DowncastHighlightDescriptorCreatorFunction">

### `DowncastHighlightDescriptorCreatorFunction`

<a id="typedef-DowncastMarkerDataCreatorFunction">

### `DowncastMarkerDataCreatorFunction`

<a id="typedef-DowncastMarkerElementCreatorFunction">

### `DowncastMarkerElementCreatorFunction`

<a id="typedef-DowncastRemoveHighlightCallback">

### `DowncastRemoveHighlightCallback`

<a id="typedef-DowncastSlotFilter">

### `DowncastSlotFilter`

<a id="typedef-DowncastStructureCreatorFunction">

### `DowncastStructureCreatorFunction`

<a id="functions">

## Functions

<a id="function-cleanSelection">

### `cleanSelection() → ( evt: EventInfo, data: unknown, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which cleans artifacts after the previous [model selection](module_engine_model_selection-ModelSelection.md) conversion. It removes all empty [view attribute elements](module_engine_view_attributeelement-ViewAttributeElement.md) and merges sibling attributes at all start and end positions of all ranges.

```
   <p><strong>^</strong></p>
-> <p>^</p>

   <p><strong>foo</strong>^<strong>bar</strong>bar</p>
-> <p><strong>foo^bar<strong>bar</p>

   <p><strong>foo</strong><em>^</em><strong>bar</strong>bar</p>
-> <p><strong>foo^bar<strong>bar</p>
```

This listener should be assigned before any converter for the new selection:

```typescript
modelDispatcher.on( 'cleanSelection', cleanSelection() );
```

See [`convertCollapsedSelection`](#function-convertCollapsedSelection) which does the opposite by breaking attributes in the selection position.

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

#### Returns

* `( evt: EventInfo, data: unknown, conversionApi: DowncastConversionApi ) => void`

  Selection converter.

<a id="function-convertCollapsedSelection">

### `convertCollapsedSelection() → ( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts a collapsed [model selection](module_engine_model_selection-ModelSelection.md) to a [view selection](module_engine_view_documentselection-ViewDocumentSelection.md). The converter consumes appropriate value from the `consumable` object, maps the model selection position to the view position and breaks [attribute elements](module_engine_view_attributeelement-ViewAttributeElement.md) at the selection position.

```typescript
modelDispatcher.on( 'selection', convertCollapsedSelection() );
```

An example of the view state before and after converting the collapsed selection:

```
   <p><strong>f^oo<strong>bar</p>
-> <p><strong>f</strong>^<strong>oo</strong>bar</p>
```

By breaking attribute elements like `<strong>`, the selection is in a correct element. Then, when the selection attribute is converted, broken attributes might be merged again, or the position where the selection is may be wrapped with different, appropriate attribute elements.

See also [`cleanSelection`](#function-cleanSelection) which does a clean-up by merging attributes.

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

#### Returns

* `( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void`

  Selection converter.

<a id="function-convertRangeSelection">

### `convertRangeSelection() → ( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts a non-collapsed [model selection](module_engine_model_selection-ModelSelection.md) to a [view selection](module_engine_view_documentselection-ViewDocumentSelection.md). The converter consumes appropriate value from the `consumable` object and maps model positions from the selection to view positions.

```typescript
modelDispatcher.on( 'selection', convertRangeSelection() );
```

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

#### Returns

* `( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void`

  Selection converter.

<a id="function-createViewElementFromDowncastHighlightDescriptor">

### `createViewElementFromDowncastHighlightDescriptor( writer, descriptor ) → ViewAttributeElement` _(internal)_

Creates a `<span>` [view attribute element](module_engine_view_attributeelement-ViewAttributeElement.md) from the information provided by the [highlight descriptor](module_engine_conversion_downcasthelpers-DowncastHighlightDescriptor.md) object. If the priority is not provided in the descriptor, the default priority will be used.

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

#### Parameters

* `writer: ViewDowncastWriter`
* `descriptor: DowncastHighlightDescriptor`

#### Returns

* `ViewAttributeElement`

<a id="function-insertAttributesAndChildren">

### `insertAttributesAndChildren() → ( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a default downcast converter for triggering attributes and children conversion.

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

#### Returns

* `( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void`

  The converter.

<a id="function-insertElement">

### `insertElement( elementCreator, consumer ) → ( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts node insertion changes from the model to the view. The function passed will be provided with all the parameters of the dispatcher's [`insert` event](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md#event-insert). It is expected that the function returns an [`ViewElement`](module_engine_view_element-ViewElement.md). The result of the function will be inserted into the view.

The converter automatically consumes the corresponding value from the consumables list and binds the model and view elements.

```typescript
downcastDispatcher.on(
	'insert:myElem',
	insertElement( ( modelItem, { writer } ) => {
		const text = writer.createText( 'myText' );
		const myElem = writer.createElement( 'myElem', { myAttr: 'my-' + modelItem.getAttribute( 'myAttr' ) }, text );

		// Do something fancy with `myElem` using `modelItem` or other parameters.

		return myElem;
	}
) );
```

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

#### Parameters

* `elementCreator: DowncastElementCreatorFunction`

  Function returning a view element, which will be inserted.

* `consumer: ConsumerFunction`

  Function defining element consumption process. By default this function just consume passed item insertion.

  Defaults to `defaultConsumer`

#### Returns

* `( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void`

  Insert element event converter.

<a id="function-insertStructure">

### `insertStructure( elementCreator, consumer ) → ( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts a single model node insertion to a view structure.

It is expected that the passed element creator function returns an [`ViewElement`](module_engine_view_element-ViewElement.md) with attached slots created with `writer.createSlot()` to indicate where child nodes should be converted.

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

#### Parameters

* `elementCreator: DowncastElementCreatorFunction`

  Function returning a view structure, which will be inserted.

* `consumer: ConsumerFunction`

  A callback that is expected to consume all the consumables that were used by the element creator.

#### Returns

* `( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void`

  Insert element event converter.

#### Related:

* [DowncastHelpers#elementToStructure](module_engine_conversion_downcasthelpers-DowncastHelpers.md#function-elementToStructure)

<a id="function-insertText">

### `insertText() → ( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a default downcast converter for text insertion changes.

The converter automatically consumes the corresponding value from the consumables list and stops the event (see [`DowncastDispatcher`](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md)).

```typescript
modelDispatcher.on( 'insert:$text', insertText() );
```

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

#### Returns

* `( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void`

  Insert text event converter.

<a id="function-insertUIElement">

### `insertUIElement( elementCreator ) → ( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts marker adding change to the [view UI element](module_engine_view_uielement-ViewUIElement.md).

The view UI element that will be added to the view depends on the passed parameter. See [`insertElement`](#function-insertElement). In case of a non-collapsed range, the UI element will not wrap nodes but separate elements will be placed at the beginning and at the end of the range.

This converter binds created UI elements with the marker name using [`bindElementToMarker`](module_engine_conversion_mapper-Mapper.md#function-bindElementToMarker).

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

#### Parameters

* `elementCreator: DowncastMarkerElementCreatorFunction`

  A view UI element or a function returning the view element that will be inserted.

#### Returns

* `( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void`

  Insert element event converter.

<a id="function-remove">

### `remove() → ( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a default downcast converter for node remove changes.

```typescript
modelDispatcher.on( 'remove', remove() );
```

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

#### Returns

* `( evt: unknown, data: object, conversionApi: DowncastConversionApi ) => void`

  Remove event converter.

<a id="function-wrap">

### `wrap( elementCreator ) → ( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void` _(internal)_

Function factory that creates a converter which converts the set/change/remove attribute changes from the model to the view. It can also be used to convert selection attributes. In that case, an empty attribute element will be created and the selection will be put inside it.

Attributes from the model are converted to a view element that will be wrapping these view nodes that are bound to model elements having the given attribute. This is useful for attributes like `bold` that may be set on text nodes in the model but are represented as an element in the view:

````
[paragraph]              MODEL ====> VIEW        <p>
	|- a {bold: true}                             |- <b>
	|- b {bold: true}                             |   |- ab
	|- c                                          |- c
	```

Passed `Function` will be provided with the attribute value and then all the parameters of the
`attribute` event.
It is expected that the function returns an ViewElement.
The result of the function will be the wrapping element.
When the provided `Function` does not return any element, no conversion will take place.

The converter automatically consumes the corresponding value from the consumables list and stops the event (see
DowncastDispatcher).

```ts
modelDispatcher.on( 'attribute:bold', wrap( ( modelAttributeValue, { writer } ) => {
	return writer.createAttributeElement( 'strong' );
} );
````

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

#### Parameters

* `elementCreator: DowncastAttributeElementCreatorFunction`

  Function returning a view element that will be used for wrapping.

#### Returns

* `( evt: EventInfo, data: object, conversionApi: DowncastConversionApi ) => void`

  Set/change attribute converter.

---

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