CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
Class

DowncastDispatcher (engine/conversion)

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

class
See source

DowncastDispatcher is a central point of downcasting (conversion from model to view), which is a process of reacting to changes in the model and firing a set of events. Callbacks listening to those events are called converters. Those converters role is to convert the model changes to changes in view (for example, adding view nodes or changing attributes on view elements).

During conversion process, DowncastDispatcher fires events, basing on state of the model and prepares data for those events. It is important to understand that those events are connected with changes done on model, for example: "node has been inserted" or "attribute has changed". This is in a contrary to upcasting (view to model conversion), where we convert view state (view nodes) to a model tree.

The events are prepared basing on a diff created by Differ, which buffers them and then passes to DowncastDispatcher as a diff between old model state and new model state.

Note, that because changes are converted there is a need to have a mapping between model structure and view structure. To map positions and elements during downcast (model to view conversion) use Mapper.

DowncastDispatcher fires following events for model tree changes:

  • insert if a range of nodes has been inserted to the model tree,
  • remove if a range of nodes has been removed from the model tree,
  • attribute if attribute has been added, changed or removed from a model node.

For insert and attribute, DowncastDispatcher generates consumables. These are used to have a control over which changes has been already consumed. It is useful when some converters overwrite other or converts multiple changes (for example converts insertion of an element and also converts that element's attributes during insertion).

Additionally, DowncastDispatcher fires events for marker changes:

Note, that changing a marker is done through removing the marker from the old range, and adding on the new range, so both those events are fired.

Finally, DowncastDispatcher also handles firing events for model selection conversion:

Unlike model tree and markers, events for selection are not fired for changes but for selection state.

When providing custom listeners for DowncastDispatcher remember to check whether given change has not been consumed yet.

When providing custom listeners for DowncastDispatcher keep in mind that any callback that had consumed a value from a consumable and converted the change should also stop the event (for efficiency purposes).

When providing custom listeners for DowncastDispatcher remember to use provided view downcast writer to apply changes to the view document.

Example of a custom converter for DowncastDispatcher:

// We will convert inserting "paragraph" model element into the model.
downcastDispatcher.on( 'insert:paragraph', ( evt, data, conversionApi ) => {
    // Remember to check whether the change has not been consumed yet and consume it.
    if ( conversionApi.consumable.consume( data.item, 'insert' ) ) {
        return;
    }

    // Translate position in model to position in view.
    const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );

    // Create <p> element that will be inserted in view at `viewPosition`.
    const viewElement = conversionApi.writer.createContainerElement( 'p' );

    // Bind the newly created view element to model element so positions will map accordingly in future.
    conversionApi.mapper.bindElements( data.item, viewElement );

    // Add the newly created view element to the view.
    conversionApi.writer.insert( viewPosition, viewElement );

    // Remember to stop the event propagation.
    evt.stop();
} );

Filtering

Properties

  • conversionApi : Object

    Interface passed by dispatcher to the events callbacks.

    See source

Methods

  • constructor( [ conversionApi ] )

    Creates a DowncastDispatcher instance.

    See source

    Parameters

    [ conversionApi ] : Object

    Interface passed by dispatcher to the events calls.

  • convertAttribute( range, key, oldValue, newValue, writer )

    Starts conversion of attribute change on given range.

    See source

    For each node in the given range, attribute event is fired with the passed data.

    Parameters

    range : Range

    Changed range.

    key : String

    Key of the attribute that has changed.

    oldValue : *

    Attribute value before the change or null if the attribute has not been set before.

    newValue : *

    New attribute value or null if the attribute has been removed.

    writer : DowncastWriter

    View writer that should be used to modify view document.

    Fires

  • convertChanges( differ, writer )

    Takes model differ object with buffered changes and fires conversion basing on it.

    See source

    Parameters

    differ : Differ

    Differ object with buffered changes.

    writer : DowncastWriter

    View writer that should be used to modify view document.

  • convertInsert( range, writer )

    Starts conversion of a range insertion.

    See source

    For each node in the range, insert event is fired. For each attribute on each node, attribute event is fired.

    Parameters

    range : Range

    Inserted range.

    writer : DowncastWriter

    View writer that should be used to modify view document.

    Fires

  • convertMarkerAdd( markerName, markerRange, writer )

    Converts added marker. Fires addMarker event for each item in marker's range. If range is collapsed single event is dispatched. See event description for more details.

    See source

    Parameters

    markerName : String

    Marker name.

    markerRange : Range

    Marker range.

    writer : DowncastWriter

    View writer that should be used to modify view document.

    Fires

  • convertMarkerRemove( markerName, markerRange, writer )

    Fires conversion of marker removal. Fires removeMarker event with provided data.

    See source

    Parameters

    markerName : String

    Marker name.

    markerRange : Range

    Marker range.

    writer : DowncastWriter

    View writer that should be used to modify view document.

    Fires

  • convertRemove( position, length, name, writer )

    Fires conversion of a single node removal. Fires remove event with provided data.

    See source

    Parameters

    position : Position

    Position from which node was removed.

    length : Number

    Offset size of removed node.

    name : String

    Name of removed node.

    writer : DowncastWriter

    View writer that should be used to modify view document.

  • convertSelection( selection, markers, writer )

    Starts model selection conversion.

    See source

    Fires events for given selection to start selection conversion.

    Parameters

    selection : Selection

    Selection to convert.

    markers : Array.<Marker>

    Array of markers containing model markers.

    writer : DowncastWriter

    View writer that should be used to modify view document.

    Fires

  • _clearConversionApi()

    private

    Clears conversion API object.

    See source

  • _createConsumableForRange( range, type ) → ModelConsumable

    private

    Creates ModelConsumable with values to consume for given range.

    See source

    Parameters

    range : Range

    Affected range.

    type : String

    Consumable type.

    Returns

    ModelConsumable

    Values to consume.

  • _createInsertConsumable( range ) → ModelConsumable

    private

    Creates ModelConsumable with values to consume from given range, assuming that the range has just been inserted to the model.

    See source

    Parameters

    range : Range

    Inserted range.

    Returns

    ModelConsumable

    Values to consume.

  • _createSelectionConsumable( selection, markers ) → ModelConsumable

    private

    Creates ModelConsumable with selection consumable values.

    See source

    Parameters

    selection : Selection

    Selection to create consumable from.

    markers : Iterable.<Marker>

    Markers which contains selection.

    Returns

    ModelConsumable

    Values to consume.

  • _testAndFire( type, data )

    private

    Tests passed consumable to check whether given event can be fired and if so, fires it.

    See source

    Parameters

    type : String

    Event type.

    data : Object

    Event data.

    Fires

Events

  • addMarker( eventInfo, data = { data.item, [data.range], data.markerRange, data.markerName }, consumable, conversionApi )

    Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside marker is converted.

    See source

    addMarker is a namespace for a class of events. Names of actually called events follow this pattern: addMarker:markerName. By specifying certain marker names, you can make the events even more gradual. For example, if markers are named foo:abc, foo:bar, then it is possible to listen to addMarker:foo or addMarker:foo:abc and addMarker:foo:bar events.

    If the marker range is not collapsed:

    • the event is fired for each item in the marker range one by one,
    • consumables object includes each item of the marker range and the consumable value is same as event name.

    If the marker range is collapsed:

    • there is only one event,
    • consumables object includes marker range with event name.

    If selection inside a marker is converted:

    • there is only one event,
    • consumables object includes selection instance with event name.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object

    Additional information about the change.

    Properties
    data.item : Item | Selection

    Item inside the new marker or the selection that is being converted.

    [ data.range ] : Range

    Range spanning over converted item. Available only in marker conversion, if the marker range was not collapsed.

    data.markerRange : Range

    Marker range.

    data.markerName : String

    Marker name.

    consumable : ModelConsumable

    Values to consume.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.

  • attribute( eventInfo, data = { data.item, data.range, data.attributeKey, data.attributeOldValue, data.attributeNewValue }, consumable, conversionApi )

    Fired in the following cases:

    See source
    • when an attribute has been added, changed, or removed from a node,
    • when a node with an attribute is inserted,
    • when collapsed model selection attribute is converted.

    attribute is a namespace for a class of events. Names of actually called events follow this pattern: attribute:attributeKey:name. attributeKey is the key of added/changed/removed attribute. name is either '$text' if change was on a text node, or the name of element which attribute has changed.

    This way listeners can either listen to a general attribute:bold event or specific event (for example attribute:src:image).

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object

    Additional information about the change.

    Properties
    data.item : Item | DocumentSelection

    Changed item or converted selection.

    data.range : Range

    Range spanning over changed item or selection range.

    data.attributeKey : String

    Attribute key.

    data.attributeOldValue : *

    Attribute value before the change. This is null when selection attribute is converted.

    data.attributeNewValue : *

    New attribute value.

    consumable : ModelConsumable

    Values to consume.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.

  • insert( eventInfo, data = { data.item, data.range }, conversionApi )

    Fired for inserted nodes.

    See source

    insert is a namespace for a class of events. Names of actually called events follow this pattern: insert:name. name is either '$text', when a text node has been inserted, or name of inserted element.

    This way listeners can either listen to a general insert event or specific event (for example insert:paragraph).

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object

    Additional information about the change.

    Properties
    data.item : Item

    Inserted item.

    data.range : Range

    Range spanning over inserted item.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.

  • remove( eventInfo, data = { data.position, data.length }, conversionApi )

    Fired for removed nodes.

    See source

    remove is a namespace for a class of events. Names of actually called events follow this pattern: remove:name. name is either '$text', when a text node has been removed, or the name of removed element.

    This way listeners can either listen to a general remove event or specific event (for example remove:paragraph).

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object

    Additional information about the change.

    Properties
    data.position : Position

    Position from which the node has been removed.

    data.length : Number

    Offset size of the removed node.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.

  • removeMarker( eventInfo, data = { data.markerRange, data.markerName }, conversionApi )

    Fired when marker is removed from the model.

    See source

    removeMarker is a namespace for a class of events. Names of actually called events follow this pattern: removeMarker:markerName. By specifying certain marker names, you can make the events even more gradual. For example, if markers are named foo:abc, foo:bar, then it is possible to listen to removeMarker:foo or removeMarker:foo:abc and removeMarker:foo:bar events.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object

    Additional information about the change.

    Properties
    data.markerRange : Range

    Marker range.

    data.markerName : String

    Marker name.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.

  • selection( eventInfo, selection, consumable, conversionApi )

    Fired for selection changes.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    selection : Selection

    Selection that is converted.

    consumable : ModelConsumable

    Values to consume.

    conversionApi : Object

    Conversion interface to be used by callback, passed in DowncastDispatcher constructor.