CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DowncastDispatcher (engine/conversion)

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

class
See source

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

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

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

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

Downcast dispatcher fires the following events for model tree changes:

  • insert – If a range of nodes was inserted to the model tree.
  • remove – If a range of nodes was removed from the model tree.
  • attribute – If an attribute was added, changed or removed from a model node.

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

Additionally, downcast dispatcher fires events for marker changes:

Note that changing a marker is done through removing the marker from the old range and adding it to the new range, so both of these events are fired.

Finally, a downcast dispatcher also handles firing events for the model selection conversion:

  • selection – Converts the selection from the model to the view.
  • attribute – Fired for every selection attribute.
  • addMarker – Fired for every marker that contains a selection.

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

When providing custom listeners for a downcast dispatcher, remember to check whether a given change has not been consumed yet.

When providing custom listeners for a downcast dispatcher, keep in mind that you should not stop the event. If you stop it, then the default converter at the lowest priority will not trigger the conversion of this node's attributes and child nodes.

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

You can read more about conversion in the following guide:

An example of a custom converter for the downcast dispatcher:

// You will convert inserting a "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 the position in the model to a position in the view.
	const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );

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

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

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

Filtering

Properties

  • internal readonly

    _conversionApi : Pick<DowncastConversionApi, 'schema' | 'dispatcher' | 'mapper'>

    See source

    A template for an interface passed by the dispatcher to the event callbacks.

  • private readonly

    _firedEventsMap : WeakMap<DowncastConversionApi, Map<unknown, Set<string>>>

    See source

    A map of already fired events for a given ModelConsumable.

Methods

  • constructor( conversionApi )

    See source

    Creates a downcast dispatcher instance.

    Parameters

    conversionApi : Pick<DowncastConversionApi, 'schema' | 'mapper'>

    Additional properties for an interface that will be passed to events fired by the downcast dispatcher.

    Related:

  • convert( range, markers, writer, options ) → void

    See source

    Starts a conversion of a model range and the provided markers.

    Parameters

    range : Range

    The inserted range.

    markers : Map<string, Range>

    The map of markers that should be down-casted.

    writer : DowncastWriter

    The view writer that should be used to modify the view document.

    options : Record<string, unknown>

    Optional options object passed to convertionApi.options.

    Defaults to {}

    Returns

    void

    Fires

  • convertChanges( differ, markers, writer ) → void

    See source

    Converts changes buffered in the given model differ and fires conversion events based on it.

    Parameters

    differ : Differ

    The differ object with buffered changes.

    markers : MarkerCollection

    Markers related to the model fragment to convert.

    writer : DowncastWriter

    The view writer that should be used to modify the view document.

    Returns

    void

    Fires

  • convertSelection( selection, markers, writer ) → void

    See source

    Starts the model selection conversion.

    Fires events for a given selection to start the selection conversion.

    Parameters

    selection : Selection | DocumentSelection

    The selection to convert.

    markers : MarkerCollection

    Markers connected with the converted model.

    writer : DowncastWriter

    View writer that should be used to modify the view document.

    Returns

    void

    Fires

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

    // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired.

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

    Stops delegating events. It can be used at different levels:

    • To stop delegating all events.
    • To stop delegating a specific event to all emitters.
    • To stop delegating a specific event to a specific emitter.

    Parameters

    [ event ] : string

    The name of the event to stop delegating. If omitted, stops it all delegations.

    [ emitter ] : Emitter

    (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

    Stops listening for events. It can be used at different levels:

    • To stop listening to a specific callback.
    • To stop listening to a specific event.
    • To stop listening to all events fired by a specific object.
    • To stop listening to all events fired by all objects.

    Parameters

    [ emitter ] : Emitter

    The object to stop listening to. If omitted, stops it for all objects.

    [ event ] : string

    (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

    [ callback ] : Function

    (Requires the event) The function to be removed from the call list for the given event.

    Returns

    void

  • private

    _addConsumablesForInsert( consumable, walkerValues ) → ModelConsumable

    See source

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

    Parameters

    consumable : ModelConsumable

    The consumable.

    walkerValues : Iterable<TreeWalkerValue>

    The walker values for the inserted range.

    Returns

    ModelConsumable

    The values to consume.

  • private

    _addConsumablesForRange( consumable, range, type ) → ModelConsumable

    See source

    Populates provided ModelConsumable with values to consume for a given range.

    Parameters

    consumable : ModelConsumable

    The consumable.

    range : Range

    The affected range.

    type : string

    Consumable type.

    Returns

    ModelConsumable

    The values to consume.

  • private

    _addConsumablesForSelection( consumable, selection, markers ) → ModelConsumable

    See source

    Populates provided ModelConsumable with selection consumable values.

    Parameters

    consumable : ModelConsumable

    The consumable.

    selection : Selection | DocumentSelection

    The selection to create the consumable from.

    markers : Iterable<Marker>

    Markers that contain the selection.

    Returns

    ModelConsumable

    The values to consume.

  • private

    _convertAttribute( range, key, oldValue, newValue, conversionApi ) → void

    See source

    Starts a conversion of an attribute change on a given range.

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

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

    newValue : unknown

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

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

    Fires

  • private

    _convertInsert( range, conversionApi, options = { [options.doNotAddConsumables] } ) → void

    See source

    Fires insertion conversion of a range of nodes.

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

    Parameters

    range : Range

    The inserted range.

    conversionApi : DowncastConversionApi

    The conversion API object.

    options : object
    Properties
    [ options.doNotAddConsumables ] : boolean

    Whether the ModelConsumable should not get populated for items in the provided range.

    Defaults to {}

    Returns

    void

    Fires

  • private

    _convertMarkerAdd( markerName, markerRange, conversionApi ) → void

    See source

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

    Parameters

    markerName : string

    Marker name.

    markerRange : Range

    The marker range.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

    Fires

  • private

    _convertMarkerRemove( markerName, markerRange, conversionApi ) → void

    See source

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

    Parameters

    markerName : string

    Marker name.

    markerRange : Range

    The marker range.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

    Fires

  • private

    _convertReinsert( range, conversionApi ) → void

    See source

    Fires re-insertion conversion (with a reconversion flag passed to insert events) of a range of elements (only elements on the range depth, without children).

    For each node in the range on its depth (without children), insert event is fired. For each attribute on each node, attribute event is fired.

    Parameters

    range : Range

    The range to reinsert.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

    Fires

  • private

    _convertRemove( position, length, name, conversionApi ) → void

    See source

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

    Parameters

    position : Position

    Position from which node was removed.

    length : number

    Offset size of removed node.

    name : string

    Name of removed node.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

  • private

    _createConversionApi( writer, refreshedItems, options ) → DowncastConversionApi

    See source

    Builds an instance of the DowncastConversionApi from a template and a given DowncastWriter and options object.

    Parameters

    writer : DowncastWriter

    View writer that should be used to modify the view document.

    refreshedItems : Set<Item>

    A set of model elements that should not reuse their previous view representations.

    Defaults to ...

    options : Record<string, unknown>

    Optional options passed to convertionApi.options.

    Defaults to {}

    Returns

    DowncastConversionApi

    The conversion API object.

  • private

    _reduceChanges( changes ) → Iterable<DiffItem | DiffItemReinsert>

    See source

    Fires the reduction of changes buffered in the Differ.

    Features can replace selected DiffItems with reinsert entries to trigger reconversion. The DowncastHelpers.elementToStructure() is using this event to trigger reconversion.

    Parameters

    changes : Iterable<DiffItem>

    Returns

    Iterable<DiffItem | DiffItemReinsert>

    Fires

  • private

    _testAndFire( type, data, conversionApi ) → void

    See source

    Tests whether given event wasn't already fired and if so, fires it.

    Type parameters

    TType

    Parameters

    type : TType | `${ TType }:${ string }`

    Event type.

    data : EventMap<Item>[ TType ]

    Event data.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

    Fires

  • private

    _testAndFireAddAttributes( item, conversionApi ) → void

    See source

    Fires not already fired events for setting attributes on just inserted item.

    Parameters

    item : Item

    The model item to convert attributes for.

    conversionApi : DowncastConversionApi

    The conversion API object.

    Returns

    void

Events

  • addMarker( eventInfo, data, conversionApi )

    See source

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

    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,
    • conversionApi.consumable includes each item of the marker range and the consumable value is same as the event name.

    If the marker range is collapsed:

    • there is only one event,
    • conversionApi.consumable includes marker range with the event name.

    If the selection inside a marker is converted:

    • there is only one event,
    • conversionApi.consumable includes the selection instance with the event name.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : EventMap<TItem>[ TName ]

    Additional information about the change.

    conversionApi : DowncastConversionApi

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

  • attribute( eventInfo, data, conversionApi )

    See source

    Fired in the following cases:

    • when an attribute has been added, changed, or removed from a node,
    • when a node with an attribute is inserted,
    • when a 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:imageBlock).

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : EventMap<TItem>[ TName ]

    Additional information about the change.

    conversionApi : DowncastConversionApi

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

  • cleanSelection( eventInfo, data, conversionApi )

    See source

    Fired at the beginning of selection conversion, before selection events.

    Should be used to clean up the view state at the current selection position, before the selection is moved to another place.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : EventMap<TItem>[ TName ]
    conversionApi : DowncastConversionApi

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

  • insert( eventInfo, data, conversionApi )

    See source

    Fired for inserted nodes.

    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, the 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 : EventMap<TItem>[ TName ]

    Additional information about the change.

    conversionApi : DowncastConversionApi

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

  • reduceChanges( eventInfo, data )

    See source

    Fired to enable reducing (transforming) changes buffered in the Differ before convertChanges() will fire any conversion events.

    For instance, a feature can replace selected DiffItems with a reinsert entry to trigger reconversion of an element when e.g. its attribute has changes. The * DowncastHelpers.elementToStructure() helper is using this event to trigger reconversion of an element when the element, its attributes or direct children changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : DowncastReduceChangesEventData

  • remove( eventInfo, data, conversionApi )

    See source

    Fired for removed nodes.

    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 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 : EventMap<TItem>[ TName ]

    Additional information about the change.

    conversionApi : DowncastConversionApi

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

  • removeMarker( eventInfo, data, conversionApi )

    See source

    Fired when a marker is removed from the model.

    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 : EventMap<TItem>[ TName ]

    Additional information about the change.

    conversionApi : DowncastConversionApi

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

  • selection( eventInfo, data, conversionApi )

    See source

    Fired for selection changes.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : EventMap<TItem>[ TName ]
    conversionApi : DowncastConversionApi

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