Sign up (with export icon)

ViewUpcastWriter

Api-class icon class

View upcast writer. It provides a set of methods used to manipulate non-semantic view trees.

It should be used only while working on a non-semantic view (e.g. a view created from HTML string on paste). To manipulate a view which was or is being downcasted from the the model use the downcast writer.

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

Unlike ViewDowncastWriter, which is available in the View#change() block, ViewUpcastWriter can be created wherever you need it:

const writer = new ViewUpcastWriter( viewDocument );
const text = writer.createText( 'foo!' );

writer.appendChild( text, someViewElement );
Copy code
See source (with github icon)

Properties

Methods

  • Chevron-right icon

    constructor( document )

    See source (with github icon)

    Parameters

    document : ViewDocument

    The view document instance in which this upcast writer operates.

  • Chevron-right icon

    addClass( className, element ) → void

    Adds specified class to the element.

    writer.addClass( 'foo', linkElement );
writer.addClass( [ 'foo', 'bar' ], linkElement );
    Copy code
    See source (with github icon)

    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:

  • Chevron-right icon

    appendChild( items, element ) → number

    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.

    See source (with github icon)

    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:

  • Chevron-right icon

    clone( element, deep ) → ViewElement

    Clones the provided element.

    See source (with github icon)

    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:

  • Chevron-right icon

    createDocumentFragment( [ children ] ) → ViewDocumentFragment

    Creates a new ViewDocumentFragment instance.

    See source (with github icon)

    Parameters

    [ children ] : ViewNode | Iterable<ViewNode>

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

    Returns

    ViewDocumentFragment

    The created document fragment.

  • Chevron-right icon

    createElement( name, [ attrs ], [ children ] ) → ViewElement

    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
    Copy code
    See source (with github icon)

    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.

  • Chevron-right icon

    createPositionAfter( item ) → ViewPosition

    Creates a new position after given view item.

    See source (with github icon)

    Parameters

    item : ViewItem

    View item after which the position should be located.

    Returns

    ViewPosition
  • Chevron-right icon

    createPositionAt( itemOrPosition, [ offset ] ) → 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:

    See source (with github icon)

    Parameters

    itemOrPosition : ViewPosition | ViewItem
    [ offset ] : ViewPositionOffset

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

    Returns

    ViewPosition
  • Chevron-right icon

    createPositionBefore( item ) → ViewPosition

    Creates a new position before given view item.

    See source (with github icon)

    Parameters

    item : ViewItem

    View item before which the position should be located.

    Returns

    ViewPosition
  • Chevron-right icon

    createRange( start, end ) → ViewRange

    Creates a range spanning from start position to end position.

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

    See source (with github icon)

    Parameters

    start : ViewPosition

    Start position.

    end : ViewPosition

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

    Returns

    ViewRange
  • Chevron-right icon

    createRangeIn( element ) → 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.

    See source (with github icon)

    Parameters

    element : ViewElement | ViewDocumentFragment

    Element which is a parent for the range.

    Returns

    ViewRange
  • Chevron-right icon

    createRangeOn( item ) → ViewRange

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

    See source (with github icon)

    Parameters

    item : ViewItem

    Returns

    ViewRange
  • Chevron-right icon

    createSelection( [ selectable ], [ options ] ) → ViewSelection

    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 );
    Copy code

    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 } );
    Copy code

    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' } );
    Copy code

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

    See source (with github icon)

    Parameters

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

    Returns

    ViewSelection
  • Chevron-right icon

    createSelection( selectable, placeOrOffset, [ options ] ) → 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' );
    Copy code

    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 } );
    Copy code

    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' } );
    Copy code

    See also: createSelection( selectable, options ).

    See source (with github icon)

    Parameters

    selectable : ViewNode
    placeOrOffset : ViewPlaceOrOffset
    [ options ] : ViewSelectionOptions

    Returns

    ViewSelection
  • Chevron-right icon

    createText( data ) → ViewText

    Creates a new ViewText instance.

    See source (with github icon)

    Parameters

    data : string

    The text's data.

    Returns

    ViewText

    The created text node.

  • Chevron-right icon

    insertChild( index, items, element ) → number

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

    See source (with github icon)

    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:

  • Chevron-right icon

    remove( element ) → Array<ViewNode>

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

    See source (with github icon)

    Parameters

    element : ViewNode

    Element which will be removed.

    Returns

    Array<ViewNode>

    The array containing removed nodes.

  • Chevron-right icon

    removeAttribute( key, element ) → void

    Removes attribute from the element.

    writer.removeAttribute( 'href', linkElement );
    Copy code
    See source (with github icon)

    Parameters

    key : string

    Attribute key.

    element : ViewElement

    Element from which attribute will be removed.

    Returns

    void

    Related:

  • Chevron-right icon

    removeChildren( index, howMany, element ) → Array<ViewNode>

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

    See source (with github icon)

    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:

  • Chevron-right icon

    removeClass( className, element ) → void

    Removes specified class from the element.

    writer.removeClass( 'foo', linkElement );
writer.removeClass( [ 'foo', 'bar' ], linkElement );
    Copy code
    See source (with github icon)

    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:

  • Chevron-right icon

    removeCustomProperty( key, element ) → boolean

    Removes a custom property stored under the given key.

    See source (with github icon)

    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:

  • Chevron-right icon

    removeStyle( property, element ) → void

    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.
    Copy code

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

    See source (with github icon)

    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:

  • Chevron-right icon

    rename( newName, element ) → null | ViewElement

    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.

    See source (with github icon)

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

  • Chevron-right icon

    replace( oldElement, newElement ) → boolean

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

    See source (with github icon)

    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.

  • Chevron-right icon

    setAttribute( key, value, element ) → void

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

    writer.setAttribute( 'href', 'http://ckeditor.com', linkElement );
    Copy code
    See source (with github icon)

    Parameters

    key : string

    Attribute key.

    value : unknown

    Attribute value.

    element : ViewElement

    Element for which attribute will be set.

    Returns

    void

    Related:

  • Chevron-right icon

    setCustomProperty( key, value, element ) → void

    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.

    See source (with github icon)

    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:

  • Chevron-right icon

    setStyle( properties, element ) → void

    Adds style to the element.

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

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

    See source (with github icon)

    Parameters

    properties : Record<string, string>

    Object with key - value pairs.

    element : ViewElement

    Element for which style will be added.

    Returns

    void

    Related:

  • Chevron-right icon

    setStyle( property, value, element ) → void

    Adds style to the element.

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

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

    See source (with github icon)

    Parameters

    property : string

    Property name.

    value : string

    Value to set.

    element : ViewElement

    Element for which style will be added.

    Returns

    void

    Related:

  • Chevron-right icon

    unwrapElement( element ) → void

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

    See source (with github icon)

    Parameters

    element : ViewElement

    Element to unwrap.

    Returns

    void

Was this page helpful?

Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.

GitHubSupportContact Us

© 2003 - 2025  CKSource. All rights reserved.