CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DowncastHelpers (engine/conversion)

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

class
See source

Downcast 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.model, config.view, [config.converterPriority] } ) → DowncastHelpers

    Model attribute to view attribute conversion helper.

    See source

    This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example, <image src='foo.jpg'></image> is converted to <img src='foo.jpg'></img>.

    editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: 'source',
	view: 'src'
} );

editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: 'source',
	view: 'href',
	converterPriority: 'high'
} );

editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: {
		name: 'image',
		key: 'source'
	},
	view: 'src'
} );

editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: {
		name: 'styled',
		values: [ 'dark', 'light' ]
	},
	view: {
		dark: {
			key: 'class',
			value: [ 'styled', 'styled-dark' ]
		},
		light: {
			key: 'class',
			value: [ 'styled', 'styled-light' ]
		}
	}
} );

editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: 'styled',
	view: modelAttributeValue => ( {
		key: 'class',
		value: 'styled-' + modelAttributeValue
	} )
} );

    Note: Downcasting to a style property requires providing value as an object:

    editor.conversion.for( 'downcast' ).attributeToAttribute( {
	model: 'lineHeight',
	view: modelAttributeValue => ( {
		key: 'style',
		value: {
			'line-height': modelAttributeValue,
			'border-bottom': '1px dotted #ba2'
		}
	} )
} );

    See conversion.for() to learn how to add a converter to the conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String | Object

    The key of the attribute to convert from or a { key, values, [ name ] } object describing the attribute key, possible values and, optionally, an element name to convert from.

    config.view : String | Object | function

    A view attribute key, or a { key, value } object or a function that takes the model attribute value and downcast conversion API as parameters and returns a { key, value } object. If key is 'class', value can be a String or an array of Strings. If key is 'style', value is an object with key-value pairs. In other cases, value is a String. If config.model.values is set, config.view should be an object assigning values from config.model.values to { key, value } objects or a functions.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers

  • attributeToElement( config = { config.model, config.view, [config.converterPriority] } ) → DowncastHelpers

    Model attribute to view element conversion helper.

    See source

    This conversion results in wrapping view nodes with a view attribute element. For example, a model text node with "Foo" as data and the bold attribute becomes <strong>Foo</strong> in the view.

    editor.conversion.for( 'downcast' ).attributeToElement( {
	model: 'bold',
	view: 'strong'
} );

editor.conversion.for( 'downcast' ).attributeToElement( {
	model: 'bold',
	view: 'b',
	converterPriority: 'high'
} );

editor.conversion.for( 'downcast' ).attributeToElement( {
	model: 'invert',
	view: {
		name: 'span',
		classes: [ 'font-light', 'bg-dark' ]
	}
} );

editor.conversion.for( 'downcast' ).attributeToElement( {
	model: {
		key: 'fontSize',
		values: [ 'big', 'small' ]
	},
	view: {
		big: {
			name: 'span',
			styles: {
				'font-size': '1.2em'
			}
		},
		small: {
			name: 'span',
			styles: {
				'font-size': '0.8em'
			}
		}
	}
} );

editor.conversion.for( 'downcast' ).attributeToElement( {
	model: 'bold',
	view: ( modelAttributeValue, conversionApi ) => {
		const { writer } = conversionApi;

		return writer.createAttributeElement( 'span', {
			style: 'font-weight:' + modelAttributeValue
		} );
	}
} );

editor.conversion.for( 'downcast' ).attributeToElement( {
	model: {
		key: 'color',
		name: '$text'
	},
	view: ( modelAttributeValue, conversionApi ) => {
		const { writer } = conversionApi;

		return writer.createAttributeElement( 'span', {
			style: 'color:' + modelAttributeValue
		} );
	}
} );

    See conversion.for() to learn how to add a converter to the conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String | Object

    The key of the attribute to convert from or a { key, values } object. values is an array of Strings with possible values if the model attribute is an enumerable.

    config.view : ElementDefinition | function | Object

    A view element definition or a function that takes the model attribute value and downcast conversion API as parameters and returns a view attribute element. If config.model.values is given, config.view should be an object assigning values from config.model.values to view element definitions or functions.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers

  • elementToElement( config = { config.model, config.view, [config.triggerBy], config.triggerBy.attributes, config.triggerBy.children } ) → DowncastHelpers

    Model element to view element conversion helper.

    See source

    This conversion results in creating a view element. For example, model <paragraph>Foo</paragraph> becomes <p>Foo</p> in the view.

    editor.conversion.for( 'downcast' ).elementToElement( {
	model: 'paragraph',
	view: 'p'
} );

editor.conversion.for( 'downcast' ).elementToElement( {
	model: 'paragraph',
	view: 'div',
	converterPriority: 'high'
} );

editor.conversion.for( 'downcast' ).elementToElement( {
	model: 'fancyParagraph',
	view: {
		name: 'p',
		classes: 'fancy'
	}
} );

editor.conversion.for( 'downcast' ).elementToElement( {
	model: 'heading',
	view: ( modelElement, conversionApi ) => {
		const { writer } = conversionApi;

		return writer.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) );
	}
} );

    The element-to-element conversion supports the reconversion mechanism. This is helpful in the conversion to complex view structures where multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying triggerBy() events you can trigger reconverting the model to full view tree structures at once.

    editor.conversion.for( 'downcast' ).elementToElement( {
	model: 'complex',
	view: ( modelElement, conversionApi ) => createComplexViewFromModel( modelElement, conversionApi ),
	triggerBy: {
		attributes: [ 'foo', 'bar' ],
		children: [ 'slot' ]
	}
} );

    See conversion.for() to learn how to add a converter to the conversion process.

    You can read more about element-to-element conversion in the Custom element conversion guide.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    The name of the model element to convert.

    config.view : ElementDefinition | function

    A view element definition or a function that takes the model element and downcast conversion API as parameters and returns a view container element.

    [ config.triggerBy ] : Object

    Reconversion triggers. At least one trigger must be defined.

    config.triggerBy.attributes : Array.<String>

    The name of the element's attributes whose change will trigger element reconversion.

    config.triggerBy.children : Array.<String>

    The name of direct children whose adding or removing will trigger element reconversion.

    Returns

    DowncastHelpers

  • markerToData( config = { config.model, [config.view], [config.converterPriority] } ) → DowncastHelpers

    Model marker converter for data downcast.

    See source

    This conversion creates a representation for model marker boundaries in the view:

    • If the marker boundary is at a position where text nodes are allowed, then a view element with the specified tag name and name attribute is added at this position.
    • In other cases, a specified attribute is set on a view element that is before or after the marker boundary.

    Typically, marker names use the group:uniqueId:otherData convention. For example: comment:e34zfk9k2n459df53sjl34:zx32c. The default configuration for this conversion is that the first part is the group part and the rest of the marker name becomes the name part.

    Tag and attribute names and values are generated from the marker name:

    • Templates for attributes are data-[group]-start-before="[name]", data-[group]-start-after="[name]", data-[group]-end-before="[name]" and data-[group]-end-after="[name]".
    • Templates for view elements are <[group]-start name="[name]"> and <[group]-end name="[name]">.

    Attributes mark whether the given marker's start or end boundary is before or after the given element. Attributes data-[group]-start-before and data-[group]-end-after are favored. The other two are used when the former two cannot be used.

    The conversion configuration can take a function that will generate different group and name parts. If such function is set as the config.view parameter, it is passed a marker name and it is expected to return an object with two properties: group and name. If the function returns a falsy value, the conversion will not take place.

    Basic usage:

    // Using the default conversion.
// In this case, all markers whose name starts with 'comment:' will be converted.
// The `group` parameter will be set to `comment`.
// The `name` parameter will be the rest of the marker name (without `:`).
editor.conversion.for( 'dataDowncast' ).markerToData( {
	model: 'comment'
} );

    An example of a view that may be generated by this conversion (assuming a marker with the name comment:commentId:uid marked by []):

    // Model:
<paragraph>Foo[bar</paragraph>
<image src="abc.jpg"></image>]

// 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>

    In the example above, the comment starts before "bar" and ends after the image.

    If the name part is empty, the following view may be generated:

    <p>Foo <myMarker-start></myMarker-start>bar</p>
<figure data-myMarker-end-after="" class="image"><img src="abc.jpg" /></figure>

    Note: A situation where some markers have the name part and some do not have it is incorrect and should be avoided.

    Examples where data-group-start-after and data-group-end-before are used:

    // Model:
<blockQuote>[]<paragraph>Foo</paragraph></blockQuote>

// View:
<blockquote><p data-group-end-before="name" data-group-start-before="name">Foo</p></blockquote>

    Similarly, when a marker is collapsed after the last element:

    // Model:
<blockQuote><paragraph>Foo</paragraph>[]</blockQuote>

// View:
<blockquote><p data-group-end-after="name" data-group-start-after="name">Foo</p></blockquote>

    When there are multiple markers from the same group stored in the same attribute of the same element, their name parts are put together in the attribute value, for example: data-group-start-before="name1,name2,name3".

    Other examples of usage:

    // Using a custom function which is the same as the default conversion:
editor.conversion.for( 'dataDowncast' ).markerToData( {
	model: 'comment'
	view: markerName => ( {
		group: 'comment',
		name: markerName.substr( 8 ) // Removes 'comment:' part.
	} )
} );

// Using the converter priority:
editor.conversion.for( 'dataDowncast' ).markerToData( {
	model: 'comment'
	view: markerName => ( {
		group: 'comment',
		name: markerName.substr( 8 ) // Removes 'comment:' part.
	} ),
	converterPriority: 'high'
} );

    This kind of conversion is useful for saving data into the database, so it should be used in the data conversion pipeline.

    See conversion.for() to learn how to add a converter to the conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    The name of the model marker (or model marker group) to convert.

    [ config.view ] : function

    A function that takes the model marker name and downcast conversion API as a parameters and returns an object with the group and name properties.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers

  • markerToElement( config = { config.model, config.view, [config.converterPriority] } ) → DowncastHelpers

    Model marker to view element conversion helper.

    See source

    Note: This method should be used only for editing downcast. For data downcast, use #markerToData() that produces valid HTML data.

    This conversion results in creating a view element on the boundaries of the converted marker. If the converted marker is collapsed, only one element is created. For example, model marker set like this: <paragraph>F[oo b]ar</paragraph> becomes <p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p> in the view.

    editor.conversion.for( 'editingDowncast' ).markerToElement( {
	model: 'search',
	view: 'marker-search'
} );

editor.conversion.for( 'editingDowncast' ).markerToElement( {
	model: 'search',
	view: 'search-result',
	converterPriority: 'high'
} );

editor.conversion.for( 'editingDowncast' ).markerToElement( {
	model: 'search',
	view: {
		name: 'span',
		attributes: {
			'data-marker': 'search'
		}
	}
} );

editor.conversion.for( 'editingDowncast' ).markerToElement( {
	model: 'search',
	view: ( markerData, conversionApi ) => {
		const { writer } = conversionApi;

		return writer.createUIElement( 'span', {
			'data-marker': 'search',
			'data-start': markerData.isOpening
		} );
	}
} );

    If a function is passed as the config.view parameter, it will be used to generate both boundary elements. The function receives the data object and downcast conversion API as a parameters and should return an instance of the view UI element. The data object and conversionApi are passed from event-addMarker. Additionally, the data.isOpening parameter is passed, which is set to true for the marker start boundary element, and false to the marker end boundary element.

    See conversion.for() to learn how to add a converter to the conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    The name of the model marker (or model marker group) to convert.

    config.view : ElementDefinition | function

    A view element definition or a function that takes the model marker data and downcast conversion API as a parameters and returns a view UI element.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers

  • markerToHighlight( config = { config.model, config.view, [config.converterPriority] } ) → DowncastHelpers

    Model marker to highlight conversion helper.

    See source

    This conversion results in creating a highlight on view nodes. For this kind of conversion, HighlightDescriptor should be provided.

    For text nodes, a <span> AttributeElement is created and it wraps all text nodes in the converted marker range. For example, a model marker set like this: <paragraph>F[oo b]ar</paragraph> becomes <p>F<span class="comment">oo b</span>ar</p> in the view.

    ContainerElement may provide a custom way of handling highlight. Most often, the element itself is given classes and attributes described in the highlight descriptor (instead of being wrapped in <span>). For example, a model marker set like this: [<image src="foo.jpg"></image>] becomes <img src="foo.jpg" class="comment"></img> in the view.

    For container elements, the conversion is two-step. While the converter processes the highlight descriptor and passes it to a container element, it is the container element instance itself that applies values from the highlight descriptor. So, in a sense, the converter takes care of stating what should be applied on what, while the element decides how to apply that.

    editor.conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: { classes: 'comment' } } );

editor.conversion.for( 'downcast' ).markerToHighlight( {
	model: 'comment',
	view: { classes: 'new-comment' },
	converterPriority: 'high'
} );

editor.conversion.for( 'downcast' ).markerToHighlight( {
	model: 'comment',
	view: ( data, converstionApi ) => {
		// Assuming that the marker name is in a form of comment:commentType.
		const commentType = data.markerName.split( ':' )[ 1 ];

		return {
			classes: [ 'comment', 'comment-' + commentType ]
		};
	}
} );

    If a function is passed as the config.view parameter, it will be used to generate the highlight descriptor. The function receives the data object and downcast conversion API as a parameters and should return a highlight descriptor. The data object properties are passed from event-addMarker.

    See conversion.for() to learn how to add a converter to the conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    The name of the model marker (or model marker group) to convert.

    config.view : HighlightDescriptor | function

    A highlight descriptor that will be used for highlighting or a function that takes the model marker data and downcast conversion API as a parameters and returns a highlight descriptor.

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers