Report an issue
Class

DowncastHelpers (engine/conversion)

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

class

Downcast conversion helper functions.

Filtering

Methods

  • constructor( dispatchers )

    inherited

    Creates a conversion helpers instance.

    Parameters

    dispatchers : Array.<(DowncastDispatcher | UpcastDispatcher)>
  • add( conversionHelper ) → DowncastHelpers | UpcastHelpers

    inherited

    Registers a conversion helper.

    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.

    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 } )
    } );

    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

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

    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.

    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, viewWriter ) => {
            return viewWriter.createAttributeElement( 'span', {
                style: 'font-weight:' + modelAttributeValue
            } );
        }
    } );
    
    editor.conversion.for( 'downcast' ).attributeToElement( {
        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

    DowncastHelpers
  • elementToElement( config = { config.model, config.view } ) → DowncastHelpers

    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.

    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, viewWriter ) => {
            return 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

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

    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.

    editor.conversion.for( 'downcast' ).markerToElement( {
        model: 'search',
        view: 'marker-search'
    } );
    
    editor.conversion.for( 'downcast' ).markerToElement( {
        model: 'search',
        view: 'search-result',
        converterPriority: 'high'
    } );
    
    editor.conversion.for( 'downcast' ).markerToElement( {
        model: 'search',
        view: {
            name: 'span',
            attributes: {
                'data-marker': 'search'
            }
        }
    } );
    
    editor.conversion.for( 'downcast' ).markerToElement( {
        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 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.

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

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

    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.

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

    [ config.converterPriority ] : PriorityString

    Converter priority.

    Defaults to 'normal'

    Returns

    DowncastHelpers