Module engine/conversion/downcast-converters

`changeAttribute( [ attributeCreator ] ) → function`

static

Function factory that creates a converter which converts set/change/remove attribute changes from the model to the view.

Attributes from the model are converted to the view element attributes in the view. You may provide a custom function to generate a key-value attribute pair to add/change/remove. If not provided, model attributes will be converted to view element attributes on a one-to-one basis.

Note: The provided attribute creator should always return the same key for a given attribute from the model.

The converter automatically consumes the corresponding value from the consumables list and stops the event (see DowncastDispatcher).

modelDispatcher.on( 'attribute:customAttr:myElem', changeAttribute( ( value, data ) => {
    // Change attribute key from `customAttr` to `class` in the view.
    const key = 'class';
    let value = data.attributeNewValue;

    // Force attribute value to 'empty' if the model element is empty.
    if ( data.item.childCount === 0 ) {
        value = 'empty';
    }

    // Return the key-value pair.
    return { key, value };
} ) );

Parameters

[ attributeCreator ] : function: Function returning an object with two properties: key and value, which represent the attribute key and attribute value to be set on a view element. The function is passed the model attribute value as the first parameter and additional data about the change as the second parameter.

Returns

function: Set/change attribute converter.

`createViewElementFromHighlightDescriptor( descriptor ) → AttributeElement`

static

Creates a  view attribute element from the information provided by the highlight descriptor object. If a priority is not provided in the descriptor, the default priority will be used.

Parameters

descriptor : HighlightDescriptor

Returns

AttributeElement

`downcastAttributeToAttribute( config = { config.model, config.view, [config.converterPriority] } ) → function`

static

Model attribute to view attribute conversion helper.

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

downcastAttributeToAttribute( { model: 'source', view: 'src' } );

downcastAttributeToAttribute( { model: 'source', view: 'href', converterPriority: 'high' } );

downcastAttributeToAttribute( {
    model: {
        name: 'image',
        key: 'source'
    },
    view: 'src'
} );

downcastAttributeToAttribute( {
    model: {
        name: 'styled',
        values: [ 'dark', 'light' ]
    },
    view: {
        dark: {
            key: 'class',
            value: [ 'styled', 'styled-dark' ]
        },
        light: {
            key: 'class',
            value: [ 'styled', 'styled-light' ]
        }
    }
} );

downcastAttributeToAttribute( {
    model: 'styled',
    view: modelAttributeValue => ( { key: 'class', value: 'styled-' + 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, [ 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 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

function: Conversion helper.

`downcastAttributeToElement( config = { config.model, config.view, [config.converterPriority] } ) → function`

static

Model attribute to view element conversion helper.

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 Foo in the view.

downcastAttributeToElement( { model: 'bold', view: 'strong' } );

downcastAttributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );

downcastAttributeToElement( {
    model: 'invert',
    view: {
        name: 'span',
        classes: [ 'font-light', 'bg-dark' ]
    }
} );

downcastAttributeToElement( {
    model: {
        key: 'fontSize',
        values: [ 'big', 'small' ]
    },
    view: {
        big: {
            name: 'span',
            styles: {
                'font-size': '1.2em'
            }
        },
        small: {
            name: 'span',
            styles: {
                'font-size': '0.8em'
            }
        }
    }
} );

downcastAttributeToElement( {
    model: 'bold',
    view: ( modelAttributeValue, viewWriter ) => {
        return viewWriter.createAttributeElement( 'span', { style: 'font-weight:' + modelAttributeValue } );
    }
} );

downcastAttributeToElement( {
    model: {
        key: 'color',
        name: '$text'
    },
    view: ( modelAttributeValue, viewWriter ) => {
        return viewWriter.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 view writer 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

function: Conversion helper.

`downcastElementToElement( config = { config.model, config.view } ) → function`

static

Model element to view element conversion helper.

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

downcastElementToElement( { model: 'paragraph', view: 'p' } );

downcastElementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );

downcastElementToElement( {
    model: 'fancyParagraph',
    view: {
        name: 'p',
        classes: 'fancy'
    }
} );

downcastElementToElement( {
    model: 'heading',
    view: ( modelElement, viewWriter ) => viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
} );

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 element to convert.
config.view : ElementDefinition | function: A view element definition or a function that takes the model element and view writer as parameters and returns a view container element.

Returns

function: Conversion helper.

`downcastMarkerToElement( config = { config.model, config.view, [config.converterPriority] } ) → function`

static

Model marker to view element conversion helper.

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 Foo bar in the view.

downcastMarkerToElement( { model: 'search', view: 'marker-search' } );

downcastMarkerToElement( { model: 'search', view: 'search-result', converterPriority: 'high' } );

downcastMarkerToElement( {
    model: 'search',
    view: {
        name: 'span',
        attributes: {
            'data-marker': 'search'
        }
    }
} );

downcastMarkerToElement( {
    model: 'search',
    view: ( markerData, viewWriter ) => {
         return viewWriter.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 as a parameter and should return an instance of the view UI element. The data and conversionApi objects 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.

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

See 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 as a parameter and returns a view UI element.

[ config.converterPriority ] : PriorityString

Converter priority.

Defaults to 'normal'

Returns

function: Conversion helper.

`downcastMarkerToHighlight( config = { config.model, config.view, [config.converterPriority] } ) → function`

static

Model marker to highlight conversion helper.

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

For text nodes, a  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 Foo bar 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 ). 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.

downcastMarkerToHighlight( { model: 'comment', view: { classes: 'comment' } } );

downcastMarkerToHighlight( { model: 'comment', view: { classes: 'new-comment' }, converterPriority: 'high' } );

downcastMarkerToHighlight( {
    model: 'comment',
    view: data => {
        // 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 as a parameter and should return a highlight descriptor. The data object properties are passed from event-addMarker.

See 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 as a parameter and returns a highlight descriptor.

[ config.converterPriority ] : PriorityString

Converter priority.

Defaults to 'normal'

Returns

function: Conversion helper.

`highlightElement( highlightDescriptor ) → function`

static

Converter function factory. It creates a function which applies the marker's highlight to an element inside the marker's range.

The converter checks if an element has the addHighlight function stored as a custom property and, if so, uses it to apply the highlight. In such case the converter will consume all element's children, assuming that they were handled by the element itself.

When the addHighlight custom property is not present, the element is not converted in any special way. This means that converters will proceed to convert the element's child nodes.

If the highlight descriptor does not provide the priority property, 10 will be used.

If the highlight descriptor does not provide the id property, the name of the marker will be used.

This converter binds altered container elements with the marker name using the bindElementToMarker method.

Parameters

highlightDescriptor : HighlightDescriptor | function

Returns

function

`highlightText( highlightDescriptor ) → function`

static

Function factory that creates a converter which converts the text inside marker's range. The converter wraps the text with AttributeElement created from the provided descriptor. See {link module:engine/conversion/downcast-converters~createViewElementFromHighlightDescriptor}.

It can also be used to convert the selection that is inside a marker. In that case, an empty attribute element will be created and the selection will be put inside it.

If the highlight descriptor does not provide the priority property, 10 will be used.

If the highlight descriptor does not provide the id property, the name of the marker will be used.

This converter binds the created attribute elemens with the marker name using the bindElementToMarker method.

Parameters

highlightDescriptor : HighlightDescriptor | function

Returns

function

`insertElement( elementCreator ) → function`

static

Function factory that creates a converter which converts node insertion changes from the model to the view. The function passed will be provided with all the parameters of the dispatcher's insert event. It is expected that the function returns an Element. The result of the function will be inserted into the view.

The converter automatically consumes the corresponding value from the consumables list, stops the event (see DowncastDispatcher) and binds the model and view elements.

downcastDispatcher.on(
    'insert:myElem',
    insertElement( ( modelItem, viewWriter ) => {
        const text = viewWriter.createText( 'myText' );
        const myElem = viewWriter.createElement( 'myElem', { myAttr: 'my-' + modelItem.getAttribute( 'myAttr' ) }, text );

        // Do something fancy with `myElem` using `modelItem` or other parameters.

        return myElem;
    }
) );

Parameters

elementCreator : function: Function returning a view element, which will be inserted.

Returns

function: Insert element event converter.

`insertText() → function`

static

Function factory that creates a default downcast converter for text insertion changes.

The converter automatically consumes the corresponding value from the consumables list and stops the event (see DowncastDispatcher).

modelDispatcher.on( 'insert:$text', insertText() );

Returns

function: Insert text event converter.

`insertUIElement( elementCreator ) → function`

static

Function factory that creates a converter which converts marker adding change to the view UI element.

The view UI element that will be added to the view depends on the passed parameter. See insertElement. In case of a non-collapsed range, the UI element will not wrap nodes but separate elements will be placed at the beginning and at the end of the range.

This converter binds created UI elements with the marker name using bindElementToMarker.

Parameters

elementCreator : UIElement | function: A view UI element or a function returning the view element that will be inserted.

Returns

function: Insert element event converter.

`remove() → function`

static

Function factory that creates a default downcast converter for node remove changes.

modelDispatcher.on( 'remove', remove() );

Returns

function: Remove event converter.

`removeHighlight( highlightDescriptor ) → function`

static

Function factory that creates a converter which converts the removing model marker to the view.

Both text nodes and elements are handled by this converter but they are handled a bit differently.

Text nodes are unwrapped using the attribute element created from the provided highlight descriptor. See {link module:engine/conversion/downcast-converters~HighlightDescriptor}.

For elements, the converter checks if an element has the removeHighlight function stored as a custom property. If so, it uses it to remove the highlight. In such case, the children of that element will not be converted.

When removeHighlight is not present, the element is not converted in any special way. The converter will proceed to convert the element's child nodes instead.

If the highlight descriptor does not provide the priority property, 10 will be used.

If the highlight descriptor does not provide the id property, the name of the marker will be used.

This converter unbinds elements from the marker name.

Parameters

highlightDescriptor : HighlightDescriptor | function

Returns

function

`removeUIElement() → function`

static

Function factory that returns a default downcast converter for removing a UI element basing on marker remove change.

This converter unbinds elements from the marker name.

Returns

function: Removed UI element converter.

`wrap( elementCreator ) → function`

static

Function factory that creates a converter which converts set/change/remove attribute changes from the model to the view. It can also be used to convert selection attributes. In that case, an empty attribute element will be created and the selection will be put inside it.

Attributes from the model are converted to a view element that will be wrapping these view nodes that are bound to model elements having the given attribute. This is useful for attributes like bold that may be set on text nodes in the model but are represented as an element in the view:

[paragraph]              MODEL ====> VIEW        <p>
    |- a {bold: true}                             |- <b>
    |- b {bold: true}                             |   |- ab
    |- c                                          |- c

Passed Function will be provided with the attribute value and then all the parameters of the attribute event. It is expected that the function returns an Element. The result of the function will be the wrapping element. When the provided Function does not return any element, no conversion will take place.

The converter automatically consumes the corresponding value from the consumables list and stops the event (see DowncastDispatcher).

modelDispatcher.on( 'attribute:bold', wrapItem( ( modelAttributeValue, viewWriter ) => {
    return viewWriter.createAttributeElement( 'strong' );
} );

Parameters

elementCreator : function: Function returning a view element that will be used for wrapping.

Returns

function: Set/change attribute converter.

engine/conversion/downcast-converters

Filtering

Type Definitions

HighlightDescriptormodule:engine/conversion/downcast-converters~HighlightDescriptor

Functions

changeAttribute( [ attributeCreator ] ) → functionmodule:engine/conversion/downcast-converters.changeAttribute

Parameters

Returns

createViewElementFromHighlightDescriptor( descriptor ) → AttributeElementmodule:engine/conversion/downcast-converters.createViewElementFromHighlightDescriptor

Parameters

Returns

downcastAttributeToAttribute( config = { config.model, config.view, [config.converterPriority] } ) → functionmodule:engine/conversion/downcast-converters.downcastAttributeToAttribute

Parameters

Returns

downcastAttributeToElement( config = { config.model, config.view, [config.converterPriority] } ) → functionmodule:engine/conversion/downcast-converters.downcastAttributeToElement

Parameters

Returns

downcastElementToElement( config = { config.model, config.view } ) → functionmodule:engine/conversion/downcast-converters.downcastElementToElement

Parameters

Returns

downcastMarkerToElement( config = { config.model, config.view, [config.converterPriority] } ) → functionmodule:engine/conversion/downcast-converters.downcastMarkerToElement

Parameters

Returns

downcastMarkerToHighlight( config = { config.model, config.view, [config.converterPriority] } ) → functionmodule:engine/conversion/downcast-converters.downcastMarkerToHighlight

Parameters

Returns

highlightElement( highlightDescriptor ) → functionmodule:engine/conversion/downcast-converters.highlightElement

Parameters

Returns

highlightText( highlightDescriptor ) → functionmodule:engine/conversion/downcast-converters.highlightText

Parameters

Returns

insertElement( elementCreator ) → functionmodule:engine/conversion/downcast-converters.insertElement

Parameters

Returns

insertText() → functionmodule:engine/conversion/downcast-converters.insertText

Returns

insertUIElement( elementCreator ) → functionmodule:engine/conversion/downcast-converters.insertUIElement

Parameters

Returns

remove() → functionmodule:engine/conversion/downcast-converters.remove

Returns

removeHighlight( highlightDescriptor ) → functionmodule:engine/conversion/downcast-converters.removeHighlight

Parameters

Returns

removeUIElement() → functionmodule:engine/conversion/downcast-converters.removeUIElement

Returns

wrap( elementCreator ) → functionmodule:engine/conversion/downcast-converters.wrap

Parameters

Returns

`HighlightDescriptor`

`changeAttribute( [ attributeCreator ] ) → function`

`createViewElementFromHighlightDescriptor( descriptor ) → AttributeElement`

`downcastAttributeToAttribute( config = { config.model, config.view, [config.converterPriority] } ) → function`

`downcastAttributeToElement( config = { config.model, config.view, [config.converterPriority] } ) → function`

`downcastElementToElement( config = { config.model, config.view } ) → function`

`downcastMarkerToElement( config = { config.model, config.view, [config.converterPriority] } ) → function`

`downcastMarkerToHighlight( config = { config.model, config.view, [config.converterPriority] } ) → function`

`highlightElement( highlightDescriptor ) → function`

`highlightText( highlightDescriptor ) → function`

`insertElement( elementCreator ) → function`

`insertText() → function`

`insertUIElement( elementCreator ) → function`

`remove() → function`

`removeHighlight( highlightDescriptor ) → function`

`removeUIElement() → function`

`wrap( elementCreator ) → function`