engine/dev-utils/view

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

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

Elements will be _parseViewd with attributes as children:

_parseView( '<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:

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

The method can _parseView 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 } = _parseView( 'f{ooba}r' );

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

const { root, selection } = _parseView( '<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 _parseView 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 } = _parseView( '{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 } = _parseView( `{foo}bar{baz}`, { lastRangeBackward: true } );

Some more examples and edge cases:

// Returns an empty document fragment.
_parseView( '' );

// Returns an empty document fragment and a collapsed selection.
const { root, selection } = _parseView( '[]' );

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

Parameters

data: string

An HTML-like string to be parsed.

options: object

Properties

options.inlineObjectElements?: Array<string>

options.lastRangeBackward?: boolean

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

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.rootElement?: ViewElement | ViewDocumentFragment

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 {}

Returns

ViewNode | ViewDocumentFragment | 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.

Converts view elements to HTML-like string representation.

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: ViewNode | ViewDocumentFragment

The node to stringify.

selectionOrPositionOrRange: ViewPosition | ViewRange | ViewDocumentSelection | null

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.

Defaults to null

options: object

An object with additional options.

Properties

options.domConverter?: ViewDomConverter

When set to an actual ViewDomConverter instance, it lets the conversion go through exactly the same flow the editing view is going through, i.e. with view data filtering. Otherwise the simple stub is used.

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.

options.renderRawElements?: boolean

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

options.renderUIElements?: boolean

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

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.

options.showAttributeElementId?: boolean

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

options.showPriority?: boolean

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

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>).

options.skipListItemIds?: boolean

Defaults to {}

Returns

string

An HTML-like string representing the view.