Report an issue
Module

engine/conversion/downcast-converters

@ckeditor/ckeditor5-engine/src/conversion/downcast-converters

module

Contains downcast (model-to-view) converters for DowncastDispatcher.

Filtering

Type Definitions

  • HighlightDescriptor

    An object describing how the marker highlight should be represented in the view.

Functions

  • 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 <span> 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 <strong>Foo</strong> 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 downcast 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 <p>Foo</p> 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 downcast 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 <p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p> 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 <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.

    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.