Class UpcastDispatcher

Upcast dispatcher is a central point of the view-to-model conversion, which is a process of converting a given module:engine/view/documentfragment~ViewDocumentFragment view document fragment or module:engine/view/element~ViewElement view element into a correct model structure.

During the conversion process, the dispatcher fires events for all module:engine/view/node~ViewNode view nodes from the converted view document fragment. Special callbacks called "converters" should listen to these events in order to convert the view nodes.

The second parameter of the callback is the data object with the following properties:

• data.viewItem contains a module:engine/view/node~ViewNode view node or a module:engine/view/documentfragment~ViewDocumentFragment view document fragment that is converted at the moment and might be handled by the callback.
• data.modelRange is used to point to the result of the current conversion (e.g. the element that is being inserted) and is always a module:engine/model/range~ModelRange when the conversion succeeds.
• data.modelCursor is a module:engine/model/position~ModelPosition position on which the converter should insert the newly created items.

The third parameter of the callback is an instance of module:engine/conversion/upcastdispatcher~UpcastConversionApi which provides additional tools for converters.

You can read more about conversion in the {@glink framework/deep-dive/conversion/upcast Upcast conversion} guide.

Examples of event-based converters:

// A converter for links (<a>).
editor.data.upcastDispatcher.on( 'element:a', ( evt, data, conversionApi ) => {
	if ( conversionApi.consumable.consume( data.viewItem, { name: true, attributes: [ 'href' ] } ) ) {
		// The <a> element is inline and is represented by an attribute in the model.
		// This is why you need to convert only children.
		const { modelRange } = conversionApi.convertChildren( data.viewItem, data.modelCursor );

		for ( let item of modelRange.getItems() ) {
			if ( conversionApi.schema.checkAttribute( item, 'linkHref' ) ) {
				conversionApi.writer.setAttribute( 'linkHref', data.viewItem.getAttribute( 'href' ), item );
			}
		}
	}
} );

// Convert <p> element's font-size style.
// Note: You should use a low-priority observer in order to ensure that
// it is executed after the element-to-element converter.
editor.data.upcastDispatcher.on( 'element:p', ( evt, data, conversionApi ) => {
	const { consumable, schema, writer } = conversionApi;

	if ( !consumable.consume( data.viewItem, { style: 'font-size' } ) ) {
		return;
	}

	const fontSize = data.viewItem.getStyle( 'font-size' );

	// Do not go for the model element after data.modelCursor because it might happen
	// that a single view element was converted to multiple model elements. Get all of them.
	for ( const item of data.modelRange.getItems( { shallow: true } ) ) {
		if ( schema.checkAttribute( item, 'fontSize' ) ) {
			writer.setAttribute( 'fontSize', fontSize, item );
		}
	}
}, { priority: 'low' } );

// Convert all elements which have no custom converter into a paragraph (autoparagraphing).
editor.data.upcastDispatcher.on( 'element', ( evt, data, conversionApi ) => {
	// Check if an element can be converted.
	if ( !conversionApi.consumable.test( data.viewItem, { name: data.viewItem.name } ) ) {
		// When an element is already consumed by higher priority converters, do nothing.
		return;
	}

	const paragraph = conversionApi.writer.createElement( 'paragraph' );

	// Try to safely insert a paragraph at the model cursor - it will find an allowed parent for the current element.
	if ( !conversionApi.safeInsert( paragraph, data.modelCursor ) ) {
		// When an element was not inserted, it means that you cannot insert a paragraph at this position.
		return;
	}

	// Consume the inserted element.
	conversionApi.consumable.consume( data.viewItem, { name: data.viewItem.name } ) );

	// Convert the children to a paragraph.
	const { modelRange } = conversionApi.convertChildren( data.viewItem,  paragraph ) );

	// Update `modelRange` and `modelCursor` in the `data` as a conversion result.
	conversionApi.updateConversionResult( paragraph, data );
}, { priority: 'low' } );
Copy