CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
Home/CKEditor 5/API
Class

ViewConsumable (engine/conversion)

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

class
See source

Class used for handling consumption of view elements, text nodes and document fragments. 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. To test items use test method. To consume items use consume method. To revert already consumed items use revert method.

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.

Filtering

Properties

Methods

  • constructor()

    Creates new ViewConsumable.

    See source

  • add( element, [ consumables ] = { consumables.name, consumables.attributes, consumables.classes, consumables.styles } )

    Adds view element, text node or document fragment as ready to be consumed.

    See source
    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 viewconsumable-invalid-attribute when class or style attribute is provided - it should be handled separately by providing actual style/class.

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

    Parameters

    element : Element | Text | DocumentFragment
    [ consumables ] : Object

    Used only if first parameter is view element instance.

    Properties
    consumables.name : Boolean

    If set to true element's name will be included.

    consumables.attributes : String | Array.<String>

    Attribute name or array of attribute names.

    consumables.classes : String | Array.<String>

    Class name or array of class names.

    consumables.styles : String | Array.<String>

    Style name or array of style names.

  • consume( element, [ consumables ] = { consumables.name, consumables.attributes, consumables.classes, consumables.styles } ) → Boolean

    Consumes view element, text node or document fragment. It returns true when all items included in method's call can be consumed, otherwise returns false.

    See source
    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.

    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.

    Parameters

    element : Element | Text | DocumentFragment
    [ consumables ] : Object

    Used only if first parameter is view element instance.

    Properties
    consumables.name : Boolean

    If set to true element's name will be included.

    consumables.attributes : String | Array.<String>

    Attribute name or array of attribute names.

    consumables.classes : String | Array.<String>

    Class name or array of class names.

    consumables.styles : String | Array.<String>

    Style name or array of style names.

    Returns

    Boolean

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

  • revert( element, [ consumables ] = { consumables.name, consumables.attributes, consumables.classes, consumables.styles } )

    Reverts view element, text node or document fragment 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.

    See source
    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.

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

    Parameters

    element : Element | Text | DocumentFragment
    [ consumables ] : Object

    Used only if first parameter is view element instance.

    Properties
    consumables.name : Boolean

    If set to true element's name will be included.

    consumables.attributes : String | Array.<String>

    Attribute name or array of attribute names.

    consumables.classes : String | Array.<String>

    Class name or array of class names.

    consumables.styles : String | Array.<String>

    Style name or array of style names.

  • test( element, [ consumables ] = { consumables.name, consumables.attributes, consumables.classes, consumables.styles } ) → Boolean | null

    Tests if view element, text node or document fragment 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.

    See source
    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.

    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.

    Parameters

    element : Element | Text | DocumentFragment
    [ consumables ] : Object

    Used only if first parameter is view element instance.

    Properties
    consumables.name : Boolean

    If set to true element's name will be included.

    consumables.attributes : String | Array.<String>

    Attribute name or array of attribute names.

    consumables.classes : String | Array.<String>

    Class name or array of class names.

    consumables.styles : String | Array.<String>

    Style name or array of style names.

    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

  • consumablesFromElement( element ) → Object

    static

    Creates consumable object from view element. Consumable object will include element's name and all its attributes, classes and styles.

    See source

    Parameters

    element : Element

    Returns

    Object

    consumables

  • createFrom( from, [ instance ] )

    static

    Creates ViewConsumable instance from node or document fragment. Instance will contain all elements, child nodes, attributes, styles and classes added for consumption.

    See source

    Parameters

    from : Node | DocumentFragment

    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.