UpcastHelpers (engine/conversion)
@ckeditor/ckeditor5-engine/src/conversion/upcasthelpers
Upcast conversion helper functions.
Filtering
Methods
-
constructor( dispatchers )
inherited
Creates a conversion helpers instance.
Parameters
dispatchers : Array.<(DowncastDispatcher | UpcastDispatcher)>
-
add( conversionHelper ) → DowncastHelpers | UpcastHelpers
inherited
Registers a conversion helper.
Note: See full usage example in the
conversion.for()
method description.Parameters
conversionHelper : function
The function to be called on event.
Returns
-
attributeToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers
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<image source="foo.jpg"></image>
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 contrary 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 => { 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 => viewElement.getStyle( 'line-height' ) } } );
See
conversion.for()
to learn how to add a converter to the conversion process.Parameters
config : Object
Conversion configuration.
Propertiesconfig.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
.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 returns the value. IfString
is given, the model attribute value will be same as view attribute value.[ config.converterPriority ] : PriorityString
Converter priority.
Defaults to
'low'
Returns
-
elementToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers
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 => { 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.
Propertiesconfig.view : MatcherPattern
Pattern matching all view elements which should be converted.
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 returns the value. IfString
is given, the model attribute value will be set totrue
.[ config.converterPriority ] : PriorityString
Converter priority.
Defaults to
'low'
Returns
-
elementToElement( config = { [config.view], config.model, [config.converterPriority] } ) → UpcastHelpers
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, modelWriter ) => { 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.view ] : MatcherPattern
Pattern matching all view elements which should be converted. If not set, the converter will fire for every view element.
config.model : String | Element | function
Name of the model element, a model element instance or a function that takes a view element and returns a model element. The model element will be inserted in the model.
[ config.converterPriority ] : PriorityString
Converter priority.
Defaults to
'normal'
Returns
-
elementToMarker( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers
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.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 => '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.
Propertiesconfig.view : MatcherPattern
Pattern matching all view elements which should be converted.
config.model : String | function
Name of the model marker, or a function that takes a view element and returns a model marker name.
[ config.converterPriority ] : PriorityString
Converter priority.
Defaults to
'normal'
Returns