UpcastHelpers
Upcast conversion helper functions.
Learn more about upcast helpers.
Methods
-
constructor( dispatchers )
inheritedmodule:engine/conversion/upcasthelpers~UpcastHelpers#constructor
-
add( conversionHelper ) → this
inheritedmodule:engine/conversion/upcasthelpers~UpcastHelpers#add
Registers a conversion helper.
Note: See full usage example in the
conversion.for()
method description.Parameters
conversionHelper : ( dispatcher: UpcastDispatcher ) => void
The function to be called on event.
Returns
this
-
attributeToAttribute( config = { [config.converterPriority], config.model, config.view } ) → this
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
this
-
dataToMarker( config = { [config.converterPriority], [config.model], config.view } ) → this
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 ] : UpcastMarkerFromAttributeCreatorFunction
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
this
-
elementToAttribute( config = { [config.converterPriority], config.model, config.view } ) → this
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
this
-
elementToElement( config = { [config.converterPriority], config.model, config.view } ) → this
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 | UpcastElementCreatorFunction
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
this
-
elementToMarker( config = { [config.converterPriority], config.model, config.view } ) → this
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 | UpcastMarkerFromElementCreatorFunction
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
this