DowncastHelpers (engine/conversion)
@ckeditor/ckeditor5-engine/src/conversion/downcasthelpers
Downcast conversion helper functions.
Learn more about downcast helpers.
Filtering
Methods
-
inherited
constructor( dispatchers )
module:engine/conversion/downcasthelpers~DowncastHelpers#constructor
-
inherited
add( conversionHelper ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#add
Registers a conversion helper.
Note: See full usage example in the
conversion.for()
method description.Parameters
conversionHelper : ( DowncastDispatcher ) => void
The function to be called on event.
Returns
-
attributeToAttribute( config = { [config.converterPriority], config.model, config.view, [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToAttribute
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,
<imageInline src='foo.jpg'></imageInline>
is converted to<img src='foo.jpg'></img>
.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:editor.conversion.for( 'downcast' ).attributeToAttribute( { model: 'lineHeight', view: modelAttributeValue => ( { key: 'style', value: { 'line-height': modelAttributeValue, 'border-bottom': '1px dotted #ba2' } } ) } );
See
conversion.for()
to learn how to add a converter to the conversion process.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 | AttributeDescriptor | AttributeCreatorFunction
A view attribute key, or a
{ key, value }
object or a function that takes the model attribute value and downcast conversion API as parameters and returns a{ key, value }
object. If thekey
is'class'
, thevalue
can be aString
or an array ofString
s. If thekey
is'style'
, thevalue
is an object with key-value pairs. In other cases,value
is aString
. Ifconfig.model.values
is set,config.view
should be an object assigning values fromconfig.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<TValues, AttributeDescriptor | AttributeCreatorFunction>
A view attribute key, or a
{ key, value }
object or a function that takes the model attribute value and downcast conversion API as parameters and returns a{ key, value }
object. If thekey
is'class'
, thevalue
can be aString
or an array ofString
s. If thekey
is'style'
, thevalue
is an object with key-value pairs. In other cases,value
is aString
. Ifconfig.model.values
is set,config.view
should be an object assigning values fromconfig.model.values
to{ key, value }
objects or a functions.
Returns
-
attributeToElement( config = { [config.converterPriority], config.model, config.view, [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement
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 thebold
attribute becomes<strong>Foo</strong>
in the view.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()
to learn how to add a converter to the conversion process.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 ofString
s with possible values if the model attribute is an enumerable.config.view : ElementDefinition | AttributeElementCreatorFunction
A view element definition or a function that takes the model attribute value and downcast conversion API as parameters and returns a view attribute element. If
config.model.values
is given,config.view
should be an object assigning values fromconfig.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 ofString
s with possible values if the model attribute is an enumerable.config.view : Record<TValues, ElementDefinition | AttributeElementCreatorFunction>
A view element definition or a function that takes the model attribute value and downcast conversion API as parameters and returns a view attribute element. If
config.model.values
is given,config.view
should be an object assigning values fromconfig.model.values
to view element definitions or functions.
Returns
-
elementToElement( config = { [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement
Model element to view element conversion helper.
This conversion results in creating a view element. For example, model
<paragraph>Foo</paragraph>
becomes<p>Foo</p>
in the view.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 thechildren
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 amodel
description. For example, this model:<box> <paragraph>Some text.</paragraph> </box>
will be converted into this structure in the view:
<div class="box" data-type="single"> <p>Some text.</p> </div>
But if more items were inserted in the model:
<box> <paragraph>Some text.</paragraph> <paragraph>Other item.</paragraph> </box>
it will be converted into this structure in the view (note the element
data-type
change):<div class="box" data-type="multiple"> <p>Some text.</p> <p>Other item.</p> </div>
Such a converter would look like this (note that the
paragraph
elements are converted separately):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 amodel
description. For example, this model:<heading level="2">Some text.</heading>
will be converted into this structure in the view:
<h2>Some text.</h2>
But if the
heading
element'slevel
attribute has been updated to3
for example, then it will be converted into this structure in the view:<h3>Some text.</h3>
Such a converter would look as follows:
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()
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 guide.
Parameters
config : object
Conversion configuration.
Properties[ config.converterPriority ] : PriorityString
config.model : string | object
The description or a name of the model element to convert.
config.view : ElementDefinition | ElementCreatorFunction
A view element definition or a function that takes the model element and downcast conversion API as parameters and returns a view container element.
Returns
-
elementToStructure( config = { [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#elementToStructure
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
<table>
may become this structure in the view:<figure class="table"> <table> <tbody>${ slot for table rows }</tbody> </table> </figure>
The children of the model's
<table>
element will be inserted into the<tbody>
element. If theelementToElement()
helper was used, the children would be inserted into the<figure>
.Imagine a table feature where for this model structure:
<table headingRows="1"> <tableRow> ... table cells 1 ... </tableRow> <tableRow> ... table cells 2 ... </tableRow> <tableRow> ... table cells 3 ... </tableRow> <caption>Caption text</caption> </table>
we want to generate this view structure:
<figure class="table"> <table> <thead> <tr> ... table cells 1 ... </tr> </thead> <tbody> <tr> ... table cells 2 ... </tr> <tr> ... table cells 3 ... </tr> </tbody> </table> <figcaption>Caption text</figcaption> </figure>
The converter has to take the
headingRows
attribute into consideration when allocating the<tableRow>
elements into the<tbody>
and<thead>
elements. Hence, we need two slots and need to define proper filter callbacks for them.Additionally, all elements other than
<tableRow>
should be placed outside the<table>
tag. In the example above, this will handle the table caption.Such a converter would look like this:
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()
to learn how to add a converter to the conversion process.Parameters
config : object
Conversion configuration. *
Properties[ config.converterPriority ] : PriorityString
config.model : string | object
The description or a name of the model element to convert.
config.view : ElementCreatorFunction
A function that takes the model element and downcast conversion API as parameters and returns a view container element with slots for model child nodes to be converted into.
Returns
-
markerToData( config = { [config.converterPriority], config.model, [config.view] } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData
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 thegroup
part and the rest of the marker name becomes thename
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]"
anddata-[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
anddata-[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
andname
. If the function returns a falsy value, the conversion will not take place.Basic usage:
// 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: <paragraph>Foo[bar</paragraph> <imageBlock src="abc.jpg"></imageBlock>] // View: <p>Foo<comment-start name="commentId:uid"></comment-start>bar</p> <figure data-comment-end-after="commentId:uid" class="image"><img src="abc.jpg" /></figure>
In the example above, the comment starts before "bar" and ends after the image.
If the
name
part is empty, the following view may be generated:<p>Foo <myMarker-start></myMarker-start>bar</p> <figure data-myMarker-end-after="" class="image"><img src="abc.jpg" /></figure>
Note: A situation where some markers have the
name
part and some do not, is incorrect and should be avoided.Examples where
data-group-start-after
anddata-group-end-before
are used:// Model: <blockQuote>[]<paragraph>Foo</paragraph></blockQuote> // View: <blockquote><p data-group-end-before="name" data-group-start-before="name">Foo</p></blockquote>
Similarly, when a marker is collapsed after the last element:
// Model: <blockQuote><paragraph>Foo</paragraph>[]</blockQuote> // View: <blockquote><p data-group-end-after="name" data-group-start-after="name">Foo</p></blockquote>
When there are multiple markers from the same group stored in the same attribute of the same element, their name parts are put together in the attribute value, for example:
data-group-start-before="name1,name2,name3"
.Other examples of usage:
// Using a custom function which is the same as the default conversion: editor.conversion.for( 'dataDowncast' ).markerToData( { model: 'comment', view: markerName => ( { group: 'comment', name: markerName.substr( 8 ) // Removes 'comment:' part. } ) } ); // Using the converter priority: editor.conversion.for( 'dataDowncast' ).markerToData( { model: 'comment', view: markerName => ( { group: 'comment', name: markerName.substr( 8 ) // Removes 'comment:' part. } ), converterPriority: 'high' } );
This kind of conversion is useful for saving data into the database, so it should be used in the data conversion pipeline.
See the
conversion.for()
API guide to learn how to add a converter to the conversion process.Parameters
config : object
Conversion configuration.
Properties[ config.converterPriority ] : PriorityString
Converter priority.
config.model : string
The name of the model marker (or the model marker group) to convert.
[ config.view ] : MarkerDataCreatorFunction
A function that takes the model marker name and downcast conversion API as the parameters and returns an object with the
group
andname
properties.
Returns
-
markerToElement( config = { [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#markerToElement
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()
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:
<paragraph>F[oo b]ar</paragraph>
becomes<p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p>
in the view.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 thedata
object and downcast conversion API as a parameters and should return an instance of the view UI element. Thedata
object andconversionApi
are passed from event-addMarker. Additionally, thedata.isOpening
parameter is passed, which is set totrue
for the marker start boundary element, andfalse
for the marker end boundary element.See
conversion.for()
to learn how to add a converter to the conversion process.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 : ElementDefinition | MarkerElementCreatorFunction
A view element definition or a function that takes the model marker data and downcast conversion API as a parameters and returns a view UI element.
Returns
-
markerToHighlight( config = { [config.converterPriority], config.model, config.view } ) → DowncastHelpers
module:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight
Model marker to highlight conversion helper.
This conversion results in creating a highlight on view nodes. For this kind of conversion, the
HighlightDescriptor
should be provided.For text nodes, a
<span>
AttributeElement
is created and it wraps all text nodes in the converted marker range. For example, a model marker set like this:<paragraph>F[oo b]ar</paragraph>
becomes<p>F<span class="comment">oo b</span>ar</p>
in the view.ContainerElement
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<span>
). For example, a model marker set like this:[<imageInline src="foo.jpg"></imageInline>]
becomes<img src="foo.jpg" class="comment"></img>
in the view.For container elements, the conversion is two-step. While the converter processes the highlight descriptor and passes it to a container element, it is the container element instance itself that applies values from the highlight descriptor. So, in a sense, the converter takes care of stating what should be applied on what, while the element decides how to apply that.
editor.conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: { classes: 'comment' } } ); editor.conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: { classes: 'comment' }, converterPriority: 'high' } ); editor.conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: ( data, conversionApi ) => { // Assuming that the marker name is in a form of comment:commentType:commentId. const [ , commentType, commentId ] = data.markerName.split( ':' ); return { classes: [ 'comment', 'comment-' + commentType ], attributes: { 'data-comment-id': commentId } }; } } );
If a function is passed as the
config.view
parameter, it will be used to generate the highlight descriptor. The function receives thedata
object and downcast conversion API as the parameters and should return a highlight descriptor. Thedata
object properties are passed from event-addMarker.See
conversion.for()
to learn how to add a converter to the conversion process.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 : HighlightDescriptor | HighlightDescriptorCreatorFunction
A highlight descriptor that will be used for highlighting or a function that takes the model marker data and downcast conversion API as a parameters and returns a highlight descriptor.
Returns
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.