UpcastHelpers (engine/conversion)
@ckeditor/ckeditor5-engine/src/conversion/upcasthelpers
Upcast conversion helper functions.
Learn more about upcast helpers.
Filtering
Methods
-
inherited
constructor( dispatchers )
module:engine/conversion/upcasthelpers~UpcastHelpers#constructor
-
inherited
add( conversionHelper ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#add
Registers a conversion helper.
Note: See full usage example in the
conversion.for()
method description.Parameters
conversionHelper : ( UpcastDispatcher ) => void
The function to be called on event.
Returns
-
attributeToAttribute( config = { [config.converterPriority], config.model, config.view } ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#attributeToAttribute
View attribute to model attribute conversion helper.
This conversion results in setting an attribute on a model node. For example, view
<img src="foo.jpg"></img>
becomes<imageBlock source="foo.jpg"></imageBlock>
in the model.This helper is meant to convert view attributes from view elements which got converted to the model, so the view attribute is set only on the corresponding model node:
<div class="dark"><div>foo</div></div> --> <div dark="true"><div>foo</div></div>
Above,
class="dark"
attribute is added only to the<div>
elements that has it. This is in contrast toelementToAttribute
which sets attributes for all the children in the model:<strong>Foo</strong> --> <strong><p>Foo</p></strong> --> <paragraph><$text bold="true">Foo</$text></paragraph>
Above is a sample of HTML code, that goes through autoparagraphing (first step) and then is converted (second step). Even though
<strong>
is over<p>
element,bold="true"
was added to the text.Keep in mind that the attribute will be set only if it is allowed by schema configuration.
editor.conversion.for( 'upcast' ).attributeToAttribute( { view: 'src', model: 'source' } ); editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'src' }, model: 'source' } ); editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'src' }, model: 'source', converterPriority: 'normal' } ); editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'data-style', value: /[\s\S]+/ }, model: 'styled' } ); editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { name: 'img', key: 'class', value: 'styled-dark' }, model: { key: 'styled', value: 'dark' } } ); editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'class', value: /styled-[\S]+/ }, model: { key: 'styled' value: ( viewElement, conversionApi ) => { const regexp = /styled-([\S]+)/; const match = viewElement.getAttribute( 'class' ).match( regexp ); return match[ 1 ]; } } } );
Converting styles works a bit differently as it requires
view.styles
to be an object and by default a model attribute will be set totrue
by such a converter. You can set the model attribute to any value by providing thevalue
callback that returns the desired value.// Default conversion of font-weight style will result in setting bold attribute to true. editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { styles: { 'font-weight': 'bold' } }, model: 'bold' } ); // This converter will pass any style value to the `lineHeight` model attribute. editor.conversion.for( 'upcast' ).attributeToAttribute( { view: { styles: { 'line-height': /[\s\S]+/ } }, model: { key: 'lineHeight', value: ( viewElement, conversionApi ) => viewElement.getStyle( 'line-height' ) } } );
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. Defaults to
low
.config.model : string | object
Model attribute key or an object with
key
andvalue
properties, describing the model attribute.value
property may be set as a function that takes a view element and upcast conversion API and returns the value. IfString
is given, the model attribute value will be same as view attribute value.config.view : string | object
Specifies which view attribute will be converted. If a
String
is passed, attributes with given key will be converted. If anObject
is passed, it must have a requiredkey
property, specifying view attribute key, and may have an optionalvalue
property, specifying view attribute value and optionalname
property specifying a view element name from/on which the attribute should be converted.value
can be given as aString
, aRegExp
or a function callback, that takes view attribute value as the only parameter and returnsBoolean
.
Returns
-
dataToMarker( config = { [config.converterPriority], [config.model], config.view } ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker
View-to-model marker conversion helper.
Converts view data created by
#markerToData()
back to a model marker.This converter looks for specific view elements and view attributes that mark marker boundaries. See
#markerToData()
to learn what view data is expected by this converter.The
config.view
property is equal to the marker group name to convert.By default, this converter creates markers with the
group:name
name convention (to match the defaultmarkerToData
conversion).The conversion configuration can take a function that will generate a marker name. If such function is set as the
config.model
parameter, it is passed thename
part from the view element or attribute and it is expected to return a string with the marker name.Basic usage:
// Using the default conversion. // In this case, all markers from the `comment` group will be converted. // The conversion will look for `<comment-start>` and `<comment-end>` tags and // `data-comment-start-before`, `data-comment-start-after`, // `data-comment-end-before` and `data-comment-end-after` attributes. editor.conversion.for( 'upcast' ).dataToMarker( { view: 'comment' } );
An example of a model that may be generated by this conversion:
// 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> // Model: <paragraph>Foo[bar</paragraph> <imageBlock src="abc.jpg"></imageBlock>]
Where
[]
are boundaries of a marker that will receive thecomment:commentId:uid
name.Other examples of usage:
// Using a custom function which is the same as the default conversion: editor.conversion.for( 'upcast' ).dataToMarker( { view: 'comment', model: ( name, conversionApi ) => 'comment:' + name, } ); // Using the converter priority: editor.conversion.for( 'upcast' ).dataToMarker( { view: 'comment', model: ( name, conversionApi ) => 'comment:' + name, converterPriority: 'high' } );
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 ] : MarkerFromAttributeCreatorFunction
A function that takes the
name
part from the view element or attribute and upcast conversion API and returns the marker name.config.view : string
The marker group name to convert.
Returns
-
elementToAttribute( config = { [config.converterPriority], config.model, config.view } ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#elementToAttribute
View element to model attribute conversion helper.
This conversion results in setting an attribute on a model node. For example, view
<strong>Foo</strong>
becomesFoo
model text node withbold
attribute set totrue
.This helper is meant to set a model attribute on all the elements that are inside the converted element:
<strong>Foo</strong> --> <strong><p>Foo</p></strong> --> <paragraph><$text bold="true">Foo</$text></paragraph>
Above is a sample of HTML code, that goes through autoparagraphing (first step) and then is converted (second step). Even though
<strong>
is over<p>
element,bold="true"
was added to the text. SeeattributeToAttribute
for comparison.Keep in mind that the attribute will be set only if it is allowed by schema configuration.
editor.conversion.for( 'upcast' ).elementToAttribute( { view: 'strong', model: 'bold' } ); editor.conversion.for( 'upcast' ).elementToAttribute( { view: 'strong', model: 'bold', converterPriority: 'high' } ); editor.conversion.for( 'upcast' ).elementToAttribute( { view: { name: 'span', classes: 'bold' }, model: 'bold' } ); editor.conversion.for( 'upcast' ).elementToAttribute( { view: { name: 'span', classes: [ 'styled', 'styled-dark' ] }, model: { key: 'styled', value: 'dark' } } ); editor.conversion.for( 'upcast' ).elementToAttribute( { view: { name: 'span', styles: { 'font-size': /[\s\S]+/ } }, model: { key: 'fontSize', value: ( viewElement, conversionApi ) => { const fontSize = viewElement.getStyle( 'font-size' ); const value = fontSize.substr( 0, fontSize.length - 2 ); if ( value <= 10 ) { return 'small'; } else if ( value > 12 ) { return 'big'; } return null; } } } );
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. Defaults to
low
.config.model : string | object
Model attribute key or an object with
key
andvalue
properties, describing the model attribute.value
property may be set as a function that takes a view element and upcast conversion API and returns the value. IfString
is given, the model attribute value will be set totrue
.config.view : MatcherPattern
Pattern matching all view elements which should be converted.
Returns
-
elementToElement( config = { [config.converterPriority], config.model, config.view } ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#elementToElement
View element to model element conversion helper.
This conversion results in creating a model element. For example, view
<p>Foo</p>
becomes<paragraph>Foo</paragraph>
in the model.Keep in mind that the element will be inserted only if it is allowed by schema configuration.
editor.conversion.for( 'upcast' ).elementToElement( { view: 'p', model: 'paragraph' } ); editor.conversion.for( 'upcast' ).elementToElement( { view: 'p', model: 'paragraph', converterPriority: 'high' } ); editor.conversion.for( 'upcast' ).elementToElement( { view: { name: 'p', classes: 'fancy' }, model: 'fancyParagraph' } ); editor.conversion.for( 'upcast' ).elementToElement( { view: { name: 'p', classes: 'heading' }, model: ( viewElement, conversionApi ) => { const modelWriter = conversionApi.writer; return modelWriter.createElement( 'heading', { level: viewElement.getAttribute( 'data-level' ) } ); } } );
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 | ElementCreatorFunction
Name of the model element, a model element instance or a function that takes a view element and upcast conversion API and returns a model element. The model element will be inserted in the model.
config.view : MatcherPattern
Pattern matching all view elements which should be converted. If not set, the converter will fire for every view element.
Returns
-
elementToMarker( config = { [config.converterPriority], config.model, config.view } ) → UpcastHelpers
module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker
View element to model marker conversion helper.
This conversion results in creating a model marker. For example, if the marker was stored in a view as an element:
<p>Fo<span data-marker="comment" data-comment-id="7"></span>o</p><p>B<span data-marker="comment" data-comment-id="7"></span>ar</p>
, after the conversion is done, the marker will be available in model document markers.Note: When this helper is used in the data upcast in combination with
#markerToData()
in the data downcast, then invalid HTML code (e.g. a span between table cells) may be produced by the latter converter.In most of the cases, the
dataToMarker
should be used instead.editor.conversion.for( 'upcast' ).elementToMarker( { view: 'marker-search', model: 'search' } ); editor.conversion.for( 'upcast' ).elementToMarker( { view: 'marker-search', model: 'search', converterPriority: 'high' } ); editor.conversion.for( 'upcast' ).elementToMarker( { view: 'marker-search', model: ( viewElement, conversionApi ) => 'comment:' + viewElement.getAttribute( 'data-comment-id' ) } ); editor.conversion.for( 'upcast' ).elementToMarker( { view: { name: 'span', attributes: { 'data-marker': 'search' } }, model: 'search' } );
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 | MarkerFromElementCreatorFunction
Name of the model marker, or a function that takes a view element and returns a model marker name.
config.view : MatcherPattern
Pattern matching all view elements which should be converted.
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.