# engine/dev-utils/view

module

<a id="constants">

## Constants

<a id="constant-_getViewData">

### `_getViewData: GetViewData`

Writes the content of the [document](module_engine_view_document-ViewDocument.md) to an HTML-like string.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/dev-utils/view.ts#L98)

<a id="constant-_setViewData">

### `_setViewData: SetViewData`

Sets the content of a view [document](module_engine_view_document-ViewDocument.md) provided as an HTML-like string.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/dev-utils/view.ts#L139)

<a id="functions">

## Functions

<a id="function-_parseView">

### `_parseView( data, options = { options.inlineObjectElements?, options.lastRangeBackward?, options.order?, options.rootElement?, options.sameSelectionCharacters? } ) → ViewNode | ViewDocumentFragment | object`

Parses an HTML-like string and returns a view tree. A simple string will be converted to a [text](module_engine_view_text-ViewText.md) node:

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

[Elements](module_engine_view_element-ViewElement.md) will be \_parseViewd with attributes as children:

```typescript
_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](module_engine_view_documentfragment-ViewDocumentFragment.md):

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

The method can \_parseView multiple [ranges](module_engine_view_range-ViewRange.md) provided in string data and return a [selection](module_engine_view_documentselection-ViewDocumentSelection.md) instance containing these ranges. Ranges placed inside [text](module_engine_view_text-ViewText.md) nodes should be marked using `{` and `}` brackets:

```typescript
const { text, selection } = _parseView( 'f{ooba}r' );
```

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

```typescript
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:

```typescript
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](module_engine_view_documentselection-ViewDocumentSelection.md#member-anchor) is represented by the `end` position and [selection focus](module_engine_view_documentselection-ViewDocumentSelection.md#member-focus) is represented by the `start` position), use the `lastRangeBackward` flag:

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

Some more examples and edge cases:

```typescript
// 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>]' );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/dev-utils/view.ts#L434)

#### 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](module_engine_view_documentselection-ViewDocumentSelection.md) instance.

  * `options.order?: Array<number>`

    An array with the order of parsed ranges added to the returned [Selection](module_engine_view_documentselection-ViewDocumentSelection.md) 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](module_engine_view_element-ViewElement.md) or [DocumentFragment](module_engine_view_documentfragment-ViewDocumentFragment.md), 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.

<a id="function-_stringifyView">

### `_stringifyView( node, selectionOrPositionOrRange, options = { options.domConverter?, options.ignoreRoot?, options.renderRawElements?, options.renderUIElements?, options.sameSelectionCharacters?, options.showAttributeElementId?, options.showPriority?, options.showType?, options.skipListItemIds? } ) → string`

Converts view elements to HTML-like string representation.

A root element can be provided as [text](module_engine_view_text-ViewText.md):

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

or as an [element](module_engine_view_element-ViewElement.md):

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

or as a [document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md):

```typescript
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](module_engine_view_documentselection-ViewDocumentSelection.md) 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 `]`:

```typescript
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 `}`:

```typescript
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:

```typescript
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](module_engine_view_range-ViewRange.md) or [position](module_engine_view_position-ViewPosition.md) instance can be provided instead of the [selection](module_engine_view_documentselection-ViewDocumentSelection.md) 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.

```typescript
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](module_engine_view_attributeelement-ViewAttributeElement.md), [container elements](module_engine_view_containerelement-ViewContainerElement.md) [empty elements](module_engine_view_emptyelement-ViewEmptyElement.md) and [UI elements](module_engine_view_uielement-ViewUIElement.md):

```typescript
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](module_engine_view_attributeelement-ViewAttributeElement.md).

```typescript
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](module_engine_view_attributeelement-ViewAttributeElement.md) that have it set.

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/dev-utils/view.ts#L315)

#### 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](module_engine_view_domconverter-ViewDomConverter.md) 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](module_engine_view_document-ViewDocument.md) root element.

  * `options.renderRawElements?: boolean`

    When set to `true`, the inner content of each [`ViewRawElement`](module_engine_view_rawelement-ViewRawElement.md) will be printed.

  * `options.renderUIElements?: boolean`

    When set to `true`, the inner content of each [`ViewUIElement`](module_engine_view_uielement-ViewUIElement.md) 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.

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)