Class DowncastDispatcher

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 module:engine/model/differ~Differ 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 module:engine/conversion/mapper~Mapper.

Downcast dispatcher fires the following events for model tree changes:

• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert – If a range of nodes was inserted to the model tree.
• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:remove remove – If a range of nodes was removed from the model tree.
• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute – If an attribute was added, changed or removed from a model node.

For module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert and module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute, the downcast dispatcher generates module:engine/conversion/modelconsumable~ModelConsumable 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 module:engine/model/markercollection~Marker marker changes:

• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker addMarker – If a marker was added.
• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker removeMarker – If a marker was removed.

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 module:engine/model/selection model selection conversion:

• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:selection selection – Converts the selection from the model to the view.
• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute – Fired for every selection attribute.
• module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker 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 module:engine/conversion/modelconsumable~ModelConsumable#consume 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 module:engine/view/downcastwriter~ViewDowncastWriter view downcast writer to apply changes to the view document.

You can read more about conversion in the following guide:

• {@glink framework/deep-dive/conversion/downcast Downcast conversion}

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