CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

UpcastHelpers (engine/conversion)

@ckeditor/ckeditor5-engine/src/conversion/upcasthelpers

class
See source

Upcast conversion helper functions.

Filtering

Methods

  • constructor( dispatchers )

    inherited

    Creates a conversion helpers instance.

    See source

    Parameters

    dispatchers : Array.<(DowncastDispatcher | UpcastDispatcher)>

  • add( conversionHelper ) → DowncastHelpers | UpcastHelpers

    inherited

    Registers a conversion helper.

    See source

    Note: See full usage example in the conversion.for() method description.

    Parameters

    conversionHelper : function

    The function to be called on event.

    Returns

    DowncastHelpers | UpcastHelpers

  • attributeToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers

    View attribute to model attribute conversion helper.

    See source

    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 to elementToAttribute 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 to true by such a converter. You can set the model attribute to any value by providing the value 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.view : String | Object

    Specifies which view attribute will be converted. If a String is passed, attributes with given key will be converted. If an Object is passed, it must have a required key property, specifying view attribute key, and may have an optional value property, specifying view attribute value and optional name property specifying a view element name from/on which the attribute should be converted. value can be given as a String, a RegExp or a function callback, that takes view attribute value as the only parameter and returns Boolean.

    config.model : String | Object

    Model attribute key or an object with key and value 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. If String is given, the model attribute value will be same as view attribute value.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'low'

    Returns

    UpcastHelpers

  • dataToMarker( config = { config.view, [config.model], [config.converterPriority] } ) → UpcastHelpers

    View-to-model marker conversion helper.

    See source

    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 default markerToData 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 the name 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>
<image src="abc.jpg"></image>]

    Where [] are boundaries of a marker that will receive the comment: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.view : String

    The marker group name to convert.

    [ config.model ] : function

    A function that takes the name part from the view element or attribute and upcast conversion API and returns the marker name.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    UpcastHelpers

  • elementToAttribute( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers

    View element to model attribute conversion helper.

    See source

    This conversion results in setting an attribute on a model node. For example, view <strong>Foo</strong> becomes Foo model text node with bold attribute set to true.

    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. See attributeToAttribute 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.view : MatcherPattern

    Pattern matching all view elements which should be converted.

    config.model : String | Object

    Model attribute key or an object with key and value 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. If String is given, the model attribute value will be set to true.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'low'

    Returns

    UpcastHelpers

  • elementToElement( config = { [config.view], config.model, [config.converterPriority] } ) → UpcastHelpers

    View element to model element conversion helper.

    See source

    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.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 upcast conversion API and returns a model element. The model element will be inserted in the model.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    UpcastHelpers

  • elementToMarker( config = { config.view, config.model, [config.converterPriority] } ) → UpcastHelpers

    deprecated

    View element to model marker conversion helper.

    See source

    Note: This method was deprecated. Please use dataToMarker instead.

    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, 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.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

    UpcastHelpers