CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
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.

    See source

  • ViewStringify

    private

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

    See source

Functions

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

    static

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

    See source

    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

    [ options.renderUIElements ] : Boolean

    When set to true, the inner content of each UIElement will be printed.

    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 a view tree. A simple string will be converted to a text node:

    See source
    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 a view document provided as an HTML-like string.

    See source

    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], [options.renderUIElements] } ) → String

    static

    Converts view elements to HTML-like string representation.

    See source

    A root element can be provided as text:

    const text = downcastWriter.createText( 'foobar' );
stringify( text ); // 'foobar'

    or as an element:

    const element = downcastWriter.createElement( 'p', null, downcastWriter.createText( 'foobar' ) );
stringify( element ); // '<p>foobar</p>'

    or as a document fragment:

    const text = downcastWriter.createText( 'foobar' );
const b = downcastWriter.createElement( 'b', { name: 'test' }, text );
const p = downcastWriter.createElement( 'p', { style: 'color:red;' } );
const fragment = downcastWriter.createDocumentFragment( [ 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 the output data. If a range position is placed inside the element node, it will be represented with [ and ]:

    const text = downcastWriter.createText( 'foobar' );
const b = downcastWriter.createElement( 'b', null, text );
const p = downcastWriter.createElement( 'p', null, b );
const selection = downcastWriter.createSelection(
    downcastWriter.createRangeIn( p )
);

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 = downcastWriter.createText( 'foobar' );
const b = downcastWriter.createElement( 'b', null, text );
const p = downcastWriter.createElement( 'p', null, b );
const selection = downcastWriter.createSelection(
    downcastWriter.createRange( downcastWriter.createPositionAt( text, 1 ), downcastWriter.createPositionAt( 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 = downcastWriter.createText( 'foobar' );
const selection = downcastWriter.createSelection( [
    downcastWriter.createRange( downcastWriter.createPositionAt( text, 0 ), downcastWriter.createPositionAt( text, 1 ) ),
    downcastWriter.createRange( downcastWriter.createPositionAt( text, 3 ), downcastWriter.createPositionAt( 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 = downcastWriter.createText( 'foobar' );
const range = downcastWriter.createRange( downcastWriter.createPositionAt( text, 0 ), downcastWriter.createPositionAt( text, 1 ) );
const position = downcastWriter.createPositionAt( 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 = downcastWriter.createAttributeElement( 'b' );
const container = downcastWriter.createContainerElement( 'p' );
const empty = downcastWriter.createEmptyElement( 'img' );
const ui = downcastWriter.createUIElement( '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 = downcastWriter.createAttributeElement( '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 = downcastWriter.createAttributeElement( '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

    [ options.renderUIElements ] : Boolean

    When set to true, the inner content of each UIElement will be printed.

    Defaults to false

    Returns

    String

    An HTML-like string representing the view.