CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DowncastWriter (engine/view)

@ckeditor/ckeditor5-engine/src/view/downcastwriter

class
See source

View downcast writer.

It provides a set of methods used to manipulate view nodes.

Do not create an instance of this writer manually. To modify a view structure, use the View#change() block.

The DowncastWriter is designed to work with semantic views which are the views that were/are being downcasted from the model. To work with ordinary views (e.g. parsed from a pasted content) use the upcast writer.

Read more about changing the view in the Changing the view section of the Editing engine architecture guide.

Filtering

Properties

Methods

  • constructor( document )

    See source

    Parameters

    document : Document

    The view document instance.

  • addClass( className, element ) → void

    See source

    Adds specified class to the element.

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

    Parameters

    className : string | Array<string>
    element : Element

    Returns

    void

  • breakAttributes( positionOrRange ) → Position | Range

    See source

    Breaks attribute elements at the provided position or at the boundaries of a provided range. It breaks attribute elements up to their first ancestor that is a container element.

    In following examples <p> is a container, <b> and <u> are attribute elements:

    <p>foo<b><u>bar{}</u></b></p> -> <p>foo<b><u>bar</u></b>[]</p>
<p>foo<b><u>{}bar</u></b></p> -> <p>foo{}<b><u>bar</u></b></p>
<p>foo<b><u>b{}ar</u></b></p> -> <p>foo<b><u>b</u></b>[]<b><u>ar</u></b></p>
<p><b>fo{o</b><u>ba}r</u></p> -> <p><b>fo</b><b>o</b><u>ba</u><u>r</u></b></p>

    Note: DocumentFragment is treated like a container.

    Note: The difference between breakAttributes() and breakContainer() is that breakAttributes() breaks all attribute elements that are ancestors of a given position, up to the first encountered container element. breakContainer() assumes that a given position is directly in the container element and breaks that container element.

    Throws the view-writer-invalid-range-container CKEditorError when the start and end positions of a passed range are not placed inside same parent container.

    Throws the view-writer-cannot-break-empty-element CKEditorError when trying to break attributes inside an EmptyElement.

    Throws the view-writer-cannot-break-ui-element CKEditorError when trying to break attributes inside a UIElement.

    Parameters

    positionOrRange : Position | Range

    The position where to break attribute elements.

    Returns

    Position | Range

    The new position or range, after breaking the attribute elements.

    Related:

  • breakContainer( position ) → Position

    See source

    Breaks a container view element into two, at the given position. The position has to be directly inside the container element and cannot be in the root. It does not break the conrainer view element if the position is at the beginning or at the end of its parent element.

    <p>foo^bar</p> -> <p>foo</p><p>bar</p>
<div><p>foo</p>^<p>bar</p></div> -> <div><p>foo</p></div><div><p>bar</p></div>
<p>^foobar</p> -> ^<p>foobar</p>
<p>foobar^</p> -> <p>foobar</p>^

    Note: The difference between breakAttributes() and breakContainer() is that breakAttributes() breaks all attribute elements that are ancestors of a given position, up to the first encountered container element. breakContainer() assumes that the given position is directly in the container element and breaks that container element.

    Parameters

    position : Position

    The position where to break the element.

    Returns

    Position

    The position between broken elements. If an element has not been broken, the returned position is placed either before or after it.

    Related:

  • clear( range, element ) → void

    See source

    Removes matching elements from given range.

    Throws CKEditorError view-writer-invalid-range-container when start and end positions are not placed inside same parent container.

    Parameters

    range : Range

    Range to clear.

    element : Element

    Element to remove.

    Returns

    void

  • clearClonedElementsGroup( groupName ) → void

    See source

    Cleans up memory by removing obsolete cloned elements group from the writer.

    Should be used whenever all attribute elements with the same id are going to be removed from the view and the group will no longer be needed.

    Cloned elements group are not removed automatically in case if the group is still needed after all its elements were removed from the view.

    Keep in mind that group names are equal to the id property of the attribute element.

    Parameters

    groupName : string

    Name of the group to clear.

    Returns

    void

  • createAttributeElement( name, [ attributes ], options = { [options.id], [options.priority], [options.renderUnsafeAttributes] } ) → AttributeElement

    See source

    Creates a new AttributeElement.

    writer.createAttributeElement( 'strong' );
writer.createAttributeElement( 'a', { href: 'foo.bar' } );

// Make `<a>` element contain other attributes element so the `<a>` element is not broken.
writer.createAttributeElement( 'a', { href: 'foo.bar' }, { priority: 5 } );

// Set `id` of a marker element so it is not joined or merged with "normal" elements.
writer.createAttributeElement( 'span', { class: 'my-marker' }, { id: 'marker:my' } );

    Parameters

    name : string

    Name of the element.

    [ attributes ] : ElementAttributes

    Element's attributes.

    options : object

    Element's options.

    Properties
    [ options.id ] : string | number

    Element's id.

    [ options.priority ] : number

    Element's priority.

    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Defaults to {}

    Returns

    AttributeElement

    Created element.

  • createContainerElement( name, attributes, children, [ options ] = { [options.renderUnsafeAttributes] } ) → ContainerElement

    See source

    Creates a new ContainerElement with children.

    // Create element with children.
writer.createContainerElement( 'figure', { class: 'image' }, [
	writer.createEmptyElement( 'img' ),
	writer.createContainerElement( 'figcaption' )
] );

// Create element with specific options.
writer.createContainerElement( 'figure', { class: 'image' }, [
	writer.createEmptyElement( 'img' ),
	writer.createContainerElement( 'figcaption' )
], { renderUnsafeAttributes: [ 'foo' ] } );

    Parameters

    name : string

    Name of the element.

    attributes : ElementAttributes

    Elements attributes.

    children : Node | Iterable<Node>

    A node or a list of nodes to be inserted into the created element. If no children were specified, element's options can be passed in this argument.

    [ options ] : object

    Element's options.

    Properties
    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Returns

    ContainerElement

    Created element.

  • createContainerElement( name, [ attributes ], [ options ] = { [options.renderUnsafeAttributes] } ) → ContainerElement

    See source

    Creates a new ContainerElement.

    writer.createContainerElement( 'p' );

// Create element with custom attributes.
writer.createContainerElement( 'div', { id: 'foo-bar', 'data-baz': '123' } );

// Create element with custom styles.
writer.createContainerElement( 'p', { style: 'font-weight: bold; padding-bottom: 10px' } );

// Create element with custom classes.
writer.createContainerElement( 'p', { class: 'foo bar baz' } );

// Create element with specific options.
writer.createContainerElement( 'span', { class: 'placeholder' }, { renderUnsafeAttributes: [ 'foo' ] } );

    Parameters

    name : string

    Name of the element.

    [ attributes ] : ElementAttributes

    Elements attributes.

    [ options ] : object

    Element's options.

    Properties
    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Returns

    ContainerElement

    Created element.

  • createDocumentFragment( [ children ] ) → DocumentFragment

    See source

    Creates a new DocumentFragment instance.

    Parameters

    [ children ] : Node | Iterable<Node>

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

    Returns

    DocumentFragment

    The created document fragment.

  • createEditableElement( name, [ attributes ], options = { [options.renderUnsafeAttributes] } ) → EditableElement

    See source

    Creates a new EditableElement.

    writer.createEditableElement( 'div' );
writer.createEditableElement( 'div', { id: 'foo-1234' } );

    Note: The editable element is to be used in the editing pipeline. Usually, together with toWidgetEditable().

    Parameters

    name : string

    Name of the element.

    [ attributes ] : ElementAttributes

    Elements attributes.

    options : object

    Element's options.

    Properties
    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Defaults to {}

    Returns

    EditableElement

    Created element.

  • createEmptyElement( name, [ attributes ], options = { [options.renderUnsafeAttributes] } ) → EmptyElement

    See source

    Creates a new EmptyElement.

    writer.createEmptyElement( 'img' );
writer.createEmptyElement( 'img', { id: 'foo-1234' } );

    Parameters

    name : string

    Name of the element.

    [ attributes ] : ElementAttributes

    Elements attributes.

    options : object

    Element's options.

    Properties
    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Defaults to {}

    Returns

    EmptyElement

    Created element.

  • createPositionAfter( item ) → Position

    See source

    Creates a new position after given view item.

    Parameters

    item : Item

    View item after which the position should be located.

    Returns

    Position

  • createPositionAt( itemOrPosition, [ offset ] ) → Position

    See source

    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:

    Parameters

    itemOrPosition : Position | Item
    [ offset ] : PositionOffset

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

    Returns

    Position

  • createPositionBefore( item ) → Position

    See source

    Creates a new position before given view item.

    Parameters

    item : Item

    View item before which the position should be located.

    Returns

    Position

  • createRange( start, [ end ] ) → Range

    See source

    Creates a range spanning from start position to end position.

    Note: This factory method creates its own Position instances basing on passed values.

    Parameters

    start : Position

    Start position.

    [ end ] : null | Position

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

    Returns

    Range

  • createRangeIn( element ) → Range

    See source

    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 : Element | DocumentFragment

    Element which is a parent for the range.

    Returns

    Range

  • createRangeOn( item ) → Range

    See source

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

    Parameters

    item : Item

    Returns

    Range

  • createRawElement( name, [ attributes ], [ renderFunction ], options = { [options.renderUnsafeAttributes] } ) → RawElement

    See source

    Creates a new RawElement.

    writer.createRawElement( 'span', { id: 'foo-1234' }, function( domElement ) {
	domElement.innerHTML = '<b>This is the raw content of the raw element.</b>';
} );

    Raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures in the editor content without, for instance, worrying about compatibility with other editor features. Raw elements are a perfect tool for integration with external frameworks and data sources.

    Unlike UI elements, raw elements act like "real" editor content (similar to ContainerElement or EmptyElement), and they are considered by the editor selection.

    You should not use raw elements to render the UI in the editor content. Check out #createUIElement() instead.

    Parameters

    name : string

    The name of the element.

    [ attributes ] : ElementAttributes

    Element attributes.

    [ renderFunction ] : ( domElement: HTMLElement, domConverter: DomConverter ) => void

    A custom render function.

    options : object

    Element's options.

    Properties
    [ options.renderUnsafeAttributes ] : Array<string>

    A list of attribute names that should be rendered in the editing pipeline even though they would normally be filtered out by unsafe attribute detection mechanisms.

    Defaults to {}

    Returns

    RawElement

    The created element.

  • createSelection( [ selectable ], [ option ] ) → Selection

    See source

    Creates new Selection 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 | Position | Range | Selection | DocumentSelection | Iterable<Range>
    [ option ] : SelectionOptions

    Returns

    Selection

  • createSelection( selectable, placeOrOffset, [ options ] ) → Selection

    See source

    Creates new Selection instance.

    // Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'p' );
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 : Node
    placeOrOffset : PlaceOrOffset
    [ options ] : SelectionOptions

    Returns

    Selection

  • createSlot( modeOrFilter ) → Element

    See source

    Creates placeholders for child elements of the elementToStructure() conversion helper.

    const viewSlot = conversionApi.writer.createSlot();
const viewPosition = conversionApi.writer.createPositionAt( viewElement, 0 );

conversionApi.writer.insert( viewPosition, viewSlot );

    It could be filtered down to a specific subset of children (only <foo> model elements in this case):

    const viewSlot = conversionApi.writer.createSlot( node => node.is( 'element', 'foo' ) );
const viewPosition = conversionApi.writer.createPositionAt( viewElement, 0 );

conversionApi.writer.insert( viewPosition, viewSlot );

    While providing a filtered slot, make sure to provide slots for all child nodes. A single node cannot be downcasted into multiple slots.

    Note: You should not change the order of nodes. View elements should be in the same order as model nodes.

    Parameters

    modeOrFilter : 'children' | SlotFilter

    The filter for child nodes.

    Defaults to 'children'

    Returns

    Element

    The slot element to be placed in to the view structure while processing elementToStructure().

  • createText( data ) → Text

    See source

    Creates a new text node.

    writer.createText( 'foo' );

    Parameters

    data : string

    The text's data.

    Returns

    Text

    The created text node.

  • createUIElement( name, [ attributes ], [ renderFunction ] ) → UIElement

    See source

    Creates a new UIElement.

    writer.createUIElement( 'span' );
writer.createUIElement( 'span', { id: 'foo-1234' } );

    A custom render function can be provided as the third parameter:

    writer.createUIElement( 'span', null, function( domDocument ) {
	const domElement = this.toDomElement( domDocument );
	domElement.innerHTML = '<b>this is ui element</b>';

	return domElement;
} );

    Unlike raw elements, UI elements are by no means editor content, for instance, they are ignored by the editor selection system.

    You should not use UI elements as data containers. Check out createRawElement instead.

    Parameters

    name : string

    The name of the element.

    [ attributes ] : ElementAttributes

    Element attributes.

    [ renderFunction ] : ( this: UIElement, domDocument: Document, domConverter: DomConverter ) => HTMLElement

    A custom render function.

    Returns

    UIElement

    The created element.

  • insert( position, nodes ) → Range

    See source

    Inserts a node or nodes at specified position. Takes care about breaking attributes before insertion and merging them afterwards.

    Throws CKEditorError view-writer-insert-invalid-node when nodes to insert contains instances that are not Texts, AttributeElements, ContainerElements, EmptyElements, RawElements or UIElements.

    Parameters

    position : Position

    Insertion position.

    nodes : Node | Iterable<Node>

    Node or nodes to insert.

    Returns

    Range

    Range around inserted nodes.

  • mergeAttributes( position ) → Position

    See source

    Merges attribute elements. It also merges text nodes if needed. Only similar attribute elements can be merged.

    In following examples <p> is a container and <b> is an attribute element:

    <p>foo[]bar</p> -> <p>foo{}bar</p>
<p><b>foo</b>[]<b>bar</b></p> -> <p><b>foo{}bar</b></p>
<p><b foo="bar">a</b>[]<b foo="baz">b</b></p> -> <p><b foo="bar">a</b>[]<b foo="baz">b</b></p>

    It will also take care about empty attributes when merging:

    <p><b>[]</b></p> -> <p>[]</p>
<p><b>foo</b><i>[]</i><b>bar</b></p> -> <p><b>foo{}bar</b></p>

    Note: Difference between mergeAttributes and mergeContainers is that mergeAttributes merges two attribute elements or text nodes while mergeContainer merges two container elements.

    Parameters

    position : Position

    Merge position.

    Returns

    Position

    Position after merge.

    Related:

  • mergeContainers( position ) → Position

    See source

    Merges two container elements that are before and after given position. Precisely, the element after the position is removed and it's contents are moved to element before the position.

    <p>foo</p>^<p>bar</p> -> <p>foo^bar</p>
<div>foo</div>^<p>bar</p> -> <div>foo^bar</div>

    Note: Difference between mergeAttributes and mergeContainers is that mergeAttributes merges two attribute elements or text nodes while mergeContainer merges two container elements.

    Parameters

    position : Position

    Merge position.

    Returns

    Position

    Position after merge.

    Related:

  • move( sourceRange, targetPosition ) → Range

    See source

    Moves nodes from provided range to target position.

    Throws CKEditorError view-writer-invalid-range-container when start and end positions are not placed inside same parent container.

    Parameters

    sourceRange : Range

    Range containing nodes to move.

    targetPosition : Position

    Position to insert.

    Returns

    Range

    Range in target container. Inserted nodes are placed between start and end positions.

  • remove( rangeOrItem ) → DocumentFragment

    See source

    Removes provided range from the container.

    Throws CKEditorError view-writer-invalid-range-container when start and end positions are not placed inside same parent container.

    Parameters

    rangeOrItem : Range | Item

    Range to remove from container or an item to remove. If range is provided, after removing, it will be updated to a collapsed range showing the new position.

    Returns

    DocumentFragment

    Document fragment containing removed nodes.

  • removeAttribute( key, tokens, element ) → void

    See source

    Removes specified tokens from an attribute value (for example class names, style properties). If resulting attribute become empty, the whole attribute is removed.

    writer.removeAttribute( 'class', 'foo', linkElement );

    Parameters

    key : string

    Attribute key.

    tokens : ArrayOrItem<string>

    Tokens to partly remove from attribute value. For example class names or style property names.

    element : Element

    The element to remove an attribute of.

    Returns

    void

  • removeAttribute( key, element ) → void

    See source

    Removes attribute from the element.

    writer.removeAttribute( 'href', linkElement );

    Parameters

    key : string

    Attribute key.

    element : Element

    The element to remove an attribute of.

    Returns

    void

  • removeClass( className, element ) → void

    See source

    Removes specified class from the element.

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

    Parameters

    className : string | Array<string>
    element : Element

    Returns

    void

  • removeCustomProperty( key, element ) → boolean

    See source

    Removes a custom property stored under the given key.

    Parameters

    key : string | symbol
    element : Element | DocumentFragment

    Returns

    boolean

    Returns true if property was removed.

  • removeStyle( property, element ) → void

    See source

    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>
    element : Element

    Returns

    void

  • rename( newName, viewElement ) → ContainerElement

    See source

    Renames element by creating a copy of renamed element but with changed name and then moving contents of the old element to the new one. Keep in mind that this will invalidate all positions which has renamed element as a parent.

    New element has to be created because Element#tagName property in DOM is readonly.

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

    Parameters

    newName : string

    New name for element.

    viewElement : ContainerElement

    Element to be renamed.

    Returns

    ContainerElement

    Element created due to rename.

  • setAttribute( key, value, overwrite, element ) → void

    See source

    Adds or overwrites the element's attribute with a specified key and value. Note that for tokenized attributes it allows the reset parameter to specify if the previous attribute value should be overwritten or a new token (class name, style property) should be added.

    writer.setAttribute( 'href', 'http://ckeditor.com', linkElement );
writer.setAttribute( 'class', 'foo', false, element );

    Parameters

    key : string

    The attribute key.

    value : unknown

    The attribute value.

    overwrite : boolean

    Whether tokenized attribute should overwrite the attribute value or just add a token.

    element : Element

    The element to set an attribute on.

    Returns

    void

  • setAttribute( key, value, element ) → void

    See source

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

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

    Parameters

    key : string

    The attribute key.

    value : unknown

    The attribute value.

    element : Element

    The element to set an attribute on.

    Returns

    void

  • setCustomProperty( key, value, element ) → void

    See source

    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
    value : unknown
    element : Element | DocumentFragment

    Returns

    void

  • setSelection( selectable, [ options ] ) → void

    See source

    Sets selection's ranges and direction to the specified location based on the given selectable.

    Usage:

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

// Sets backward 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( start2, end2 ) ];
writer.setSelection( range );

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

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

// Removes all ranges.
writer.setSelection( null );

    DowncastWriter#setSelection() allow passing additional options (backward, fake and label) as the last argument.

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

// Sets selection as fake.
// 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.
writer.setSelection( range, { fake: true } );

// 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).
writer.setSelection( range, { fake: true, label: 'foo' } );

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

    Parameters

    selectable : null | Position | Range | Selection | DocumentSelection | Iterable<Range>
    [ options ] : SelectionOptions

    Returns

    void

  • setSelection( selectable, placeOrOffset, [ options ] ) → void

    See source

    Sets selection's ranges and direction to the specified location based on the given selectable.

    Usage:

    // Sets collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'p' );
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 the item which starts before the item and ends just after the item.

    writer.setSelection( paragraph, 'on' );

    DowncastWriter#setSelection() allow passing additional options (backward, fake and label) as the last argument.

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

// Sets selection as fake.
// 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.
writer.setSelection( element, 'in', { fake: true } );

// 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).
writer.setSelection( element, 'in', { fake: true, label: 'foo' } );

    See also: setSelection( selectable, options ).

    Parameters

    selectable : Node
    placeOrOffset : PlaceOrOffset
    [ options ] : SelectionOptions

    Returns

    void

  • setSelectionFocus( itemOrPosition, [ offset ] ) → void

    See source

    Moves selection's focus to the specified location.

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

    Parameters

    itemOrPosition : Position | Item
    [ offset ] : PositionOffset

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

    Returns

    void

  • setStyle( property, element ) → void

    See source

    Adds many styles to the element.

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

    Note: The passed style can be normalized if a particular style processor rule is enabled. See StylesMap#set() for details.

    Parameters

    property : Record<string, string>

    Object with key - value pairs.

    element : Element

    Element to set styles on.

    Returns

    void

  • setStyle( property, value, element ) → void

    See source

    Adds style to the element.

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

    Note: The passed style can be normalized if a particular style processor rule is enabled. See StylesMap#set() for details.

    Parameters

    property : string

    Property name.

    value : string

    Value to set.

    element : Element

    Element to set styles on.

    Returns

    void

  • unwrap( range, attribute ) → Range

    See source

    Unwraps nodes within provided range from attribute element.

    Throws CKEditorError view-writer-invalid-range-container when start and end positions are not placed inside same parent container.

    Parameters

    range : Range
    attribute : AttributeElement

    Returns

    Range

  • wrap( range, attribute ) → Range

    See source

    Wraps elements within range with provided AttributeElement. If a collapsed range is provided, it will be wrapped only if it is equal to view selection.

    If a collapsed range was passed and is same as selection, the selection will be moved to the inside of the wrapped attribute element.

    Throws CKEditorError view-writer-invalid-range-container when start and end positions are not placed inside same parent container.

    Throws CKEditorError view-writer-wrap-invalid-attribute when passed attribute element is not an instance of AttributeElement.

    Throws CKEditorError view-writer-wrap-nonselection-collapsed-range when passed range is collapsed and different than view selection.

    Parameters

    range : Range

    Range to wrap.

    attribute : AttributeElement

    Attribute element to use as wrapper.

    Returns

    Range

    range Range after wrapping, spanning over wrapping attribute element.

  • internal

    _clearSlotFactory() → void

    See source

    Clears the registered slot factory.

    Returns

    void

  • internal

    _registerSlotFactory( slotFactory ) → void

    See source

    Registers a slot factory.

    Parameters

    slotFactory : ( writer: DowncastWriter, modeOrFilter: 'children' | SlotFilter ) => Element

    The slot factory.

    Returns

    void

  • private

    _addToClonedElementsGroup( element ) → void

    See source

    Stores the information that an attribute element was added to the tree. Saves the reference to the group in the given element and updates the group, so other elements from the group now keep a reference to the given attribute element.

    The clones group can be obtained using getElementsWithSameId.

    Does nothing if added element has no id.

    Parameters

    element : Node

    Attribute element to save.

    Returns

    void

  • private

    _breakAttributes( position, forceSplitText ) → Position

    See source

    Helper function used by other DowncastWriter methods. Breaks attribute elements at given position.

    Throws CKEditorError view-writer-cannot-break-empty-element when break position is placed inside EmptyElement.

    Throws CKEditorError view-writer-cannot-break-ui-element when break position is placed inside UIElement.

    Parameters

    position : Position

    Position where to break attributes.

    forceSplitText : boolean

    If set to true, will break text nodes even if they are directly in container element. This behavior will result in incorrect view state, but is needed by other view writing methods which then fixes view state.

    Defaults to false

    Returns

    Position

    New position after breaking the attributes.

  • private

    _breakAttributesRange( range, forceSplitText ) → Range

    See source

    Helper function used by other DowncastWriter methods. Breaks attribute elements at the boundaries of given range.

    Parameters

    range : Range

    Range which start and end positions will be used to break attributes.

    forceSplitText : boolean

    If set to true, will break text nodes even if they are directly in container element. This behavior will result in incorrect view state, but is needed by other view writing methods which then fixes view state.

    Defaults to false

    Returns

    Range

    New range with located at break positions.

  • private

    _insertNodes( position, nodes, breakAttributes ) → Range

    See source

    Inserts a node or nodes at the specified position. Takes care of breaking attributes before insertion and merging them afterwards if requested by the breakAttributes param.

    Parameters

    position : Position

    Insertion position.

    nodes : Iterable<Node>

    Node or nodes to insert.

    breakAttributes : boolean

    Whether attributes should be broken.

    Returns

    Range

    Range around inserted nodes.

  • private

    _removeFromClonedElementsGroup( element ) → void

    See source

    Removes all the information about the given attribute element from its clones group.

    Keep in mind, that the element will still keep a reference to the group (but the group will not keep a reference to it). This allows to reference the whole group even if the element was already removed from the tree.

    Does nothing if the element has no id.

    Parameters

    element : Node

    Attribute element to remove.

    Returns

    void

  • private

    _unwrapChildren( parent, startOffset, endOffset, unwrapElement ) → Range

    See source

    Unwraps children from provided unwrapElement. Only children contained in parent element between startOffset and endOffset will be unwrapped.

    Parameters

    parent : Element
    startOffset : number
    endOffset : number
    unwrapElement : AttributeElement

    Returns

    Range

  • private

    _wrapChildren( parent, startOffset, endOffset, wrapElement ) → Range

    See source

    Wraps children with provided wrapElement. Only children contained in parent element between startOffset and endOffset will be wrapped.

    Parameters

    parent : Element
    startOffset : number
    endOffset : number
    wrapElement : AttributeElement

    Returns

    Range

  • private

    _wrapPosition( position, attribute ) → Position

    See source

    Helper function for wrap. Wraps position with provided attribute element. This method will also merge newly added attribute element with its siblings whenever possible.

    Throws CKEditorError view-writer-wrap-invalid-attribute when passed attribute element is not an instance of AttributeElement.

    Parameters

    position : Position
    attribute : AttributeElement

    Returns

    Position

    New position after wrapping.

  • private

    _wrapRange( range, attribute ) → Range

    See source

    Helper function for view.writer.wrap. Wraps range with provided attribute element. This method will also merge newly added attribute element with its siblings whenever possible.

    Throws CKEditorError view-writer-wrap-invalid-attribute when passed attribute element is not an instance of AttributeElement.

    Parameters

    range : Range
    attribute : AttributeElement

    Returns

    Range

    New range after wrapping, spanning over wrapping attribute element.