CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
Class

ModelConsumable (engine/conversion)

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

class

Manages a list of consumable values for model items.

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

ModelConsumable is used by DowncastDispatcher while analyzing changed parts of the document. The added / changed / removed model items are broken down into singular properties (the item itself and it's attributes). All those parts are saved in ModelConsumable. Then, during conversion, when given part of model item is converted (i.e. the view element has been inserted into the view, but without attributes), 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 DowncastDispatcher gather consumable values, so there is no need to use 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, other should not, because they would duplicate the results. Using ModelConsumable helps avoiding this situation, because callbacks should only convert those values, which were not yet consumed from ModelConsumable.

Consuming multiple values in a single callback:

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

    // Check if the `image` 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

  • _consumable : Map

    private

    Contains list of consumable values.

  • _textProxyRegistry : Map

    private

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

Methods

  • constructor()

    Creates an empty consumables list.

  • add( item, type )

    Adds a consumable value to the consumables list and links it with 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 : Item | Selection | Range

    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.

  • consume( item, type ) → Boolean

    Removes given consumable value from 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 : Item | Selection | Range

    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

    Reverts consuming of 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 : Item | Selection | Range

    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

    Tests whether there is a consumable value of given type connected with 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 : Item | Selection | Range

    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.

  • _addSymbolForTextProxy( startIndex, endIndex, parent ) → Symbol

    private

    Adds a symbol for given properties that characterizes a TextProxy instance.

    Used internally to correctly consume TextProxy instances.

    Parameters

    startIndex : Number

    Text proxy start index in it's parent.

    endIndex : Number

    Text proxy end index in it's parent.

    parent : Element

    Text proxy parent.

    Returns

    Symbol

    Symbol generated for given properties.

  • _getSymbolForTextProxy( textProxy ) → Symbol

    private

    Gets a unique symbol for 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.