ViewUpcastWriter

The view document instance in which this upcast writer operates.

Parameters

document : ViewDocument

The view document instance in which this upcast writer operates.

Adds specified class to the element.

writer.addClass( 'foo', linkElement );
writer.addClass( [ 'foo', 'bar' ], linkElement );

Parameters

className : string | Array<string>

Single class name or array of class names which will be added.

element : ViewElement

Element for which class will be added.

Returns

void

Related:

• ViewElement#_addClass

Appends a child node or a list of child nodes at the end of this node and sets the parent of these nodes to this element.

Parameters

items : string | ViewItem | Iterable<( string | ViewItem )>

Items to be inserted.

element : ViewElement | ViewDocumentFragment

Element to which items will be appended.

Returns

number

Number of appended nodes.

Related:

• ViewElement#_appendChild

Clones the provided element.

Parameters

element : ViewElement

Element to be cloned.

deep : boolean

If set to true clones element and all its children recursively. When set to false, element will be cloned without any children.

Defaults to false

Returns

ViewElement

Clone of this element.

Related:

• ViewElement#_clone

Creates a new ViewDocumentFragment instance.

Parameters

[ children ] : ViewNode | Iterable<ViewNode>

A list of nodes to be inserted into the created document fragment.

Returns

ViewDocumentFragment

The created document fragment.

Creates a new ViewElement instance.

Attributes can be passed in various formats:

upcastWriter.createElement( 'div', { class: 'editor', contentEditable: 'true' } ); // object
upcastWriter.createElement( 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
upcastWriter.createElement( 'div', mapOfAttributes ); // map

Parameters

name : string

Node name.

[ attrs ] : ViewElementAttributes

Collection of attributes.

[ children ] : ViewNode | Iterable<ViewNode>

A list of nodes to be inserted into created element.

Returns

ViewElement

Created element.

Creates a new position after given view item.

Parameters

item : ViewItem

View item after which the position should be located.

Returns

ViewPosition

Creates position at the given location. The location can be specified as:

• a position,
• parent element and offset (offset defaults to 0),
• parent element and 'end' (sets position at the end of that element),
• view item and 'before' or 'after' (sets position before or after given view item).

This method is a shortcut to other constructors such as:

• createPositionBefore,
• createPositionAfter,

Parameters

itemOrPosition : ViewPosition | ViewItem

[ offset ] : ViewPositionOffset

Offset or one of the flags. Used only when first parameter is a view item.

Returns

ViewPosition

Creates a new position before given view item.

Parameters

item : ViewItem

View item before which the position should be located.

Returns

ViewPosition

Creates a range spanning from start position to end position.

Note: This factory method creates it's own ViewPosition instances basing on passed values.

Parameters

start : ViewPosition

Start position.

end : ViewPosition

End position. If not set, range will be collapsed at start position.

Returns

ViewRange

Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.

Parameters

element : ViewElement | ViewDocumentFragment

Element which is a parent for the range.

Returns

ViewRange

Creates a range that starts before given view item and ends after it.

Parameters

item : ViewItem

Returns

ViewRange

Creates a new ViewSelection instance.

// Creates empty selection without ranges.
const selection = writer.createSelection();

// Creates selection at the given range.
const range = writer.createRange( start, end );
const selection = writer.createSelection( range );

// Creates selection at the given ranges
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
const selection = writer.createSelection( ranges );

// Creates selection from the other selection.
const otherSelection = writer.createSelection();
const selection = writer.createSelection( otherSelection );

// Creates selection from the document selection.
const selection = writer.createSelection( editor.editing.view.document.selection );

// Creates selection at the given position.
const position = writer.createPositionFromPath( root, path );
const selection = writer.createSelection( position );

Selection's constructor allow passing additional options (backward, fake and label) as the last argument.

// Creates backward selection.
const selection = writer.createSelection( range, { backward: true } );

Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

// Creates fake selection with label.
const selection = writer.createSelection( range, { fake: true, label: 'foo' } );

See also: createSelection( node, placeOrOffset, options ).

Parameters

[ selectable ] : null | ViewPosition | ViewRange | ViewSelection | ViewDocumentSelection | Iterable<ViewRange>

[ options ] : ViewSelectionOptions

Returns

ViewSelection

Creates a new ViewSelection instance.

// Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'paragraph' );
const selection = writer.createSelection( paragraph, offset );

// Creates a range inside an element which starts before the
// first child of that element and ends after the last child of that element.
const selection = writer.createSelection( paragraph, 'in' );

// Creates a range on an item which starts before the item and ends
// just after the item.
const selection = writer.createSelection( paragraph, 'on' );

Selection's constructor allow passing additional options (backward, fake and label) as the last argument.

// Creates backward selection.
const selection = writer.createSelection( element, 'in', { backward: true } );

Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

// Creates fake selection with label.
const selection = writer.createSelection( element, 'in', { fake: true, label: 'foo' } );

See also: createSelection( selectable, options ).

Parameters

selectable : ViewNode

placeOrOffset : ViewPlaceOrOffset

[ options ] : ViewSelectionOptions

Returns

ViewSelection

Creates a new ViewText instance.

Parameters

data : string

The text's data.

Returns

ViewText

The created text node.

Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to this element.

Parameters

index : number

Offset at which nodes should be inserted.

items : ViewItem | Iterable<ViewItem>

Items to be inserted.

element : ViewElement | ViewDocumentFragment

Element to which items will be inserted.

Returns

number

Number of inserted nodes.

Related:

• ViewElement#_insertChild

Removes given element from the view structure. Will not have effect on detached elements.

Parameters

element : ViewNode

Element which will be removed.

Returns

Array<ViewNode>

The array containing removed nodes.

Removes attribute from the element.

writer.removeAttribute( 'href', linkElement );

Parameters

key : string

Attribute key.

element : ViewElement

Element from which attribute will be removed.

Returns

void

Related:

• ViewElement#_removeAttribute

Removes the given number of child nodes starting at the given index and set the parent of these nodes to null.

Parameters

index : number

Offset from which nodes will be removed.

howMany : number

Number of nodes to remove.

element : ViewElement | ViewDocumentFragment

Element which children will be removed.

Returns

Array<ViewNode>

The array containing removed nodes.

Related:

• ViewElement#_removeChildren

Removes specified class from the element.

writer.removeClass( 'foo', linkElement );
writer.removeClass( [ 'foo', 'bar' ], linkElement );

Parameters

className : string | Array<string>

Single class name or array of class names which will be removed.

element : ViewElement

Element from which class will be removed.

Returns

void

Related:

• ViewElement#_removeClass

Removes a custom property stored under the given key.

Parameters

key : string | symbol

Name/key of the custom property to be removed.

element : ViewElement | ViewDocumentFragment

Element from which the custom property will be removed.

Returns

boolean

Returns true if property was removed.

Related:

• ViewElement#_removeCustomProperty

Removes specified style from the element.

writer.removeStyle( 'color', element );  // Removes 'color' style.
writer.removeStyle( [ 'color', 'border-top' ], element ); // Removes both 'color' and 'border-top' styles.

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#remove() for details.

Parameters

property : string | Array<string>

Style property name or names to be removed.

element : ViewElement

Element from which style will be removed.

Returns

void

Related:

• ViewElement#_removeStyle

Renames element by creating a copy of a given element but with its name changed and then moving contents of the old element to the new one.

Since this function creates a new element and removes the given one, the new element is returned to keep reference.

Parameters

newName : string

New element name.

element : ViewElement

Element to be renamed.

Returns

null | ViewElement

New element or null if the old element was not replaced (happens for detached elements).

Replaces given element with the new one in the view structure. Will not have effect on detached elements.

Parameters

oldElement : ViewElement

Element which will be replaced.

newElement : ViewElement

Element which will be inserted in the place of the old element.

Returns

boolean

Whether old element was successfully replaced.

Adds or overwrites element's attribute with a specified key and value.

writer.setAttribute( 'href', 'http://ckeditor.com', linkElement );

Parameters

key : string

Attribute key.

value : unknown

Attribute value.

element : ViewElement

Element for which attribute will be set.

Returns

void

Related:

• ViewElement#_setAttribute

Sets a custom property on element. Unlike attributes, custom properties are not rendered to the DOM, so they can be used to add special data to elements.

Parameters

key : string | symbol

Custom property name/key.

value : unknown

Custom property value to be stored.

element : ViewElement | ViewDocumentFragment

Element for which custom property will be set.

Returns

void

Related:

• ViewElement#_setCustomProperty

Adds style to the element.

writer.setStyle( {
	color: 'red',
	position: 'fixed'
}, element );

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

Parameters

properties : Record<string, string>

Object with key - value pairs.

element : ViewElement

Element for which style will be added.

Returns

void

Related:

• ViewElement#_setStyle

Adds style to the element.

writer.setStyle( 'color', 'red', element );

Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

Parameters

property : string

Property name.

value : string

Value to set.

element : ViewElement

Element for which style will be added.

Returns

void

Related:

• ViewElement#_setStyle

Removes given element from view structure and places its children in its position. It does nothing if element has no parent.

Parameters

element : ViewElement

Element to unwrap.

Returns

void