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

  • Object describing how the marker highlight should be represented in the view.

Functions

  • changeAttribute( [ attributeCreator ] ) → function

    static

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

    Attributes from 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 elements attributes on 1-to-1 basis.

    Note: Provided attribute creator should always return the same key for given attribute from the model.

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

    modelDispatcher.on( 'attribute:customAttr:myElem', changeAttribute( ( value, data ) => {
        // Change attribute key from `customAttr` to `class` in 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 key-value pair.
        return { key, value };
    } ) );

    Parameters

    [ attributeCreator ] : function

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

    Returns

    function

    Set/change attribute converter.

  • Creates span view attribute element from information provided by HighlightDescriptor object. If priority is not provided in descriptor - default priority will be used.

    Parameters

    descriptor : HighlightDescriptor

    Returns

    AttributeElement
  • downcastAttributeToAttribute( config = { config.model, config.view, [config.priority] } ) → function

    static

    Model attribute to view attribute conversion helper.

    This conversion results in adding an attribute on 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', priority: '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 for to learn how to add converter to conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String | Object

    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

    View attribute key, or a { key, value } object or a function that takes 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.priority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    function

    Conversion helper.

  • downcastAttributeToElement( config = { config.model, config.view, [config.priority] } ) → function

    static

    Model attribute to view element conversion helper.

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

    downcastAttributeToElement( { model: 'bold', view: 'strong' } );
    
    downcastAttributeToElement( { model: 'bold', view: 'b', priority: '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 for to learn how to add converter to conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String | Object

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

    config.view : ElementDefinition | function | Object

    View element definition or a function that takes 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.priority ] : 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', priority: 'high' } );
    
    downcastElementToElement( {
        model: 'fancyParagraph',
        view: {
            name: 'p',
            classes: 'fancy'
        }
    } );
    
    downcastElementToElement( {
        model: 'heading',
        view: ( modelElement, viewWriter ) => viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
    } );

    See for to learn how to add converter to conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    Name of the model element to convert.

    config.view : ElementDefinition | function

    View element definition or a function that takes model element and view writer as a parameters and returns a view container element.

    Returns

    function

    Conversion helper.

  • downcastMarkerToElement( config = { config.model, config.view, [config.priority] } ) → 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 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', priority: '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 function is passed as config.view parameter, it will be used to generate both boundary elements. The function receives data object as parameter and should return an instance of view.UIElement. The data and conversionApi objects are passed from event-addMarker. Additionally, data.isOpening parameter is passed, which is set to true for marker start boundary element, and false to marker end boundary element.

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

    See for to learn how to add converter to conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    Name of the model marker (or model marker group) to convert.

    config.view : ElementDefinition | function

    View element definition or a function that takes model marker data as a parameter and returns view ui element.

    [ config.priority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    function

    Conversion helper.

  • downcastMarkerToHighlight( config = { config.model, config.view, [config.priority] } ) → 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, 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 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, 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 highlight descriptor and passes it to a container element, it is the container element instance itself which applies values from highlight descriptor. So, in a sense, converter takes care of stating what should be applied on what, while element decides how to apply that.

    downcastMarkerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
    
    downcastMarkerToHighlight( { model: 'comment', view: { classes: 'new-comment' }, priority: 'high' } );
    
    downcastMarkerToHighlight( {
        model: 'comment',
        view: data => {
            // Assuming that marker name is in a form of comment:commentType.
             const commentType = data.markerName.split( ':' )[ 1 ];
    
             return {
                 classes: [ 'comment', 'comment-' + commentType ]
             };
        }
    } );

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

    See for to learn how to add converter to conversion process.

    Parameters

    config : Object

    Conversion configuration.

    Properties
    config.model : String

    Name of the model marker (or model marker group) to convert.

    config.view : HighlightDescriptor | function

    Highlight descriptor which will be used for highlighting or a function that takes model marker data as a parameter and returns a highlight descriptor.

    [ config.priority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    function

    Conversion helper.

  • highlightElement( highlightDescriptor ) → function

    static

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

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

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

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

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

    This converter binds altered ContainerElements with marker name using the bindElementToMarker.

    Parameters

    highlightDescriptor : HighlightDescriptor | function

    Returns

    function
  • highlightText( highlightDescriptor ) → function

    static

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

    Also can be used to convert 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 will not provide priority property, 10 will be used.

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

    This converter binds created AttributeElements with marker name using the bindElementToMarker.

    Parameters

    highlightDescriptor : HighlightDescriptor | function

    Returns

    function
  • insertElement( elementCreator ) → function

    static

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

    The converter automatically consumes corresponding value from consumables list, stops the event (see DowncastDispatcher) and bind 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, creates a default downcast converter for text insertion changes.

    The converter automatically consumes corresponding value from 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, creates a converter that converts marker adding change to the view ui element.

    The view ui element, that will be added to the view, depends on passed parameter. See insertElement. In a 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 UIElements with marker name using the bindElementToMarker.

    Parameters

    elementCreator : UIElement | function

    View ui element or a function returning a view element which will be inserted.

    Returns

    function

    Insert element event converter.

  • remove() → function

    static

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

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

    Returns

    function

    Remove event converter.

  • removeHighlight( highlightDescriptor ) → function

    static

    Function factory, creates a converter that converts 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 AttributeElement created from provided highlight descriptor. See {link module:engine/conversion/downcast-converters~highlightDescriptorToAttributeElement}.

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

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

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

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

    This converter unbinds elements from marker name.

    Parameters

    highlightDescriptor : HighlightDescriptor | function

    Returns

    function
  • removeUIElement() → function

    static

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

    This converter unbinds elements from marker name.

    Returns

    function

    Remove ui element converter.

  • wrap( elementCreator ) → function

    static

    Function factory, creates a converter that converts set/change/remove attribute changes from the model to the view. Also can 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 model are converted to a view element that will be wrapping those view nodes that are bound to model elements having given attribute. This is useful for attributes like bold, which may be set on text nodes in 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 attribute value and then all the parameters of the attribute event. It's expected that the function returns a Element. The result of the function will be the wrapping element. When provided Function does not return element, then will be no conversion.

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

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

    Parameters

    elementCreator : function

    Function returning a view element, which will be used for wrapping.

    Returns

    function

    Set/change attribute converter.