Class ModelConsumable

Manages a list of consumable values for the module:engine/model/item~ModelItem model items.

Consumables are various aspects of the model. A model item can be broken down into separate, single properties that might be taken into consideration when converting that item.

ModelConsumable is used by module:engine/conversion/downcastdispatcher~DowncastDispatcher while analyzing the changed parts of module:engine/model/document~ModelDocument the document. The added / changed / removed model items are broken down into singular properties (the item itself and its attributes). All those parts are saved in ModelConsumable. Then, during conversion, when the given part of a model item is converted (i.e. the view element has been inserted into the view, but without attributes), the consumable value is removed from ModelConsumable.

For model items, ModelConsumable stores consumable values of one of following types: insert, addattribute:<attributeKey>, changeattributes:<attributeKey>, removeattributes:<attributeKey>.

In most cases, it is enough to let th module:engine/conversion/downcastdispatcher~DowncastDispatcher gather consumable values, so there is no need to use the module:engine/conversion/modelconsumable~ModelConsumable#add add method directly. However, it is important to understand how consumable values can be module:engine/conversion/modelconsumable~ModelConsumable#consume consumed. See module:engine/conversion/downcasthelpers default downcast converters for more information.

Keep in mind that one conversion event may have multiple callbacks (converters) attached to it. Each of those is able to convert one or more parts of the model. However, when one of those callbacks actually converts something, the others should not, because they would duplicate the results. Using ModelConsumable helps to avoid this situation, because callbacks should only convert these values that were not yet consumed from ModelConsumable.

Consuming multiple values in a single callback:

// Converter for custom `imageBlock` element that might have a `caption` element inside which changes
// how the image is displayed in the view:
//
// Model:
//
// [imageBlock]
//   └─ [caption]
//       └─ foo
//
// View:
//
// <figure>
//   ├─ <img />
//   └─ <caption>
//       └─ foo
modelConversionDispatcher.on( 'insert:imageBlock', ( evt, data, conversionApi ) => {
	// First, consume the `imageBlock` element.
	conversionApi.consumable.consume( data.item, 'insert' );

	// Just create normal image element for the view.
	// Maybe it will be "decorated" later.
	const viewImage = new ViewElement( 'img' );
	const insertPosition = conversionApi.mapper.toViewPosition( data.range.start );
	const viewWriter = conversionApi.writer;

	// Check if the `imageBlock` element has children.
	if ( data.item.childCount > 0 ) {
		const modelCaption = data.item.getChild( 0 );

		// `modelCaption` insertion change is consumed from consumable values.
		// It will not be converted by other converters, but it's children (probably some text) will be.
		// Through mapping, converters for text will know where to insert contents of `modelCaption`.
		if ( conversionApi.consumable.consume( modelCaption, 'insert' ) ) {
			const viewCaption = new ViewElement( 'figcaption' );

			const viewImageHolder = new ViewElement( 'figure', null, [ viewImage, viewCaption ] );

			conversionApi.mapper.bindElements( modelCaption, viewCaption );
			conversionApi.mapper.bindElements( data.item, viewImageHolder );
			viewWriter.insert( insertPosition, viewImageHolder );
		}
	} else {
		conversionApi.mapper.bindElements( data.item, viewImage );
		viewWriter.insert( insertPosition, viewImage );
	}

	evt.stop();
} );
Copy