ModelWriter

The batch to which this writer will add changes.

Instance of the model on which this writer operates.

Creates a writer instance.

Note: It is not recommended to use it directly. Use Model#change() or Model#enqueueChange() instead.

Parameters

model : Model

batch : Batch

Adds a marker. Marker is a named range, which tracks changes in the document and updates its range automatically, when model tree changes.

As the first parameter you can set marker name.

The required options.usingOperation parameter lets you decide if the marker should be managed by operations or not. See marker class description to learn about the difference between markers managed by operations and not-managed by operations.

The options.affectsData parameter, which defaults to false, allows you to define if a marker affects the data. It should be true when the marker change changes the data returned by the editor.getData() method. When set to true it fires the change:data event. When set to false it fires the change event.

Create marker directly base on marker's name:

addMarker( markerName, { range, usingOperation: false } );

Create marker using operation:

addMarker( markerName, { range, usingOperation: true } );

Create marker that affects the editor data:

addMarker( markerName, { range, usingOperation: false, affectsData: true } );

Note: For efficiency reasons, it's best to create and keep as little markers as possible.

Parameters

name : string

Name of a marker to create - must be unique.

options : object

Properties

[ options.affectsData ] : boolean

Flag indicating that the marker changes the editor data.

options.range : ModelRange

Marker range.

options.usingOperation : boolean

Flag indicating that the marker should be added by MarkerOperation. See managedUsingOperations.

Returns

Marker

Marker that was set.

Related:

• Marker

Adds a new root to the document (or re-attaches a detached root).

Throws an error, if trying to add a root that is already added and attached.

Parameters

rootName : string

Name of the added root.

elementName : string

The element name. Defaults to '$root' which also has some basic schema defined (e.g. $block elements are allowed inside the $root). Make sure to define a proper schema if you use a different name.

Defaults to '$root'

Returns

ModelRootElement

The added root element.

Inserts item at the end of the given parent.

const paragraph = writer.createElement( 'paragraph' );
writer.append( paragraph, root );

Note that if the item already has parent it will be removed from the previous parent.

If you want to move range instead of an item use Writer#move().

Parameters

item : ModelDocumentFragment | ModelItem

Item or document fragment to insert.

parent : ModelElement | ModelDocumentFragment

Returns

void

Creates element with specified attributes and inserts it at the end of the parent.

writer.appendElement( 'paragraph', { alignment: 'center' }, root );

Parameters

name : string

Name of the element.

attributes : ModelNodeAttributes

Elements attributes.

parent : ModelElement | ModelDocumentFragment

Returns

void

Creates element and inserts it at the end of the parent.

writer.appendElement( 'paragraph', root );

Parameters

name : string

Name of the element.

parent : ModelElement | ModelDocumentFragment

Returns

void

Creates text node with specified attributes and inserts it at the end of the parent.

writer.appendText( 'foo', { bold: true }, paragraph );

Parameters

text : string

Text data.

attributes : ModelNodeAttributes

Text attributes.

parent : ModelElement | ModelDocumentFragment

Returns

void

Creates text node and inserts it at the end of the parent.

writer.appendText( 'foo', paragraph );

Parameters

text : string

Text data.

parent : ModelElement | ModelDocumentFragment

Returns

void

Removes all attributes from all elements in the range or from the given item.

Parameters

itemOrRange : ModelRange | ModelItem

Model item or range from which all attributes will be removed.

Returns

void

Creates a copy of the element and returns it. Created element has the same name and attributes as the original element. If clone is deep, the original element's children are also cloned. If not, then empty element is returned.

Parameters

element : ModelElement

The element to clone.

deep : boolean

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

Defaults to true

Returns

ModelElement

Creates a new document fragment.

Returns

ModelDocumentFragment

Created document fragment.

Creates a new element.

writer.createElement( 'paragraph' );
writer.createElement( 'paragraph', { alignment: 'center' } );

Parameters

name : string

Name of the element.

[ attributes ] : ModelNodeAttributes

Elements attributes.

Returns

ModelElement

Created element.

Shortcut for Model#createPositionAfter().

Parameters

item : ModelItem

Item after which the position should be placed.

Returns

ModelPosition

Shortcut for Model#createPositionAt().

Parameters

itemOrPosition : ModelDocumentFragment | ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

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

Returns

ModelPosition

Shortcut for Model#createPositionBefore().

Parameters

item : ModelItem

Item after which the position should be placed.

Returns

ModelPosition

Shortcut for Model#createPositionFromPath().

Parameters

root : ModelElement | ModelDocumentFragment

Root of the position.

path : readonly Array<number>

Position path. See path.

[ stickiness ] : ModelPositionStickiness

Position stickiness. See ModelPositionStickiness.

Returns

ModelPosition

Shortcut for Model#createRange().

Parameters

start : ModelPosition

Start position.

[ end ] : ModelPosition

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

Returns

ModelRange

Shortcut for Model#createRangeIn().

Parameters

element : ModelElement | ModelDocumentFragment

Element which is a parent for the range.

Returns

ModelRange

Shortcut for Model#createRangeOn().

Parameters

element : ModelItem

Element which is a parent for the range.

Returns

ModelRange

Shortcut for Model#createSelection().

Parameters

[ selectable ] : null | ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange>

[ options ] : object

Properties

[ options.backward ] : boolean

Returns

ModelSelection

Shortcut for Model#createSelection().

Parameters

selectable : ModelNode

placeOrOffset : ModelPlaceOrOffset

[ options ] : object

Properties

[ options.backward ] : boolean

Returns

ModelSelection

Creates a new text node.

writer.createText( 'foo' );
writer.createText( 'foo', { bold: true } );

Parameters

data : string

Text data.

[ attributes ] : ModelNodeAttributes

Text attributes.

Returns

ModelText

Created text node.

Detaches the root from the document.

All content and markers are removed from the root upon detaching. New content and new markers cannot be added to the root, as long as it is detached.

A root cannot be fully removed from the document, it can be only detached. A root is permanently removed only after you re-initialize the editor and do not specify the root in the initial data.

A detached root can be re-attached using addRoot.

Throws an error if the root does not exist or the root is already detached.

Parameters

rootOrName : string | ModelRootElement

Name of the detached root.

Returns

void

Inserts item on given position.

const paragraph = writer.createElement( 'paragraph' );
writer.insert( paragraph, position );

Instead of using position you can use parent and offset:

const text = writer.createText( 'foo' );
writer.insert( text, paragraph, 5 );

You can also use end instead of the offset to insert at the end:

const text = writer.createText( 'foo' );
writer.insert( text, paragraph, 'end' );

Or insert before or after another element:

const paragraph = writer.createElement( 'paragraph' );
writer.insert( paragraph, anotherParagraph, 'after' );

These parameters works the same way as writer.createPositionAt().

Note that if the item already has parent it will be removed from the previous parent.

Note that you cannot re-insert a node from a document to a different document or a document fragment. In this case, model-writer-insert-forbidden-move is thrown.

If you want to move range instead of an item use Writer#move().

Note: For a paste-like content insertion mechanism see model.insertContent().

Parameters

item : ModelDocumentFragment | ModelItem

Item or document fragment to insert.

itemOrPosition : ModelDocumentFragment | ModelPosition | ModelItem

offset : ModelPositionOffset

Offset or one of the flags. Used only when second parameter is a model item.

Defaults to 0

Returns

void

Creates and inserts element with specified attributes on given position.

writer.insertElement( 'paragraph', { alignment: 'center' }, position );

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

// Inserts paragraph in the root at offset 5:
writer.insertElement( 'paragraph', { alignment: 'center' }, root, 5 );
// Inserts paragraph at the end of a blockquote:
writer.insertElement( 'paragraph', { alignment: 'center' }, blockquote, 'end' );
// Inserts after an image:
writer.insertElement( 'paragraph', { alignment: 'center' }, image, 'after' );

These parameters works the same way as writer.createPositionAt().

Parameters

name : string

Name of the element.

attributes : ModelNodeAttributes

Elements attributes.

itemOrPosition : ModelDocumentFragment | ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

Offset or one of the flags. Used only when third parameter is a model item.

Returns

void

Creates and inserts element on given position. You can optionally set attributes:

writer.insertElement( 'paragraph', position );

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

// Inserts paragraph in the root at offset 5:
writer.insertElement( 'paragraph', root, 5 );
// Inserts paragraph at the end of a blockquote:
writer.insertElement( 'paragraph', blockquote, 'end' );
// Inserts after an image:
writer.insertElement( 'paragraph', image, 'after' );

These parameters works the same way as writer.createPositionAt().

Parameters

name : string

Name of the element.

itemOrPosition : ModelDocumentFragment | ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

Offset or one of the flags. Used only when second parameter is a model item.

Returns

void

Creates and inserts text with specified attributes on given position.

writer.insertText( 'foo', { bold: true }, position );

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

// Inserts 'foo' in paragraph, at offset 5:
writer.insertText( 'foo', { bold: true }, paragraph, 5 );
// Inserts 'foo' at the end of a paragraph:
writer.insertText( 'foo', { bold: true }, paragraph, 'end' );
// Inserts 'foo' after an image:
writer.insertText( 'foo', { bold: true }, image, 'after' );

These parameters work in the same way as writer.createPositionAt().

Parameters

text : string

Text data.

[ attributes ] : ModelNodeAttributes

Text attributes.

[ itemOrPosition ] : ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

Offset or one of the flags. Used only when third parameter is a model item.

Returns

void

Creates and inserts text on given position.

writer.insertText( 'foo', position );

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

// Inserts 'foo' in paragraph, at offset 5:
writer.insertText( 'foo', paragraph, 5 );
// Inserts 'foo' at the end of a paragraph:
writer.insertText( 'foo', paragraph, 'end' );
// Inserts 'foo' after an image:
writer.insertText( 'foo', image, 'after' );

These parameters work in the same way as writer.createPositionAt().

Parameters

text : string

Text data.

[ itemOrPosition ] : ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

Offset or one of the flags. Used only when second parameter is a model item.

Returns

void

Merges two siblings at the given position.

Node before and after the position have to be an element. Otherwise writer-merge-no-element-before or writer-merge-no-element-after error will be thrown.

Parameters

position : ModelPosition

Position between merged elements.

Returns

void

Moves all items in the source range to the target position.

writer.move( sourceRange, targetPosition );

Instead of the target position you can use parent and offset or define that range should be moved to the end or before or after chosen item:

// Moves all items in the range to the paragraph at offset 5:
writer.move( sourceRange, paragraph, 5 );
// Moves all items in the range to the end of a blockquote:
writer.move( sourceRange, blockquote, 'end' );
// Moves all items in the range to a position after an image:
writer.move( sourceRange, image, 'after' );

These parameters work the same way as writer.createPositionAt().

Note that items can be moved only within the same tree. It means that you can move items within the same root (element or document fragment) or between documents roots, but you cannot move items from document fragment to the document or from one detached element to another. Use insert in such cases.

Parameters

range : ModelRange

Source range.

itemOrPosition : ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

Offset or one of the flags. Used only when second parameter is a model item.

Returns

void

Temporarily changes the gravity of the selection from left to right.

The gravity defines from which direction the selection inherits its attributes. If it's the default left gravity, then the selection (after being moved by the user) inherits attributes from its left-hand side. This method allows to temporarily override this behavior by forcing the gravity to the right.

For the following model fragment:

<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>

• Default gravity: selection will have the bold and linkHref attributes.
• Overridden gravity: selection will have bold attribute.

Note: It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry of the process.

Returns

string

The unique id which allows restoring the gravity.

Removes given model item or range.

Parameters

itemOrRange : ModelRange | ModelItem

Model item or range to remove.

Returns

void

Removes an attribute with given key from a model item or from a range.

Parameters

key : string

Attribute key.

itemOrRange : ModelRange | ModelItem

Model item or range from which the attribute will be removed.

Returns

void

Removes given marker or marker with given name. The marker is removed accordingly to how it has been created, so if the marker was created using operation, it will be destroyed using operation.

Parameters

markerOrName : string | Marker

Marker or marker name to remove.

Returns

void

Removes attribute(s) with given key(s) from the selection.

Remove one attribute:

writer.removeSelectionAttribute( 'italic' );

Remove multiple attributes:

writer.removeSelectionAttribute( [ 'italic', 'bold' ] );

Parameters

keyOrIterableOfKeys : string | Iterable<string>

Key of the attribute to remove or an iterable of attribute keys to remove.

Returns

void

Renames the given element.

Parameters

element : ModelElement | ModelDocumentFragment

The element to rename.

newName : string

New element name.

Returns

void

Restores overrideSelectionGravity gravity to default.

Restoring the gravity is only possible using the unique identifier returned by overrideSelectionGravity. Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden.

Parameters

uid : string

The unique id returned by overrideSelectionGravity.

Returns

void

Sets value of the attribute with given key on a model item or on a range.

Parameters

key : string

Attribute key.

value : unknown

Attribute new value.

itemOrRange : ModelRange | ModelItem

Model item or range on which the attribute will be set.

Returns

void

Sets values of attributes on a model item or on a range.

writer.setAttributes( {
	bold: true,
	italic: true
}, range );

Parameters

attributes : ModelNodeAttributes

Attributes keys and values.

itemOrRange : ModelRange | ModelItem

Model item or range on which the attributes will be set.

Returns

void

Sets the document's selection (ranges and direction) to the specified location based on the given selectable or creates an empty selection if no arguments were passed.

// Sets selection to the given range.
const range = writer.createRange( start, end );
writer.setSelection( range );

// Sets selection to given ranges.
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
writer.setSelection( ranges );

// Sets selection to other selection.
const otherSelection = writer.createSelection();
writer.setSelection( otherSelection );

// Sets selection to the given document selection.
const documentSelection = model.document.selection;
writer.setSelection( documentSelection );

// Sets collapsed selection at the given position.
const position = writer.createPosition( root, path );
writer.setSelection( position );

// Removes all selection's ranges.
writer.setSelection( null );

Writer#setSelection() allow passing additional options (backward) as the last argument.

// Sets selection as backward.
writer.setSelection( range, { backward: true } );

Throws writer-incorrect-use error when the writer is used outside the change() block.

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

Parameters

selectable : null | ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange>

[ options ] : object

Properties

[ options.backward ] : boolean

Returns

void

Sets the document's selection (ranges and direction) to the specified location based on the given selectable or creates an empty selection if no arguments were passed.

// Sets collapsed selection at the position of the given node and an offset.
writer.setSelection( 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.

writer.setSelection( paragraph, 'in' );

Creates a range on an item which starts before the item and ends just after the item.

writer.setSelection( paragraph, 'on' );

Writer#setSelection() allow passing additional options (backward) as the last argument.

// Sets selection as backward.
writer.setSelection( element, 'in', { backward: true } );

Throws writer-incorrect-use error when the writer is used outside the change() block.

See also: setSelection( selectable, options ).

Parameters

selectable : ModelNode

placeOrOffset : ModelPlaceOrOffset

[ options ] : object

Properties

[ options.backward ] : boolean

Returns

void

Sets attributes on the selection. If any attribute with the same key already is set, it's value is overwritten.

Using key-value object:

writer.setSelectionAttribute( { italic: true, bold: false } );

Using iterable object:

writer.setSelectionAttribute( new Map( [ [ 'italic', true ] ] ) );

Parameters

objectOrIterable : ModelNodeAttributes

Object / iterable of key => value attribute pairs.

Returns

void

Sets attribute on the selection. If attribute with the same key already is set, it's value is overwritten.

writer.setSelectionAttribute( 'italic', true );

Parameters

key : string

Key of the attribute to set.

value : unknown

Attribute value.

Returns

void

Moves focus to the specified location.

The location can be specified in the same form as writer.createPositionAt() parameters.

Parameters

itemOrPosition : ModelPosition | ModelItem

[ offset ] : ModelPositionOffset

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

Returns

void

Splits elements starting from the given position and going to the top of the model tree as long as given limitElement is reached. When limitElement is not defined then only the parent of the given position will be split.

The element needs to have a parent. It cannot be a root element nor a document fragment. The writer-split-element-no-parent error will be thrown if you try to split an element with no parent.

Parameters

position : ModelPosition

Position of split.

[ limitElement ] : ModelNode | ModelDocumentFragment

Stop splitting when this element will be reached.

Returns

object

Split result with properties:

• position - Position between split elements.
• range - Range that stars from the end of the first split element and ends at the beginning of the first copy element.

Unwraps children of the given element – all its children are moved before it and then the element is removed. Throws error if you try to unwrap an element which does not have a parent.

Parameters

element : ModelElement

Element to unwrap.

Returns

void

Adds, updates or refreshes a marker. Marker is a named range, which tracks changes in the document and updates its range automatically, when model tree changes. Still, it is possible to change the marker's range directly using this method.

As the first parameter you can set marker name or instance. If none of them is provided, new marker, with a unique name is created and returned.

Note: If you want to change the view element of the marker while its data in the model remains the same, use the dedicated reconvertMarker method.

The options.usingOperation parameter lets you change if the marker should be managed by operations or not. See marker class description to learn about the difference between markers managed by operations and not-managed by operations. It is possible to change this option for an existing marker.

The options.affectsData parameter, which defaults to false, allows you to define if a marker affects the data. It should be true when the marker change changes the data returned by the editor.getData() method. When set to true it fires the change:data event. When set to false it fires the change event.

Update marker directly base on marker's name:

updateMarker( markerName, { range } );

Update marker using operation:

updateMarker( marker, { range, usingOperation: true } );
updateMarker( markerName, { range, usingOperation: true } );

Change marker's option (start using operations to manage it):

updateMarker( marker, { usingOperation: true } );

Change marker's option (inform the engine, that the marker does not affect the data anymore):

updateMarker( markerName, { affectsData: false } );

Parameters

markerOrName : string | Marker

Name of a marker to update, or a marker instance.

[ options ] : object

If options object is not defined then marker will be refreshed by triggering downcast conversion for this marker with the same data.

Properties

[ options.affectsData ] : boolean

Flag indicating that the marker changes the editor data.

[ options.range ] : ModelRange

Marker range to update.

[ options.usingOperation ] : boolean

Flag indicated whether the marker should be added by MarkerOperation. See managedUsingOperations.

Returns

void

Related:

• Marker

Wraps the given range with the given element or with a new element (if a string was passed).

Note: range to wrap should be a "flat range" (see Range#isFlat). If not, an error will be thrown.

Parameters

range : ModelRange

Range to wrap.

elementOrString : string | ModelElement

Element or name of element to wrap the range with.

Returns

void

For given action type and positionOrRange where the action happens, this function finds all affected markers and applies a marker operation with the new marker range equal to the current range. Thanks to this, the marker range can be later correctly processed during undo.

Parameters

type : 'merge' | 'move'

Writer action type.

positionOrRange : ModelPosition | ModelRange

Position or range where the writer action happens.

Returns

void

Throws writer-detached-writer-tries-to-modify-model error when the writer is used outside of the change() block.

Returns

void

Performs merge action in a non-detached tree.

Parameters

position : ModelPosition

Position between merged elements.

Returns

void

Performs merge action in a detached tree.

Parameters

position : ModelPosition

Position between merged elements.

Returns

void

Parameters

key : string

Key of the attribute to remove.

Returns

void

Parameters

key : string

Key of the attribute to remove.

value : unknown

Attribute value.

Returns

void