# ModelConsumable

class

Manages a list of consumable values for the [model items](module_engine_model_item-ModelItem.md).

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`](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md) while analyzing the changed parts of [the document](module_engine_model_document-ModelDocument.md). 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`](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md) gather consumable values, so there is no need to use the [add method](#function-add) directly. However, it is important to understand how consumable values can be [consumed](#function-consume). See [default downcast converters](module_engine_conversion_downcasthelpers.md) 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:

```typescript
// 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();
} );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L99)

<a id="properties">

## Properties

<a id="member-_consumable">

### `_consumable: Map<any, Map<string, boolean>>` _(private)_

Contains list of consumable values.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L103)

<a id="member-_textProxyRegistry">

### `_textProxyRegistry: Map<number | null, Map<number | null, Map<unknown, symbol>>>` _(private)_

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L113)

<a id="methods">

## Methods

<a id="function-add">

### `add( item, type ) → void`

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

```typescript
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.
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L130)

#### Parameters

* `item: ModelRange | ModelSelection | ModelDocumentSelection | ModelItem`

  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`

<a id="function-consume">

### `consume( item, type ) → boolean`

Removes a given consumable value from a given model item.

```typescript
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.
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L163)

#### Parameters

* `item: ModelRange | ModelSelection | ModelDocumentSelection | ModelItem`

  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.

<a id="function-revert">

### `revert( item, type ) → boolean | null`

Reverts consuming of a consumable value.

```typescript
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`.
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L240)

#### Parameters

* `item: ModelRange | ModelSelection | ModelDocumentSelection | ModelItem`

  Model item, range or selection to be reverted.

* `type: string`

  Consumable type.

#### Returns

* `boolean | null`

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

<a id="function-test">

### `test( item, type ) → boolean | null`

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

```typescript
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.
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L199)

#### Parameters

* `item: ModelRange | ModelSelection | ModelDocumentSelection | ModelItem`

  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

* `boolean | null`

  `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.

<a id="function-verifyAllConsumed">

### `verifyAllConsumed( eventGroup ) → void`

Verifies if all events from the specified group were consumed.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L268)

#### Parameters

* `eventGroup: string`

  The events group to verify.

#### Returns

* `void`

<a id="function-_getSymbolForTextProxy">

### `_getSymbolForTextProxy( textProxy ) → symbol` _(internal)_

Gets a unique symbol for the passed [`ModelTextProxy`](module_engine_model_textproxy-ModelTextProxy.md) instance. All `ModelTextProxy` instances that have same parent, same start index and same end index will get the same symbol.

Used internally to correctly consume `ModelTextProxy` instances.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L315)

#### Parameters

* `textProxy: ModelTextProxy`

  `ModelTextProxy` instance to get a symbol for.

#### Returns

* `symbol`

  Symbol representing all equal instances of `ModelTextProxy`.

<a id="function-_addSymbolForTextProxy">

### `_addSymbolForTextProxy( textProxy ) → symbol` _(private)_

Adds a symbol for the given [`ModelTextProxy`](module_engine_model_textproxy-ModelTextProxy.md) instance.

Used internally to correctly consume `ModelTextProxy` instances.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/modelconsumable.ts#L343)

#### Parameters

* `textProxy: ModelTextProxy`

  Text proxy instance.

#### Returns

* `symbol`

  Symbol generated for given `ModelTextProxy`.

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)