# ViewConsumable

class

Class used for handling consumption of view [elements](module_engine_view_element-ViewElement.md), [text nodes](module_engine_view_text-ViewText.md) and [document fragments](module_engine_view_documentfragment-ViewDocumentFragment.md). Element's name and its parts (attributes, classes and styles) can be consumed separately. Consuming an element's name does not consume its attributes, classes and styles. To add items for consumption use [add method](#function-add). To test items use [test method](#function-test). To consume items use [consume method](#function-consume). To revert already consumed items use [revert method](#function-revert).

```typescript
viewConsumable.add( element, { name: true } ); // Adds element's name as ready to be consumed.
viewConsumable.add( textNode ); // Adds text node for consumption.
viewConsumable.add( docFragment ); // Adds document fragment for consumption.
viewConsumable.test( element, { name: true }  ); // Tests if element's name can be consumed.
viewConsumable.test( textNode ); // Tests if text node can be consumed.
viewConsumable.test( docFragment ); // Tests if document fragment can be consumed.
viewConsumable.consume( element, { name: true }  ); // Consume element's name.
viewConsumable.consume( textNode ); // Consume text node.
viewConsumable.consume( docFragment ); // Consume document fragment.
viewConsumable.revert( element, { name: true }  ); // Revert already consumed element's name.
viewConsumable.revert( textNode ); // Revert already consumed text node.
viewConsumable.revert( docFragment ); // Revert already consumed document fragment.
```

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

<a id="properties">

## Properties

<a id="member-_consumables">

### `_consumables: Map<ViewNode | ViewDocumentFragment, boolean | ViewElementConsumables>` _(private)_

Map of consumable elements. If [element](module_engine_view_element-ViewElement.md) is used as a key, [ViewElementConsumables](module_engine_conversion_viewconsumable-ViewElementConsumables.md) instance is stored as value. For [text nodes](module_engine_view_text-ViewText.md) and [document fragments](module_engine_view_documentfragment-ViewDocumentFragment.md) boolean value is stored as value.

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

<a id="methods">

## Methods

<a id="function-add">

### `add( element, consumables? ) → void`

Adds view [element](module_engine_view_element-ViewElement.md), [text node](module_engine_view_text-ViewText.md) or [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md) as ready to be consumed.

```typescript
viewConsumable.add( p, { name: true } ); // Adds element's name to consume.
viewConsumable.add( p, { attributes: 'name' } ); // Adds element's attribute.
viewConsumable.add( p, { classes: 'foobar' } ); // Adds element's class.
viewConsumable.add( p, { styles: 'color' } ); // Adds element's style
viewConsumable.add( p, { attributes: 'name', styles: 'color' } ); // Adds attribute and style.
viewConsumable.add( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be provided.
viewConsumable.add( textNode ); // Adds text node to consume.
viewConsumable.add( docFragment ); // Adds document fragment to consume.
```

Throws [CKEditorError](module_utils_ckeditorerror-CKEditorError.md) `viewconsumable-invalid-attribute` when `class` or `style` attribute is provided - it should be handled separately by providing actual style/class.

```typescript
viewConsumable.add( p, { attributes: 'style' } ); // This call will throw an exception.
viewConsumable.add( p, { styles: 'color' } ); // This is properly handled style.
```

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

#### Parameters

* `element: ViewText | ViewElement | ViewDocumentFragment`

* `consumables?: Consumables | ViewNormalizedConsumables`

  Used only if first parameter is [view element](module_engine_view_element-ViewElement.md) instance.

#### Returns

* `void`

<a id="function-consume">

### `consume( element, consumables? ) → boolean`

Consumes [view element](module_engine_view_element-ViewElement.md), [text node](module_engine_view_text-ViewText.md) or [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md). It returns `true` when all items included in method's call can be consumed, otherwise returns `false`.

```typescript
viewConsumable.consume( p, { name: true } ); // Consumes element's name.
viewConsumable.consume( p, { attributes: 'name' } ); // Consumes element's attribute.
viewConsumable.consume( p, { classes: 'foobar' } ); // Consumes element's class.
viewConsumable.consume( p, { styles: 'color' } ); // Consumes element's style.
viewConsumable.consume( p, { attributes: 'name', styles: 'color' } ); // Consumes attribute and style.
viewConsumable.consume( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be consumed.
viewConsumable.consume( textNode ); // Consumes text node.
viewConsumable.consume( docFragment ); // Consumes document fragment.
```

Consuming classes and styles as attribute will test if all added classes/styles can be consumed.

```typescript
viewConsumable.consume( p, { attributes: 'class' } ); // Consume only if all added classes can be consumed.
viewConsumable.consume( p, { attributes: 'style' } ); // Consume only if all added styles can be consumed.
```

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

#### Parameters

* `element: ViewNode | ViewDocumentFragment`

* `consumables?: Consumables | Match`

  Used only if first parameter is [view element](module_engine_view_element-ViewElement.md) instance.

#### Returns

* `boolean`

  Returns `true` when all items included in method's call can be consumed, otherwise returns `false`.

<a id="function-revert">

### `revert( element, consumables ) → void`

Reverts [view element](module_engine_view_element-ViewElement.md), [text node](module_engine_view_text-ViewText.md) or [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md) so they can be consumed once again. Method does not revert items that were never previously added for consumption, even if they are included in method's call.

```typescript
viewConsumable.revert( p, { name: true } ); // Reverts element's name.
viewConsumable.revert( p, { attributes: 'name' } ); // Reverts element's attribute.
viewConsumable.revert( p, { classes: 'foobar' } ); // Reverts element's class.
viewConsumable.revert( p, { styles: 'color' } ); // Reverts element's style.
viewConsumable.revert( p, { attributes: 'name', styles: 'color' } ); // Reverts attribute and style.
viewConsumable.revert( p, { classes: [ 'baz', 'bar' ] } ); // Multiple names can be reverted.
viewConsumable.revert( textNode ); // Reverts text node.
viewConsumable.revert( docFragment ); // Reverts document fragment.
```

Reverting classes and styles as attribute will revert all classes/styles that were previously added for consumption.

```typescript
viewConsumable.revert( p, { attributes: 'class' } ); // Reverts all classes added for consumption.
viewConsumable.revert( p, { attributes: 'style' } ); // Reverts all styles added for consumption.
```

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

#### Parameters

* `element: ViewNode`

* `consumables: Consumables | Match`

  Used only if first parameter is [view element](module_engine_view_element-ViewElement.md) instance.

#### Returns

* `void`

<a id="function-test">

### `test( element, consumables? ) → boolean | null`

Tests if [view element](module_engine_view_element-ViewElement.md), [text node](module_engine_view_text-ViewText.md) or [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md) can be consumed. It returns `true` when all items included in method's call can be consumed. Returns `false` when first already consumed item is found and `null` when first non-consumable item is found.

```typescript
viewConsumable.test( p, { name: true } ); // Tests element's name.
viewConsumable.test( p, { attributes: 'name' } ); // Tests attribute.
viewConsumable.test( p, { classes: 'foobar' } ); // Tests class.
viewConsumable.test( p, { styles: 'color' } ); // Tests style.
viewConsumable.test( p, { attributes: 'name', styles: 'color' } ); // Tests attribute and style.
viewConsumable.test( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be tested.
viewConsumable.test( textNode ); // Tests text node.
viewConsumable.test( docFragment ); // Tests document fragment.
```

Testing classes and styles as attribute will test if all added classes/styles can be consumed.

```typescript
viewConsumable.test( p, { attributes: 'class' } ); // Tests if all added classes can be consumed.
viewConsumable.test( p, { attributes: 'style' } ); // Tests if all added styles can be consumed.
```

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

#### Parameters

* `element: ViewNode | ViewDocumentFragment`

* `consumables?: Consumables | Match`

  Used only if first parameter is [view element](module_engine_view_element-ViewElement.md) instance.

#### Returns

* `boolean | null`

  Returns `true` when all items included in method's call can be consumed. Returns `false` when first already consumed item is found and `null` when first non-consumable item is found.

#### Static methods

<a id="static-function-createFrom">

### `createFrom( from, instance? ) → ViewConsumable` _(static)_

Creates [ViewConsumable](module_engine_conversion_viewconsumable-ViewConsumable.md) instance from [node](module_engine_view_node-ViewNode.md) or [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md). Instance will contain all elements, child nodes, attributes, styles and classes added for consumption.

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

#### Parameters

* `from: ViewNode | ViewDocumentFragment`

  View node or document fragment from which `ViewConsumable` will be created.

* `instance?: ViewConsumable`

  If provided, given `ViewConsumable` instance will be used to add all consumables. It will be returned instead of a new instance.

#### Returns

* `ViewConsumable`

---

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