Conversion (engine/conversion)

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

class

A utility class that helps add converters to upcast and downcast dispatchers.

We recommend reading the editor conversion guide first to understand the core concepts of the conversion mechanisms.

An instance of the conversion manager is available in the editor.conversion property and by default has the following groups of dispatchers (i.e. directions of conversion):

downcast (editing and data downcasts)
editingDowncast
dataDowncast
upcast

One-way converters

To add a converter to a specific group, use the for() method:

// Add a converter to editing downcast and data downcast.
editor.conversion.for( 'downcast' ).elementToElement( config ) );

// Add a converter to the data pipepline only:
editor.conversion.for( 'dataDowncast' ).elementToElement( dataConversionConfig ) );

// And a slightly different one for the editing pipeline:
editor.conversion.for( 'editingDowncast' ).elementToElement( editingConversionConfig ) );

See for() method documentation to learn more about available conversion helpers and how to use your custom ones.

Two-way converters

Besides using one-way converters via the for() method, you can also use other methods available in this class to add two-way converters (upcast and downcast):

elementToElement() – Model element to view element and vice versa.
attributeToElement() – Model attribute to view element and vice versa.
attributeToAttribute() – Model attribute to view attribute and vice versa.

Filtering

Public
Inherited
Internal
Protected
Private
Deprecated

Properties

private readonly
_downcast : Array<DowncastDispatcher>

See source
private readonly
_helpers : Map<string, DowncastHelpers | UpcastHelpers>

See source
Maps dispatchers group name to ConversionHelpers instances.
private readonly
_upcast : Array<UpcastDispatcher>

See source

Methods

constructor( downcastDispatchers, upcastDispatchers )

See source
Creates a new conversion instance.

Parameters

downcastDispatchers : ArrayOrItem<DowncastDispatcher>

upcastDispatchers : ArrayOrItem<UpcastDispatcher>
addAlias( alias, dispatcher ) → void
See source
Define an alias for registered dispatcher.
```
const conversion = new Conversion(
	[ dataDowncastDispatcher, editingDowncastDispatcher ],
	upcastDispatcher
);

conversion.addAlias( 'dataDowncast', dataDowncastDispatcher );
```
Parameters

alias : string

An alias of a dispatcher.

dispatcher : DowncastDispatcher | UpcastDispatcher

Dispatcher which should have an alias.

Returns

void
addAlias( alias, dispatcher ) → void
See source
Define an alias for registered dispatcher.
```
const conversion = new Conversion(
	[ dataDowncastDispatcher, editingDowncastDispatcher ],
	upcastDispatcher
);

conversion.addAlias( 'dataDowncast', dataDowncastDispatcher );
```
Parameters

alias : `${ string }Upcast`

An alias of a dispatcher.

dispatcher : UpcastDispatcher

Dispatcher which should have an alias.

Returns

void
addAlias( alias, dispatcher ) → void
See source
Define an alias for registered dispatcher.
```
const conversion = new Conversion(
	[ dataDowncastDispatcher, editingDowncastDispatcher ],
	upcastDispatcher
);

conversion.addAlias( 'dataDowncast', dataDowncastDispatcher );
```
Parameters

alias : `${ string }Downcast`

An alias of a dispatcher.

dispatcher : DowncastDispatcher

Dispatcher which should have an alias.

Returns

void
attributeToAttribute( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void
See source
Sets up converters between the model and the view that convert a model attribute to a view attribute (and vice versa). For example, <imageBlock src='foo.jpg'></imageBlock> is converted to <img src='foo.jpg'></img> (the same attribute key and value). This type of converters is intended to be used with model element nodes. To convert the text attributes, the attributeToElement convertershould be set up.
```
// A simple conversion from the `source` model attribute to the `src` view attribute (and vice versa).
editor.conversion.attributeToAttribute( { model: 'source', view: 'src' } );

// Attribute values are strictly specified.
editor.conversion.attributeToAttribute( {
	model: {
		name: 'imageInline',
		key: 'aside',
		values: [ 'aside' ]
	},
	view: {
		aside: {
			name: 'img',
			key: 'class',
			value: [ 'aside', 'half-size' ]
		}
	}
} );

// Set the style attribute.
editor.conversion.attributeToAttribute( {
	model: {
		name: 'imageInline',
		key: 'aside',
		values: [ 'aside' ]
	},
	view: {
		aside: {
			name: 'img',
			key: 'style',
			value: {
				float: 'right',
				width: '50%',
				margin: '5px'
			}
		}
	}
} );

// Conversion from and to a model attribute key whose value is an enum (`align=right|center`).
// Use `upcastAlso` to define other view elements that should also be converted to the `align=right` attribute.
editor.conversion.attributeToAttribute( {
	model: {
		key: 'align',
		values: [ 'right', 'center' ]
	},
	view: {
		right: {
			key: 'class',
			value: 'align-right'
		},
		center: {
			key: 'class',
			value: 'align-center'
		}
	},
	upcastAlso: {
		right: {
			styles: {
				'text-align': 'right'
			}
		},
		center: {
			styles: {
				'text-align': 'center'
			}
		}
	}
} );
```
The definition.model parameter specifies which model attribute should be converted from and to. It can be a { key, [ values ], [ name ] } object or a String, which will be treated like { key: definition.model }. The key property is the model attribute key to convert from and to. The values are the possible model attribute values. If the values parameter is not set, the model attribute value will be the same as the view attribute value. If name is set, the conversion will be set up only for model elements with the given name.

The definition.view parameter specifies which view attribute should be converted from and to. It can be a { key, value, [ name ] } object or a String, which will be treated like { key: definition.view }. The key property is the view attribute key to convert from and to. The value is the view attribute value to convert from and to. If definition.value is not set, the view attribute value will be the same as the model attribute value. If key is 'class', value can be a String or an array of Strings. If key is 'style', value is an object with key-value pairs. In other cases, value is a String. If name is set, the conversion will be set up only for model elements with the given name. If definition.model.values is set, definition.view is an object that assigns values from definition.model.values to { key, value, [ name ] } objects.

definition.upcastAlso specifies which other matching view elements should also be upcast to the given model configuration. If definition.model.values is set, definition.upcastAlso should be an object assigning values from definition.model.values to MatcherPatterns or arrays of MatcherPatterns.

Note: definition.model and definition.view form should be mirrored, so the same types of parameters should be given in both parameters.

Type parameters

TValues : extends string

Parameters

definition : object

The converter definition.

Properties

[ definition.converterPriority ] : PriorityString

definition.model : string | object

The model attribute to convert from and to.

[ definition.upcastAlso ] : ArrayOrItem<string | AttributeCreatorFunction | Object>

Any view element matching definition.upcastAlso will also be converted to the given model attribute. definition.upcastAlso is used only if config.model.values is specified.

definition.view : string | Object

The view attribute to convert from and to.

[ definition.converterPriority ] : PriorityString

definition.model : object

The model attribute to convert from and to.

[ definition.upcastAlso ] : Record<TValues, AttributeCreatorFunction | Object>

Any view element matching definition.upcastAlso will also be converted to the given model attribute. definition.upcastAlso is used only if config.model.values is specified.

definition.view : Record<TValues, Object>

The view attribute to convert from and to.

Returns

void

`attributeToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void`

See source

Sets up converters between the model and the view that convert a model attribute to a view element (and vice versa). For example, a model text node with "Foo" as data and the bold attribute will be turned to <strong>Foo</strong> in the view.

// A simple conversion from the `bold=true` attribute to the `<strong>` view element (and vice versa).
editor.conversion.attributeToElement( { model: 'bold', view: 'strong' } );

// Override other converters by specifying a converter definition with a higher priority.
editor.conversion.attributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );

// View specified as an object instead of a string.
editor.conversion.attributeToElement( {
	model: 'bold',
	view: {
		name: 'span',
		classes: 'bold'
	}
} );

// Use `config.model.name` to define the conversion only from a given node type, `$text` in this case.
// The same attribute on different elements may then be handled by a different converter.
editor.conversion.attributeToElement( {
	model: {
		key: 'textDecoration',
		values: [ 'underline', 'lineThrough' ],
		name: '$text'
	},
	view: {
		underline: {
			name: 'span',
			styles: {
				'text-decoration': 'underline'
			}
		},
		lineThrough: {
			name: 'span',
			styles: {
				'text-decoration': 'line-through'
			}
		}
	}
} );

// Use `upcastAlso` to define other view elements that should also be converted to the `bold` attribute.
editor.conversion.attributeToElement( {
	model: 'bold',
	view: 'strong',
	upcastAlso: [
		'b',
		{
			name: 'span',
			classes: 'bold'
		},
		{
			name: 'span',
			styles: {
				'font-weight': 'bold'
			}
		},
		viewElement => {
			const fontWeight = viewElement.getStyle( 'font-weight' );

			if ( viewElement.is( 'element', 'span' ) && fontWeight && /\d+/.test() && Number( fontWeight ) > 500 ) {
				// Returned value can be an object with the matched properties.
				// These properties will be "consumed" during the conversion.
				// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.

				return {
					name: true,
					styles: [ 'font-weight' ]
				};
			}
		}
	]
} );

// Conversion from and to a model attribute key whose value is an enum (`fontSize=big|small`).
// `upcastAlso` set as callback enables a conversion of a wide range of different view elements.
editor.conversion.attributeToElement( {
	model: {
		key: 'fontSize',
		values: [ 'big', 'small' ]
	},
	view: {
		big: {
			name: 'span',
			styles: {
				'font-size': '1.2em'
			}
		},
		small: {
			name: 'span',
			styles: {
				'font-size': '0.8em'
			}
		}
	},
	upcastAlso: {
		big: viewElement => {
			const fontSize = viewElement.getStyle( 'font-size' );

			if ( !fontSize ) {
				return null;
			}

			const match = fontSize.match( /(\d+)\s*px/ );

			if ( !match ) {
				return null;
			}

			const size = Number( match[ 1 ] );

			if ( viewElement.is( 'element', 'span' ) && size > 10 ) {
				// Returned value can be an object with the matched properties.
				// These properties will be "consumed" during the conversion.
				// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.

				return { name: true, styles: [ 'font-size' ] };
			}

			return null;
		},
		small: viewElement => {
			const fontSize = viewElement.getStyle( 'font-size' );

			if ( !fontSize ) {
				return null;
			}

			const match = fontSize.match( /(\d+)\s*px/ );

			if ( !match ) {
				return null;
			}

			const size = Number( match[ 1 ] );

			if ( viewElement.is( 'element', 'span' ) && size < 10 ) {
				// Returned value can be an object with the matched properties.
				// These properties will be "consumed" during the conversion.
				// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.

				return { name: true, styles: [ 'font-size' ] };
			}

			return null;
		}
	}
} );

The definition.model parameter specifies which model attribute should be converted from or to. It can be a { key, value } object describing the attribute key and value to convert or a String specifying just the attribute key (in such a case value is set to true).

Type parameters

TValues : extends string

Parameters

definition : object

The converter definition.

Properties

[ definition.converterPriority ] : PriorityString
definition.model : string | object
[ definition.upcastAlso ] : ArrayOrItem<MatcherPattern>
definition.view : ElementDefinition
[ definition.converterPriority ] : PriorityString
definition.model : object
[ definition.upcastAlso ] : Record<TValues, ArrayOrItem<MatcherPattern>>
definition.view : Record<TValues, ElementDefinition>

Returns

void

`elementToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void`

See source

Sets up converters between the model and the view that convert a model element to a view element (and vice versa). For example, the model <paragraph>Foo</paragraph> is turned into <p>Foo</p> in the view.

// A simple conversion from the `paragraph` model element to the `<p>` view element (and vice versa).
editor.conversion.elementToElement( { model: 'paragraph', view: 'p' } );

// Override other converters by specifying a converter definition with a higher priority.
editor.conversion.elementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );

// View specified as an object instead of a string.
editor.conversion.elementToElement( {
	model: 'fancyParagraph',
	view: {
		name: 'p',
		classes: 'fancy'
	}
} );

// Use `upcastAlso` to define other view elements that should also be converted to a `paragraph` element.
editor.conversion.elementToElement( {
	model: 'paragraph',
	view: 'p',
	upcastAlso: [
		'div',
		{
			// Any element with the `display: block` style.
			styles: {
				display: 'block'
			}
		}
	]
} );

// `upcastAlso` set as callback enables a conversion of a wide range of different view elements.
editor.conversion.elementToElement( {
	model: 'heading',
	view: 'h2',
	// Convert "heading-like" paragraphs to headings.
	upcastAlso: viewElement => {
		const fontSize = viewElement.getStyle( 'font-size' );

		if ( !fontSize ) {
			return null;
		}

		const match = fontSize.match( /(\d+)\s*px/ );

		if ( !match ) {
			return null;
		}

		const size = Number( match[ 1 ] );

		if ( size > 26 ) {
			// Returned value can be an object with the matched properties.
			// These properties will be "consumed" during the conversion.
			// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.

			return { name: true, styles: [ 'font-size' ] };
		}

		return null;
	}
} );

definition.model is a String with a model element name to convert from or to.

Parameters

definition : object

The converter definition.

Properties

[ definition.converterPriority ] : PriorityString
definition.model : string
[ definition.upcastAlso ] : ArrayOrItem<string | RegExp | MatcherFunctionPattern | MatcherObjectPattern | ElementObjectDefinition>
definition.view : ElementDefinition

Returns

void

for( groupName ) → UpcastHelpers
See source
Provides a chainable API to assign converters to a conversion dispatchers group.

If the given group name has not been registered, the conversion-for-unknown-group error is thrown.

You can use conversion helpers available directly in the for() chain or your custom ones via the add() method.

Using built-in conversion helpers

The for() chain comes with a set of conversion helpers which you can use like this:
```
editor.conversion.for( 'downcast' )
	.elementToElement( config1 )        // Adds an element-to-element downcast converter.
	.attributeToElement( config2 );     // Adds an attribute-to-element downcast converter.

editor.conversion.for( 'upcast' )
	.elementToAttribute( config3 );     // Adds an element-to-attribute upcast converter.
```
Refer to the documentation of built-in conversion helpers to learn about their configuration options.
- downcast (model-to-view) conversion helpers:
- upcast (view-to-model) conversion helpers:
Using custom conversion helpers

If you need to implement an atypical converter, you can do so by calling:
```
editor.conversion.for( direction ).add( customHelper );
```
The .add() method takes exactly one parameter, which is a function. This function should accept one parameter that is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.

Example:
```
editor.conversion.for( 'upcast' ).add( dispatcher => {
	dispatcher.on( 'element:a',  ( evt, data, conversionApi ) => {
		// Do something with a view <a> element.
	} );
} );
```
Refer to the documentation of UpcastDispatcher and DowncastDispatcher to learn how to write custom converters.

Parameters

groupName : 'upcast'

The name of dispatchers group to add the converters to.

Returns

UpcastHelpers
for( groupName ) → ConversionType<T>
See source
Provides a chainable API to assign converters to a conversion dispatchers group.

If the given group name has not been registered, the conversion-for-unknown-group error is thrown.

You can use conversion helpers available directly in the for() chain or your custom ones via the add() method.

Using built-in conversion helpers

The for() chain comes with a set of conversion helpers which you can use like this:
```
editor.conversion.for( 'downcast' )
	.elementToElement( config1 )        // Adds an element-to-element downcast converter.
	.attributeToElement( config2 );     // Adds an attribute-to-element downcast converter.

editor.conversion.for( 'upcast' )
	.elementToAttribute( config3 );     // Adds an element-to-attribute upcast converter.
```
Refer to the documentation of built-in conversion helpers to learn about their configuration options.
- downcast (model-to-view) conversion helpers:
- upcast (view-to-model) conversion helpers:
Using custom conversion helpers

If you need to implement an atypical converter, you can do so by calling:
```
editor.conversion.for( direction ).add( customHelper );
```
The .add() method takes exactly one parameter, which is a function. This function should accept one parameter that is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.

Example:
```
editor.conversion.for( 'upcast' ).add( dispatcher => {
	dispatcher.on( 'element:a',  ( evt, data, conversionApi ) => {
		// Do something with a view <a> element.
	} );
} );
```
Refer to the documentation of UpcastDispatcher and DowncastDispatcher to learn how to write custom converters.

Type parameters

T : extends string

Parameters

groupName : T

The name of dispatchers group to add the converters to.

Returns

ConversionType<T>
for( groupName ) → DowncastHelpers
See source
Provides a chainable API to assign converters to a conversion dispatchers group.

If the given group name has not been registered, the conversion-for-unknown-group error is thrown.

You can use conversion helpers available directly in the for() chain or your custom ones via the add() method.

Using built-in conversion helpers

The for() chain comes with a set of conversion helpers which you can use like this:
```
editor.conversion.for( 'downcast' )
	.elementToElement( config1 )        // Adds an element-to-element downcast converter.
	.attributeToElement( config2 );     // Adds an attribute-to-element downcast converter.

editor.conversion.for( 'upcast' )
	.elementToAttribute( config3 );     // Adds an element-to-attribute upcast converter.
```
Refer to the documentation of built-in conversion helpers to learn about their configuration options.
- downcast (model-to-view) conversion helpers:
- upcast (view-to-model) conversion helpers:
Using custom conversion helpers

If you need to implement an atypical converter, you can do so by calling:
```
editor.conversion.for( direction ).add( customHelper );
```
The .add() method takes exactly one parameter, which is a function. This function should accept one parameter that is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.

Example:
```
editor.conversion.for( 'upcast' ).add( dispatcher => {
	dispatcher.on( 'element:a',  ( evt, data, conversionApi ) => {
		// Do something with a view <a> element.
	} );
} );
```
Refer to the documentation of UpcastDispatcher and DowncastDispatcher to learn how to write custom converters.

Parameters

groupName : 'downcast' | 'dataDowncast' | 'editingDowncast'

The name of dispatchers group to add the converters to.

Returns

DowncastHelpers
private
_createConversionHelpers( __namedParameters = { __namedParameters.dispatchers, __namedParameters.isDowncast, __namedParameters.name } ) → void

See source
Creates and caches conversion helpers for given dispatchers group.

Parameters

__namedParameters : object

Properties

__namedParameters.dispatchers : Array<DowncastDispatcher | UpcastDispatcher>

__namedParameters.isDowncast : boolean

__namedParameters.name : string

Returns

void

Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.

With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.

Conversion (engine/conversion)

One-way converters

Two-way converters

Filtering

Properties

private readonly _downcast : Array<DowncastDispatcher>module:engine/conversion/conversion~Conversion#_downcast

private readonly _helpers : Map<string, DowncastHelpers | UpcastHelpers>module:engine/conversion/conversion~Conversion#_helpers

private readonly _upcast : Array<UpcastDispatcher>module:engine/conversion/conversion~Conversion#_upcast

Methods

constructor( downcastDispatchers, upcastDispatchers )module:engine/conversion/conversion~Conversion#constructor

Parameters

addAlias( alias, dispatcher ) → voidmodule:engine/conversion/conversion~Conversion#addAlias

Parameters

Returns

addAlias( alias, dispatcher ) → voidmodule:engine/conversion/conversion~Conversion#addAlias

Parameters

Returns

addAlias( alias, dispatcher ) → voidmodule:engine/conversion/conversion~Conversion#addAlias

Parameters

Returns

attributeToAttribute( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → voidmodule:engine/conversion/conversion~Conversion#attributeToAttribute

Type parameters

Parameters

Returns

attributeToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → voidmodule:engine/conversion/conversion~Conversion#attributeToElement

Type parameters

Parameters

Returns

elementToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → voidmodule:engine/conversion/conversion~Conversion#elementToElement

Parameters

Returns

for( groupName ) → UpcastHelpersmodule:engine/conversion/conversion~Conversion#for

Using built-in conversion helpers

Using custom conversion helpers

Parameters

Returns

for( groupName ) → ConversionType<T>module:engine/conversion/conversion~Conversion#for

Using built-in conversion helpers

Using custom conversion helpers

Type parameters

Parameters

Returns

for( groupName ) → DowncastHelpersmodule:engine/conversion/conversion~Conversion#for

Using built-in conversion helpers

Using custom conversion helpers

Parameters

Returns

private _createConversionHelpers( __namedParameters = { __namedParameters.dispatchers, __namedParameters.isDowncast, __namedParameters.name } ) → voidmodule:engine/conversion/conversion~Conversion#_createConversionHelpers

Parameters

Returns

private readonly
`_downcast : Array<DowncastDispatcher>`

private readonly
`_helpers : Map<string, DowncastHelpers | UpcastHelpers>`

private readonly
`_upcast : Array<UpcastDispatcher>`

`constructor( downcastDispatchers, upcastDispatchers )`

`addAlias( alias, dispatcher ) → void`

`addAlias( alias, dispatcher ) → void`

`addAlias( alias, dispatcher ) → void`

`attributeToAttribute( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void`

`attributeToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view, [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void`

`elementToElement( definition = { [definition.converterPriority], definition.model, [definition.upcastAlso], definition.view } ) → void`

`for( groupName ) → UpcastHelpers`

`for( groupName ) → ConversionType<T>`

`for( groupName ) → DowncastHelpers`

private
`_createConversionHelpers( namedParameters = { namedParameters.dispatchers, namedParameters.isDowncast, namedParameters.name } ) → void`