ViewConsumable (engine/conversion)
@ckeditor/ckeditor5-engine/src/conversion/viewconsumable
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
-
private
_consumables : Map<Node | DocumentFragment, boolean | ViewElementConsumables>module:engine/conversion/viewconsumable~ViewConsumable#_consumablesMap of consumable elements. If element is used as a key, ViewElementConsumables instance is stored as value. For text nodes and document fragments boolean value is stored as value.
Methods
-
add( element, consumables ) → voidmodule:engine/conversion/viewconsumable~ViewConsumable#add:ELEMENTAdds view element as ready to be consumed.
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.Throws CKEditorError
viewconsumable-invalid-attributewhenclassorstyleattribute 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.See also:
add( textOrDocumentFragment ).Parameters
element : Elementconsumables : ConsumablesUsed only if first parameter is view element instance.
Returns
void
-
add( textOrDocumentFragment ) → voidmodule:engine/conversion/viewconsumable~ViewConsumable#add:TEXT_OR_FRAGMENTAdds text node or document fragment as ready to be consumed.
viewConsumable.add( textNode ); // Adds text node to consume. viewConsumable.add( docFragment ); // Adds document fragment to consume.See also:
add( element, consumables ).Parameters
textOrDocumentFragment : Text | DocumentFragment
Returns
void
-
consume( element, [ consumables ] ) → booleanmodule:engine/conversion/viewconsumable~ViewConsumable#consumeConsumes view element, text node or document fragment. It returns
truewhen all items included in method's call can be consumed, otherwise returnsfalse.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 : Node | DocumentFragment[ consumables ] : Match | ConsumablesUsed only if first parameter is view element instance.
Returns
booleanReturns
truewhen all items included in method's call can be consumed, otherwise returnsfalse.
-
revert( element, consumables ) → voidmodule:engine/conversion/viewconsumable~ViewConsumable#revertReverts 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.
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 : Nodeconsumables : ConsumablesUsed only if first parameter is view element instance.
Returns
void
-
test( element, [ consumables ] ) → null | booleanmodule:engine/conversion/viewconsumable~ViewConsumable#testTests if view element, text node or document fragment can be consumed. It returns
truewhen all items included in method's call can be consumed. Returnsfalsewhen first already consumed item is found andnullwhen first non-consumable item is found.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 : Node | DocumentFragment[ consumables ] : Match | ConsumablesUsed only if first parameter is view element instance.
Returns
null | booleanReturns
truewhen all items included in method's call can be consumed. Returnsfalsewhen first already consumed item is found andnullwhen first non-consumable item is found.
Static methods
-
static
consumablesFromElement( element ) → objectmodule:engine/conversion/viewconsumable~ViewConsumable.consumablesFromElementCreates consumable object from view element. Consumable object will include element's name and all its attributes, classes and styles.
Parameters
element : Element
Returns
object
-
static
createFrom( from, [ instance ] ) → ViewConsumablemodule:engine/conversion/viewconsumable~ViewConsumable.createFromCreates ViewConsumable instance from node or document fragment. Instance will contain all elements, child nodes, attributes, styles and classes added for consumption.
Parameters
from : Node | DocumentFragmentView node or document fragment from which
ViewConsumablewill be created.[ instance ] : ViewConsumableIf provided, given
ViewConsumableinstance will be used to add all consumables. It will be returned instead of a new instance.
Returns
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.