engine/conversion/downcasthelpers

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

Classes

• DowncastHelpersmodule:engine/conversion/downcasthelpers~DowncastHelpers

  Downcast conversion helper functions.

  See source

Type Definitions

• HighlightDescriptormodule:engine/conversion/downcasthelpers~HighlightDescriptor

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

  See source

Functions

• clearAttributes() → functionmodule:engine/conversion/downcasthelpers~clearAttributes

  Function factory that creates a converter which clears artifacts after the previous model selection conversion. It removes all empty view attribute elements and merges sibling attributes at all start and end positions of all ranges.

  See source

     <p><strong>^</strong></p>
  -> <p>^</p>
  
     <p><strong>foo</strong>^<strong>bar</strong>bar</p>
  -> <p><strong>foo^bar<strong>bar</p>
  
     <p><strong>foo</strong><em>^</em><strong>bar</strong>bar</p>
  -> <p><strong>foo^bar<strong>bar</p>
  

  This listener should be assigned before any converter for the new selection:

  modelDispatcher.on( 'selection', clearAttributes() );
  

  See convertCollapsedSelection which does the opposite by breaking attributes in the selection position.

  Returns

  function

  Selection converter.

• convertCollapsedSelection() → functionmodule:engine/conversion/downcasthelpers~convertCollapsedSelection

  Function factory that creates a converter which converts a collapsed model selection to a view selection. The converter consumes appropriate value from the consumable object, maps the model selection position to the view position and breaks attribute elements at the selection position.

  See source

  modelDispatcher.on( 'selection', convertCollapsedSelection() );
  

  An example of the view state before and after converting the collapsed selection:

     <p><strong>f^oo<strong>bar</p>
  -> <p><strong>f</strong>^<strong>oo</strong>bar</p>
  

  By breaking attribute elements like <strong>, the selection is in a correct element. Then, when the selection attribute is converted, broken attributes might be merged again, or the position where the selection is may be wrapped with different, appropriate attribute elements.

  See also clearAttributes which does a clean-up by merging attributes.

  Returns

  function

  Selection converter.

• convertRangeSelection() → functionmodule:engine/conversion/downcasthelpers~convertRangeSelection

  Function factory that creates a converter which converts a non-collapsed model selection to a view selection. The converter consumes appropriate value from the consumable object and maps model positions from the selection to view positions.

  See source

  modelDispatcher.on( 'selection', convertRangeSelection() );

  Returns

  function

  Selection converter.

• createViewElementFromHighlightDescriptor( writer, descriptor ) → AttributeElementmodule:engine/conversion/downcasthelpers~createViewElementFromHighlightDescriptor

  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.

  See source

  Parameters

  writer : DowncastWriter

  descriptor : HighlightDescriptor

  Returns

  AttributeElement

• insertElement( elementCreator ) → functionmodule:engine/conversion/downcasthelpers~insertElement

  protected

  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.

  See source

  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, { writer } ) => {
  		const text = writer.createText( 'myText' );
  		const myElem = writer.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() → functionmodule:engine/conversion/downcasthelpers~insertText

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

  See source

  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 ) → functionmodule:engine/conversion/downcasthelpers~insertUIElement

  protected

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

  See source

  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() → functionmodule:engine/conversion/downcasthelpers~remove

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

  See source

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

  Returns

  function

  Remove event converter.

• wrap( elementCreator ) → functionmodule:engine/conversion/downcasthelpers~wrap

  protected

  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.

  See source

  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', wrap( ( modelAttributeValue, { writer } ) => {
  	return writer.createAttributeElement( 'strong' );
  } );

  Parameters

  elementCreator : function

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

  Returns

  function

  Set/change attribute converter.