Report an issue
Module

engine/dev-utils/view

@ckeditor/ckeditor5-engine/src/dev-utils/view

module

Filtering

Classes

  • RangeParser

    private

    Private helper class used for converting ranges represented as text inside view text nodes.

  • ViewStringify

    private

    Private helper class used for converting the view tree to a string.

Functions

  • getData( view, [ options ] = { [options.withoutSelection], [options.rootName], [options.showType], [options.showPriority], [options.showAttributeElementId] } ) → String

    static

    Writes the content of the document to an HTML-like string.

    Parameters

    view : View
    [ options ] : Object
    Properties
    [ options.withoutSelection ] : Boolean

    Whether to write the selection. When set to true, the selection will not be included in the returned string.

    Defaults to false

    [ options.rootName ] : Boolean

    The name of the root from which the data should be stringified. If not provided, the default main name will be used.

    Defaults to 'main'

    [ options.showType ] : Boolean

    When set to true, the type of elements will be printed (<container:p> instead of <p>, <attribute:b> instead of <b> and <empty:img> instead of <img>).

    Defaults to false

    [ options.showPriority ] : Boolean

    When set to true, attribute element's priority will be printed (<span view-priority="12">, <b view-priority="10">).

    Defaults to false

    [ options.showAttributeElementId ] : Boolean

    When set to true, attribute element's id will be printed (<span id="marker:foo">).

    Defaults to false

    Returns

    String

    The stringified data.

  • parse( data, options = { [options.order], [options.lastRangeBackward], [options.rootElement], [options.sameSelectionCharacters] } ) → Text | Element | DocumentFragment | Object

    static

    Parses an HTML-like string and returns view tree nodes. A simple string will be converted to a text node:

    parse( 'foobar' ); // Returns an instance of text.

    Elements will be parsed with attributes as children:

    parse( '<b name="baz">foobar</b>' ); // Returns an instance of element with the `baz` attribute and a text child node.

    Multiple nodes provided on root level will be converted to a document fragment:

    parse( '<b>foo</b><i>bar</i>' ); // Returns a document fragment with two child elements.

    The method can parse multiple ranges provided in string data and return a selection instance containing these ranges. Ranges placed inside text nodes should be marked using { and } brackets:

    const { text, selection } = parse( 'f{ooba}r' );

    Ranges placed outside text nodes should be marked using [ and ] brackets:

    const { root, selection } = parse( '<p>[<b>foobar</b>]</p>' );

    Note: It is possible to unify selection markers to [ and ] for both (inside and outside text) by setting sameSelectionCharacters=true option. It is mainly used when the view parse option is used by model utilities.

    Sometimes there is a need for defining the order of ranges inside the created selection. This can be achieved by providing the range order array as an additional parameter:

    const { root, selection } = parse( '{fo}ob{ar}{ba}z', { order: [ 2, 3, 1 ] } );

    In the example above, the first range ({fo}) will be added to the selection as the second one, the second range ({ar}) will be added as the third and the third range ({ba}) will be added as the first one.

    If the selection's last range should be added as a backward one (so the selection anchor is represented by the end position and selection focus is represented by the start position), use the lastRangeBackward flag:

    const { root, selection } = parse( `{foo}bar{baz}`, { lastRangeBackward: true } );

    Some more examples and edge cases:

    // Returns an empty document fragment.
    parse( '' );
    
    // Returns an empty document fragment and a collapsed selection.
    const { root, selection } = parse( '[]' );
    
    // Returns an element and a selection that is placed inside the document fragment containing that element.
    const { root, selection } = parse( '[<a></a>]' );

    Parameters

    data : String

    An HTML-like string to be parsed.

    options : Object
    Properties
    [ options.order ] : Array.<Number>

    An array with the order of parsed ranges added to the returned Selection instance. Each element should represent the desired position of each range in the selection instance. For example: [2, 3, 1] means that the first range will be placed as the second, the second as the third and the third as the first.

    [ options.lastRangeBackward ] : Boolean

    If set to true, the last range will be added as backward to the returned selection instance.

    Defaults to false

    [ options.rootElement ] : Element | DocumentFragment

    The default root to use when parsing elements. When set to null, the root element will be created automatically. If set to Element or DocumentFragment, this node will be used as the root for all parsed nodes.

    [ options.sameSelectionCharacters ] : Boolean

    When set to false, the selection inside the text should be marked using { and } and the selection outside the ext using [ and ]. When set to true, both should be marked with [ and ] only.

    Defaults to false

    Returns

    Text | Element | DocumentFragment | Object

    Returns the parsed view node or an object with two fields: view and selection when selection ranges were included in the data to parse.

  • setData( view, data, options = { [options.rootName] } )

    static

    Sets the content of the document provided as an HTML-like string.

    Parameters

    view : View
    data : String

    An HTML-like string to write into the document.

    options : Object
    Properties
    [ options.rootName ] : String

    The root name where parsed data will be stored. If not provided, the default main name will be used.

    Defaults to 'main'

  • stringify( node, [ selectionOrPositionOrRange ], [ options ] = { [options.showType], [options.showPriority], [options.showAttributeElementId], [options.ignoreRoot], [options.sameSelectionCharacters] } ) → String

    static

    Converts view elements to HTML-like string representation. A root element can be provided as text:

    const text = new Text( 'foobar' );
    stringify( text ); // 'foobar'

    or as an element:

    const element = new Element( 'p', null, new Text( 'foobar' ) );
    stringify( element ); // '<p>foobar</p>'

    or as a document fragment:

    const text = new Text( 'foobar' );
    const b = new Element( 'b', { name: 'test' }, text );
    const p = new Element( 'p', { style: 'color:red;' } );
    const fragment = new DocumentFragment( [ p, b ] );
    
    stringify( fragment ); // '<p style="color:red;"></p><b name="test">foobar</b>'

    Additionally, a selection instance can be provided. Ranges from the selection will then be included in output data. If a range position is placed inside the element node, it will be represented with [ and ]:

    const text = new Text( 'foobar' );
    const b = new Element( 'b', null, text );
    const p = new Element( 'p', null, b );
    const selection = new Selection(
        Range.createFromParentsAndOffsets( p, 0, p, 1 )
    );
    
    stringify( p, selection ); // '<p>[<b>foobar</b>]</p>'

    If a range is placed inside the text node, it will be represented with { and }:

    const text = new Text( 'foobar' );
    const b = new Element( 'b', null, text );
    const p = new Element( 'p', null, b );
    const selection = new Selection( Range.createFromParentsAndOffsets( text, 1, text, 5 ) );
    
    stringify( p, selection ); // '<p><b>f{ooba}r</b></p>'

    Note: It is possible to unify selection markers to [ and ] for both (inside and outside text) by setting the sameSelectionCharacters=true option. It is mainly used when the view stringify option is used by model utilities.

    Multiple ranges are supported:

    const text = new Text( 'foobar' );
    const selection = new Selection( [
        Range.createFromParentsAndOffsets( text, 0, text, 1 ) ),
        Range.createFromParentsAndOffsets( text, 3, text, 5 ) )
    ] );
    
    stringify( text, selection ); // '{f}oo{ba}r'

    A range or position instance can be provided instead of the selection instance. If a range instance is provided, it will be converted to a selection containing this range. If a position instance is provided, it will be converted to a selection containing one range collapsed at this position.

    const text = new Text( 'foobar' );
    const range = Range.createFromParentsAndOffsets( text, 0, text, 1 );
    const position = new Position( text, 3 );
    
    stringify( text, range ); // '{f}oobar'
    stringify( text, position ); // 'foo{}bar'

    An additional options object can be provided. If options.showType is set to true, element's types will be presented for attribute elements, container elements empty elements and UI elements:

    const attribute = new AttributeElement( 'b' );
    const container = new ContainerElement( 'p' );
    const empty = new EmptyElement( 'img' );
    const ui = new UIElement( 'span' );
    getData( attribute, null, { showType: true } ); // '<attribute:b></attribute:b>'
    getData( container, null, { showType: true } ); // '<container:p></container:p>'
    getData( empty, null, { showType: true } ); // '<empty:img></empty:img>'
    getData( ui, null, { showType: true } ); // '<ui:span></ui:span>'

    If options.showPriority is set to true, a priority will be displayed for all attribute elements.

    const attribute = new AttributeElement( 'b' );
    attribute._priority = 20;
    getData( attribute, null, { showPriority: true } ); // <b view-priority="20"></b>

    If options.showAttributeElementId is set to true, the attribute element's id will be displayed for all attribute elements that have it set.

    const attribute = new AttributeElement( 'span' );
    attribute._id = 'marker:foo';
    getData( attribute, null, { showAttributeElementId: true } ); // <span view-id="marker:foo"></span>

    Parameters

    node : Text | Element | DocumentFragment

    The node to stringify.

    [ selectionOrPositionOrRange ] : DocumentSelection | Position | Range

    A selection instance whose ranges will be included in the returned string data. If a range instance is provided, it will be converted to a selection containing this range. If a position instance is provided, it will be converted to a selection containing one range collapsed at this position.

    [ options ] : Object

    An object with additional options.

    Properties
    [ options.showType ] : Boolean

    When set to true, the type of elements will be printed (<container:p> instead of <p>, <attribute:b> instead of <b> and <empty:img> instead of <img>).

    Defaults to false

    [ options.showPriority ] : Boolean

    When set to true, the attribute element's priority will be printed (<span view-priority="12">, <b view-priority="10">).

    Defaults to false

    [ options.showAttributeElementId ] : Boolean

    When set to true, attribute element's id will be printed (<span id="marker:foo">).

    Defaults to false

    [ options.ignoreRoot ] : Boolean

    When set to true, the root's element opening and closing will not be printed. Mainly used by the getData function to ignore the document's root element.

    Defaults to false

    [ options.sameSelectionCharacters ] : Boolean

    When set to true, the selection inside the text will be marked as { and } and the selection outside the text as [ and ]. When set to false, both will be marked as [ and ] only.

    Defaults to false

    Returns

    String

    An HTML-like string representing the view.