engine/conversion/upcast-converters
@ckeditor/ckeditor5-engine/src/conversion/upcast-converters
Contains view to model converters for
UpcastDispatcher
.
Filtering
Functions
-
convertText() → function
static
-
convertToModelFragment() → function
static
Function factory, creates a converter that converts view document fragment or all children of
Element
into model document fragment. This is the "entry-point" converter for upcast (view to model conversion). This converter starts the conversion of all children of passed view document fragment. Those children view nodes are then handled by other converters.This also a "default", last resort converter for all view elements that has not been converted by other converters. When a view element is being converted to the model but it does not have converter specified, that view element will be converted to model document fragment and returned.
Returns
function
Universal converter for view fragments and elements that returns model fragment with children of converted view item.
-
upcastAttributeToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → function
static
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 toupcastElementToAttribute
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.
upcastAttributeToAttribute( { view: 'src', model: 'source' } ); upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source' } ); upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source', converterPriority: 'normal' } ); upcastAttributeToAttribute( { view: { key: 'data-style', value: /[\s\S]+/ }, model: 'styled' } ); upcastAttributeToAttribute( { view: { name: 'img', key: 'class', value: 'styled-dark' }, model: { key: 'styled', value: 'dark' } } ); upcastAttributeToAttribute( { 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 ]; } } } );
See
for
to learn how to add converter to 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
function
Conversion helper.
-
upcastElementToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → function
static
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. SeeupcastAttributeToAttribute
for comparison.Keep in mind that the attribute will be set only if it is allowed by schema configuration.
upcastElementToAttribute( { view: 'strong', model: 'bold' } ); upcastElementToAttribute( { view: 'strong', model: 'bold', converterPriority: 'high' } ); upcastElementToAttribute( { view: { name: 'span', classes: 'bold' }, model: 'bold' } ); upcastElementToAttribute( { view: { name: 'span', classes: [ 'styled', 'styled-dark' ] }, model: { key: 'styled', value: 'dark' } } ); upcastElementToAttribute( { 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
for
to learn how to add converter to 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
'normal'
Returns
function
Conversion helper.
-
upcastElementToElement( config = { config.view, config.model, [config.converterPriority] } ) → function
static
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.
upcastElementToElement( { view: 'p', model: 'paragraph' } ); upcastElementToElement( { view: 'p', model: 'paragraph', converterPriority: 'high' } ); upcastElementToElement( { view: { name: 'p', classes: 'fancy' }, model: 'fancyParagraph' } ); upcastElementToElement( { view: { name: 'p', classes: 'heading' }, model: ( viewElement, modelWriter ) => { return modelWriter.createElement( 'heading', { level: viewElement.getAttribute( 'data-level' ) } ); } } );
See
for
to learn how to add converter to conversion process.Parameters
config : Object
Conversion configuration.
Propertiesconfig.view : MatcherPattern
Pattern matching all view elements which should be converted.
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
function
Conversion helper.
-
upcastElementToMarker( config = { config.view, config.model, [config.converterPriority] } ) → function
static
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.upcastElementToMarker( { view: 'marker-search', model: 'search' } ); upcastElementToMarker( { view: 'marker-search', model: 'search', converterPriority: 'high' } ); upcastElementToMarker( { view: 'marker-search', model: viewElement => 'comment:' + viewElement.getAttribute( 'data-comment-id' ) } ); upcastElementToMarker( { view: { name: 'span', attributes: { 'data-marker': 'search' } }, model: 'search' } );
See
for
to learn how to add converter to 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
function
Conversion helper.