DowncastHelpers (engine/conversion)

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

Methods

• constructor( dispatchers )module:engine/conversion/downcasthelpers~DowncastHelpers#constructor

  inherited

  Creates a conversion helpers instance.

  See source

  Parameters

  dispatchers : Array.<(DowncastDispatcher | UpcastDispatcher)>

• add( conversionHelper ) → DowncastHelpers | UpcastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#add

  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] } ) → DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#attributeToAttribute

  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 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] } ) → DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement

  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, 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 } ) → DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement

  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, 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] } ) → DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#markerToElement

  Model marker to view element conversion helper.

  See source

  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] } ) → DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight

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