# DowncastHelpers
class
Downcast conversion helper functions.
Learn more about [downcast helpers](../framework/deep-dive/conversion/downcast.md).
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L68)
## Methods
### `constructor( dispatchers )` _(inherited)_
Creates a conversion helpers instance.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/conversionhelpers.ts#L19)
#### Parameters
* `dispatchers: Array`
### `add( conversionHelper ) → this` _(inherited)_
Registers a conversion helper.
**Note**: See full usage example in the `conversion.for()` method description.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/conversionhelpers.ts#L31)
#### Parameters
* `conversionHelper: ( dispatcher: DowncastDispatcher ) => void`
The function to be called on event.
#### Returns
* `this`
### `attributeToAttribute( config = { config.converterPriority?, config.model, config.view, config.converterPriority?, config.model, config.view } ) → this`
Model attribute to view attribute conversion helper.
This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example, ``
A view attribute key, or a `{ key, value }` object or a function that takes the model attribute value and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a `{ key, value }` object. If the `key` is `'class'`, the `value` can be a `String` or an array of `String`s. If the `key` is `'style'`, the `value` is an object with key-value pairs. In other cases, `value` is a `String`. If `config.model.values` is set, `config.view` should be an object assigning values from `config.model.values` to `{ key, value }` objects or a functions.
#### Returns
* `this`
### `attributeToElement( config = { config.converterPriority?, config.model, config.view, config.converterPriority?, config.model, config.view } ) → this`
Model attribute to view element conversion helper.
This conversion results in wrapping view nodes with a view attribute element. For example, a model text node with `"Foo"` as data and the `bold` attribute becomes `Foo ` in the view.
```typescript
editor.conversion.for( 'downcast' ).attributeToElement( {
model: 'bold',
view: 'strong'
} );
editor.conversion.for( 'downcast' ).attributeToElement( {
model: 'bold',
view: 'b',
converterPriority: 'high'
} );
editor.conversion.for( 'downcast' ).attributeToElement( {
model: 'invert',
view: {
name: 'span',
classes: [ 'font-light', 'bg-dark' ]
}
} );
editor.conversion.for( 'downcast' ).attributeToElement( {
model: {
key: 'fontSize',
values: [ 'big', 'small' ]
},
view: {
big: {
name: 'span',
styles: {
'font-size': '1.2em'
}
},
small: {
name: 'span',
styles: {
'font-size': '0.8em'
}
}
}
} );
editor.conversion.for( 'downcast' ).attributeToElement( {
model: 'bold',
view: ( modelAttributeValue, conversionApi ) => {
const { writer } = conversionApi;
return writer.createAttributeElement( 'span', {
style: 'font-weight:' + modelAttributeValue
} );
}
} );
editor.conversion.for( 'downcast' ).attributeToElement( {
model: {
key: 'color',
name: '$text'
},
view: ( modelAttributeValue, conversionApi ) => {
const { writer } = conversionApi;
return writer.createAttributeElement( 'span', {
style: 'color:' + modelAttributeValue
} );
}
} );
```
See [`conversion.for()`](module_engine_conversion_conversion-Conversion.md#function-for) to learn how to add a converter to the conversion process.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L428)
#### Type parameters
* `TValues: extends string`
#### Parameters
* `config: object`
Conversion configuration.
Properties
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: string | object`
The key of the attribute to convert from or a `{ key, values }` object. `values` is an array of `String`s with possible values if the model attribute is an enumerable.
* `config.view: ViewElementDefinition | DowncastAttributeElementCreatorFunction`
A view element definition or a function that takes the model attribute value and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a view attribute element. If `config.model.values` is given, `config.view` should be an object assigning values from `config.model.values` to view element definitions or functions.
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: object`
The key of the attribute to convert from or a `{ key, values }` object. `values` is an array of `String`s with possible values if the model attribute is an enumerable.
* `config.view: Record`
A view element definition or a function that takes the model attribute value and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a view attribute element. If `config.model.values` is given, `config.view` should be an object assigning values from `config.model.values` to view element definitions or functions.
#### Returns
* `this`
### `elementToElement( config = { config.converterPriority?, config.model, config.view } ) → this`
Model element to view element conversion helper.
This conversion results in creating a view element. For example, model `Foo ` becomes `Foo
` in the view.
```typescript
editor.conversion.for( 'downcast' ).elementToElement( {
model: 'paragraph',
view: 'p'
} );
editor.conversion.for( 'downcast' ).elementToElement( {
model: 'paragraph',
view: 'div',
converterPriority: 'high'
} );
editor.conversion.for( 'downcast' ).elementToElement( {
model: 'fancyParagraph',
view: {
name: 'p',
classes: 'fancy'
}
} );
editor.conversion.for( 'downcast' ).elementToElement( {
model: 'heading',
view: ( modelElement, conversionApi ) => {
const { writer } = conversionApi;
return writer.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) );
}
} );
```
The element-to-element conversion supports the reconversion mechanism. It can be enabled by using either the `attributes` or the `children` props on a model description. You will find a couple examples below.
In order to reconvert an element if any of its direct children have been added or removed, use the `children` property on a `model` description. For example, this model:
```xml
Some text.
```
will be converted into this structure in the view:
```html
```
But if more items were inserted in the model:
```xml
Some text.
Other item.
```
it will be converted into this structure in the view (note the element `data-type` change):
```html
```
Such a converter would look like this (note that the `paragraph` elements are converted separately):
```typescript
editor.conversion.for( 'downcast' ).elementToElement( {
model: {
name: 'box',
children: true
},
view: ( modelElement, conversionApi ) => {
const { writer } = conversionApi;
return writer.createContainerElement( 'div', {
class: 'box',
'data-type': modelElement.childCount == 1 ? 'single' : 'multiple'
} );
}
} );
```
In order to reconvert element if any of its attributes have been updated, use the `attributes` property on a `model` description. For example, this model:
```xml
Some text.
```
will be converted into this structure in the view:
```html
Some text.
```
But if the `heading` element's `level` attribute has been updated to `3` for example, then it will be converted into this structure in the view:
```html
Some text.
```
Such a converter would look as follows:
```typescript
editor.conversion.for( 'downcast' ).elementToElement( {
model: {
name: 'heading',
attributes: 'level'
},
view: ( modelElement, conversionApi ) => {
const { writer } = conversionApi;
return writer.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) );
}
} );
```
See [`conversion.for()`](module_engine_conversion_conversion-Conversion.md#function-for) to learn how to add a converter to the conversion process.
You can read more about the element-to-element conversion in the [downcast conversion](../framework/deep-dive/conversion/downcast.md) guide.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L210)
#### Parameters
* `config: object`
Conversion configuration.
Properties
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: string | object`
The description or a name of the model element to convert.
* `config.view: ViewElementDefinition | DowncastElementCreatorFunction`
A view element definition or a function that takes the model element and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a view container element.
#### Returns
* `this`
### `elementToStructure( config = { config.converterPriority?, config.model, config.view } ) → this`
The model element to view structure (several elements) conversion helper.
This conversion results in creating a view structure with one or more slots defined for the child nodes. For example, a model ` ` may become this structure in the view:
```html
```
The children of the model's `` element will be inserted into the `` element. If the `elementToElement()` helper was used, the children would be inserted into the ``.
Imagine a table feature where for this model structure:
```xml
... table cells 1 ...
... table cells 2 ...
... table cells 3 ...
Caption text
```
we want to generate this view structure:
```html
... table cells 1 ...
... table cells 2 ...
... table cells 3 ...
Caption text
```
The converter has to take the `headingRows` attribute into consideration when allocating the `` elements into the `` and `` elements. Hence, we need two slots and need to define proper filter callbacks for them.
Additionally, all elements other than `` should be placed outside the `` tag. In the example above, this will handle the table caption.
Such a converter would look like this:
```typescript
editor.conversion.for( 'downcast' ).elementToStructure( {
model: {
name: 'table',
attributes: [ 'headingRows' ]
},
view: ( modelElement, conversionApi ) => {
const { writer } = conversionApi;
const figureElement = writer.createContainerElement( 'figure', { class: 'table' } );
const tableElement = writer.createContainerElement( 'table' );
writer.insert( writer.createPositionAt( figureElement, 0 ), tableElement );
const headingRows = modelElement.getAttribute( 'headingRows' ) || 0;
if ( headingRows > 0 ) {
const tableHead = writer.createContainerElement( 'thead' );
const headSlot = writer.createSlot( node => node.is( 'element', 'tableRow' ) && node.index < headingRows );
writer.insert( writer.createPositionAt( tableElement, 'end' ), tableHead );
writer.insert( writer.createPositionAt( tableHead, 0 ), headSlot );
}
if ( headingRows < tableUtils.getRows( table ) ) {
const tableBody = writer.createContainerElement( 'tbody' );
const bodySlot = writer.createSlot( node => node.is( 'element', 'tableRow' ) && node.index >= headingRows );
writer.insert( writer.createPositionAt( tableElement, 'end' ), tableBody );
writer.insert( writer.createPositionAt( tableBody, 0 ), bodySlot );
}
const restSlot = writer.createSlot( node => !node.is( 'element', 'tableRow' ) );
writer.insert( writer.createPositionAt( figureElement, 'end' ), restSlot );
return figureElement;
}
} );
```
Note: The children of a model element that's being converted must be allocated in the same order in the view in which they are placed in the model.
See [`conversion.for()`](module_engine_conversion_conversion-Conversion.md#function-for) to learn how to add a converter to the conversion process.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L331)
#### Parameters
* `config: object`
Conversion configuration. \*
Properties
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: string | object`
The description or a name of the model element to convert.
* `config.view: DowncastElementCreatorFunction`
A function that takes the model element and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a view container element with slots for model child nodes to be converted into.
#### Returns
* `this`
### `markerToData( config = { config.converterPriority?, config.model, config.view? } ) → this`
Model marker converter for data downcast.
This conversion creates a representation for model marker boundaries in the view:
* If the marker boundary is before or after a model element, a view attribute is set on a corresponding view element.
* In other cases, a view element with the specified tag name is inserted at the corresponding view position.
Typically, the marker names use the `group:uniqueId:otherData` convention. For example: `comment:e34zfk9k2n459df53sjl34:zx32c`. The default configuration for this conversion is that the first part is the `group` part and the rest of the marker name becomes the `name` part.
Tag and attribute names and values are generated from the marker name:
* The templates for attributes are `data-[group]-start-before="[name]"`, `data-[group]-start-after="[name]"`, `data-[group]-end-before="[name]"` and `data-[group]-end-after="[name]"`.
* The templates for view elements are `<[group]-start name="[name]">` and `<[group]-end name="[name]">`.
Attributes mark whether the given marker's start or end boundary is before or after the given element. The `data-[group]-start-before` and `data-[group]-end-after` attributes are favored. The other two are used when the former two cannot be used.
The conversion configuration can take a function that will generate different group and name parts. If such a function is set as the `config.view` parameter, it is passed a marker name and it is expected to return an object with two properties: `group` and `name`. If the function returns a falsy value, the conversion will not take place.
Basic usage:
```typescript
// Using the default conversion.
// In this case, all markers with names starting with 'comment:' will be converted.
// The `group` parameter will be set to `comment`.
// The `name` parameter will be the rest of the marker name (without the `:`).
editor.conversion.for( 'dataDowncast' ).markerToData( {
model: 'comment'
} );
```
An example of a view that may be generated by this conversion (assuming a marker with the name `comment:commentId:uid` marked by `[]`):
```
// Model:
Foo[bar
Foo
Foo
[]Foo
// View:
Foo
Foo []Foo
### `markerToElement( config = { config.converterPriority?, config.model, config.view } ) → this`
Model marker to view element conversion helper.
**Note**: This method should be used mainly for editing the downcast and it is recommended to use the [`#markerToData()`](#function-markerToData) helper instead.
This helper may produce invalid HTML code (e.g. a span between table cells). It should only be used when you are sure that the produced HTML will be semantically correct.
This conversion results in creating a view element on the boundaries of the converted marker. If the converted marker is collapsed, only one element is created. For example, a model marker set like this: `F[oo b]ar ` becomes `F
` in the view.
```typescript
editor.conversion.for( 'editingDowncast' ).markerToElement( {
model: 'search',
view: 'marker-search'
} );
editor.conversion.for( 'editingDowncast' ).markerToElement( {
model: 'search',
view: 'search-result',
converterPriority: 'high'
} );
editor.conversion.for( 'editingDowncast' ).markerToElement( {
model: 'search',
view: {
name: 'span',
attributes: {
'data-marker': 'search'
}
}
} );
editor.conversion.for( 'editingDowncast' ).markerToElement( {
model: 'search',
view: ( markerData, conversionApi ) => {
const { writer } = conversionApi;
return writer.createUIElement( 'span', {
'data-marker': 'search',
'data-start': markerData.isOpening
} );
}
} );
```
If a function is passed as the `config.view` parameter, it will be used to generate both boundary elements. The function receives the `data` object and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as a parameters and should return an instance of the [view UI element](module_engine_view_uielement-ViewUIElement.md). The `data` object and [`conversionApi`](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) are passed from [event-addMarker](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md#event-addMarker). Additionally, the `data.isOpening` parameter is passed, which is set to `true` for the marker start boundary element, and `false` for the marker end boundary element.
See [`conversion.for()`](module_engine_conversion_conversion-Conversion.md#function-for) to learn how to add a converter to the conversion process.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L618)
#### Parameters
* `config: object`
Conversion configuration.
Properties
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: string`
The name of the model marker (or model marker group) to convert.
* `config.view: ViewElementDefinition | DowncastMarkerElementCreatorFunction`
A view element definition or a function that takes the model marker data and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as a parameters and returns a view UI element.
#### Returns
* `this`
### `markerToHighlight( config = { config.converterPriority?, config.model, config.view } ) → this`
Model marker to highlight conversion helper.
This conversion results in creating a highlight on view nodes. For this kind of conversion, the [`DowncastHighlightDescriptor`](module_engine_conversion_downcasthelpers-DowncastHighlightDescriptor.md) should be provided.
For text nodes, a `` [`ViewAttributeElement`](module_engine_view_attributeelement-ViewAttributeElement.md) is created and it wraps all text nodes in the converted marker range. For example, a model marker set like this: `F[oo b]ar ` becomes `Far
` in the view.
[`ViewContainerElement`](module_engine_view_containerelement-ViewContainerElement.md) may provide a custom way of handling highlight. Most often, the element itself is given classes and attributes described in the highlight descriptor (instead of being wrapped in ``). For example, a model marker set like this: `[
`.
```typescript
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: 'source',
view: 'src'
} );
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: 'source',
view: 'href',
converterPriority: 'high'
} );
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: {
name: 'imageInline',
key: 'source'
},
view: 'src'
} );
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: {
name: 'styled',
values: [ 'dark', 'light' ]
},
view: {
dark: {
key: 'class',
value: [ 'styled', 'styled-dark' ]
},
light: {
key: 'class',
value: [ 'styled', 'styled-light' ]
}
}
} );
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: 'styled',
view: modelAttributeValue => ( {
key: 'class',
value: 'styled-' + modelAttributeValue
} )
} );
```
**Note**: Downcasting to a style property requires providing `value` as an object:
```typescript
editor.conversion.for( 'downcast' ).attributeToAttribute( {
model: 'lineHeight',
view: modelAttributeValue => ( {
key: 'style',
value: {
'line-height': modelAttributeValue,
'border-bottom': '1px dotted #ba2'
}
} )
} );
```
See [`conversion.for()`](module_engine_conversion_conversion-Conversion.md#function-for) to learn how to add a converter to the conversion process.
[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcasthelpers.ts#L530)
#### Type parameters
* `TValues: extends string`
#### Parameters
* `config: object`
Conversion configuration.
Properties
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: string | object`
The key of the attribute to convert from or a `{ key, values, [ name ] }` object describing the attribute key, possible values and, optionally, an element name to convert from.
* `config.view: string | DowncastAttributeDescriptor | DowncastAttributeCreatorFunction`
A view attribute key, or a `{ key, value }` object or a function that takes the model attribute value and [downcast conversion API](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) as parameters and returns a `{ key, value }` object. If the `key` is `'class'`, the `value` can be a `String` or an array of `String`s. If the `key` is `'style'`, the `value` is an object with key-value pairs. In other cases, `value` is a `String`. If `config.model.values` is set, `config.view` should be an object assigning values from `config.model.values` to `{ key, value }` objects or a functions.
* `config.converterPriority?: PriorityString`
Converter priority.
* `config.model: object`
The key of the attribute to convert from or a `{ key, values, [ name ] }` object describing the attribute key, possible values and, optionally, an element name to convert from.
* `config.view: Record