CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

ModelConsumable (engine/conversion)

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

class
See source

Manages a list of consumable values for the 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 DowncastDispatcher while analyzing the changed parts of 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 DowncastDispatcher gather consumable values, so there is no need to use the add method directly. However, it is important to understand how consumable values can be consumed. See 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();
} );

Filtering

Properties

  • private

    _consumable : Map<any, Map<string, boolean>>

    See source

    Contains list of consumable values.

  • private

    _textProxyRegistry : Map<null | number, Map<null | number, Map<unknown, symbol>>>

    See source

    For each TextProxy added to ModelConsumable, this registry holds a parent of that TextProxy and the start and end indices of that TextProxy. This allows identification of the TextProxy instances that point to the same part of the model but are different instances. Each distinct TextProxy is given a unique Symbol which is then registered as consumable. This process is transparent for the ModelConsumable API user because whenever TextProxy is added, tested, consumed or reverted, the internal mechanisms of ModelConsumable translate TextProxy to that unique Symbol.

Methods

  • add( item, type ) → void

    See source

    Adds a consumable value to the consumables list and links it with a given model item.

    modelConsumable.add( modelElement, 'insert' ); // Add `modelElement` insertion change to consumable values.
modelConsumable.add( modelElement, 'addAttribute:bold' ); // Add `bold` attribute insertion on `modelElement` change.
modelConsumable.add( modelElement, 'removeAttribute:bold' ); // Add `bold` attribute removal on `modelElement` change.
modelConsumable.add( modelSelection, 'selection' ); // Add `modelSelection` to consumable values.
modelConsumable.add( modelRange, 'range' ); // Add `modelRange` to consumable values.

    Parameters

    item : Range | Selection | DocumentSelection | Item

    Model item, range or selection that has the consumable.

    type : string

    Consumable type. Will be normalized to a proper form, that is either <word> or <part>:<part>. Second colon and everything after will be cut. Passing event name is a safe and good practice.

    Returns

    void

  • consume( item, type ) → boolean

    See source

    Removes a given consumable value from a given model item.

    modelConsumable.consume( modelElement, 'insert' ); // Remove `modelElement` insertion change from consumable values.
modelConsumable.consume( modelElement, 'addAttribute:bold' ); // Remove `bold` attribute insertion on `modelElement` change.
modelConsumable.consume( modelElement, 'removeAttribute:bold' ); // Remove `bold` attribute removal on `modelElement` change.
modelConsumable.consume( modelSelection, 'selection' ); // Remove `modelSelection` from consumable values.
modelConsumable.consume( modelRange, 'range' ); // Remove 'modelRange' from consumable values.

    Parameters

    item : Range | Selection | DocumentSelection | Item

    Model item, range or selection from which consumable will be consumed.

    type : string

    Consumable type. Will be normalized to a proper form, that is either <word> or <part>:<part>. Second colon and everything after will be cut. Passing event name is a safe and good practice.

    Returns

    boolean

    true if consumable value was available and was consumed, false otherwise.

  • revert( item, type ) → null | boolean

    See source

    Reverts consuming of a consumable value.

    modelConsumable.revert( modelElement, 'insert' ); // Revert consuming `modelElement` insertion change.
modelConsumable.revert( modelElement, 'addAttribute:bold' ); // Revert consuming `bold` attribute insert from `modelElement`.
modelConsumable.revert( modelElement, 'removeAttribute:bold' ); // Revert consuming `bold` attribute remove from `modelElement`.
modelConsumable.revert( modelSelection, 'selection' ); // Revert consuming `modelSelection`.
modelConsumable.revert( modelRange, 'range' ); // Revert consuming `modelRange`.

    Parameters

    item : Range | Selection | DocumentSelection | Item

    Model item, range or selection to be reverted.

    type : string

    Consumable type.

    Returns

    null | boolean

    true if consumable has been reversed, false otherwise. null if the consumable has never been added.

  • test( item, type ) → null | boolean

    See source

    Tests whether there is a consumable value of a given type connected with a given model item.

    modelConsumable.test( modelElement, 'insert' ); // Check for `modelElement` insertion change.
modelConsumable.test( modelElement, 'addAttribute:bold' ); // Check for `bold` attribute insertion on `modelElement` change.
modelConsumable.test( modelElement, 'removeAttribute:bold' ); // Check for `bold` attribute removal on `modelElement` change.
modelConsumable.test( modelSelection, 'selection' ); // Check if `modelSelection` is consumable.
modelConsumable.test( modelRange, 'range' ); // Check if `modelRange` is consumable.

    Parameters

    item : Range | Selection | DocumentSelection | Item

    Model item, range or selection to be tested.

    type : string

    Consumable type. Will be normalized to a proper form, that is either <word> or <part>:<part>. Second colon and everything after will be cut. Passing event name is a safe and good practice.

    Returns

    null | boolean

    null if such consumable was never added, false if the consumable values was already consumed or true if it was added and not consumed yet.

  • verifyAllConsumed( eventGroup ) → void

    See source

    Verifies if all events from the specified group were consumed.

    Parameters

    eventGroup : string

    The events group to verify.

    Returns

    void

  • internal

    _getSymbolForTextProxy( textProxy ) → symbol

    See source

    Gets a unique symbol for the passed TextProxy instance. All TextProxy instances that have same parent, same start index and same end index will get the same symbol.

    Used internally to correctly consume TextProxy instances.

    Parameters

    textProxy : TextProxy

    TextProxy instance to get a symbol for.

    Returns

    symbol

    Symbol representing all equal instances of TextProxy.

  • private

    _addSymbolForTextProxy( textProxy ) → symbol

    See source

    Adds a symbol for the given TextProxy instance.

    Used internally to correctly consume TextProxy instances.

    Parameters

    textProxy : TextProxy

    Text proxy instance.

    Returns

    symbol

    Symbol generated for given TextProxy.