UpcastWriter (engine/view)
@ckeditor/ckeditor5-engine/src/view/upcastwriter
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 DowncastWriter
, which is available in the View#change()
block,
UpcastWriter
can be created wherever you need it:
const writer = new UpcastWriter( viewDocument );
const text = writer.createText( 'foo!' );
writer.appendChild( text, someViewElement );
Filtering
Properties
-
The view document instance in which this upcast writer operates.
Methods
-
constructor( document )
module:engine/view/upcastwriter~UpcastWriter#constructor
Parameters
document : Document
The view document instance in which this upcast writer operates.
-
addClass( className, element ) → void
module:engine/view/upcastwriter~UpcastWriter#addClass
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 : Element
Element for which class will be added.
Returns
void
Related:
-
appendChild( items, element ) → number
module:engine/view/upcastwriter~UpcastWriter#appendChild
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 | Item | Iterable<string | Item>
Items to be inserted.
element : Element | DocumentFragment
Element to which items will be appended.
Returns
number
Number of appended nodes.
Related:
-
createDocumentFragment( [ children ] ) → DocumentFragment
module:engine/view/upcastwriter~UpcastWriter#createDocumentFragment
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.
-
createElement( name, [ attrs ], [ children ] ) → Element
module:engine/view/upcastwriter~UpcastWriter#createElement
Creates a new
Element
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 ] : ElementAttributes
Collection of attributes.
[ children ] : Node | Iterable<Node>
A list of nodes to be inserted into created element.
Returns
Element
Created element.
-
createPositionAfter( item ) → Position
module:engine/view/upcastwriter~UpcastWriter#createPositionAfter
Creates a new position after given view item.
Parameters
item : Item
View item after which the position should be located.
Returns
-
createPositionAt( itemOrPosition, [ offset ] ) → Position
module:engine/view/upcastwriter~UpcastWriter#createPositionAt
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 first parameter is a view item.
Returns
-
createPositionBefore( item ) → Position
module:engine/view/upcastwriter~UpcastWriter#createPositionBefore
Creates a new position before given view item.
Parameters
item : Item
View item before which the position should be located.
Returns
-
createRange( start, end ) → Range
module:engine/view/upcastwriter~UpcastWriter#createRange
-
createRangeIn( element ) → Range
module:engine/view/upcastwriter~UpcastWriter#createRangeIn
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
-
createRangeOn( item ) → Range
module:engine/view/upcastwriter~UpcastWriter#createRangeOn
-
createSelection( [ selectable ], [ options ] ) → Selection
module:engine/view/upcastwriter~UpcastWriter#createSelection:SELECTABLE
Creates a 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
andlabel
) 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>
[ options ] : SelectionOptions
Returns
-
createSelection( selectable, placeOrOffset, [ options ] ) → Selection
module:engine/view/upcastwriter~UpcastWriter#createSelection:NODE_OFFSET
Creates a new
Selection
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
andlabel
) 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
-
createText( data ) → Text
module:engine/view/upcastwriter~UpcastWriter#createText
-
insertChild( index, items, element ) → number
module:engine/view/upcastwriter~UpcastWriter#insertChild
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 : Item | Iterable<Item>
Items to be inserted.
element : Element | DocumentFragment
Element to which items will be inserted.
Returns
number
Number of inserted nodes.
Related:
-
removeAttribute( key, element ) → void
module:engine/view/upcastwriter~UpcastWriter#removeAttribute
Removes attribute from the element.
writer.removeAttribute( 'href', linkElement );
Parameters
key : string
Attribute key.
element : Element
Element from which attribute will be removed.
Returns
void
Related:
-
removeChildren( index, howMany, element ) → Array<Node>
module:engine/view/upcastwriter~UpcastWriter#removeChildren
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 : Element | DocumentFragment
Element which children will be removed.
Returns
Array<Node>
The array containing removed nodes.
Related:
-
removeClass( className, element ) → void
module:engine/view/upcastwriter~UpcastWriter#removeClass
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 : Element
Element from which class will be removed.
Returns
void
Related:
-
removeCustomProperty( key, element ) → boolean
module:engine/view/upcastwriter~UpcastWriter#removeCustomProperty
Removes a custom property stored under the given key.
Parameters
key : string | symbol
Name/key of the custom property to be removed.
element : Element | DocumentFragment
Element from which the custom property will be removed.
Returns
boolean
Returns true if property was removed.
Related:
-
removeStyle( property, element ) → void
module:engine/view/upcastwriter~UpcastWriter#removeStyle
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 : Element
Element from which style will be removed.
Returns
void
Related:
-
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 : Element
Element to be renamed.
Returns
null | Element
New element or null if the old element was not replaced (happens for detached elements).
-
replace( oldElement, newElement ) → boolean
module:engine/view/upcastwriter~UpcastWriter#replace
Replaces given element with the new one in the view structure. Will not have effect on detached elements.
Parameters
oldElement : Element
Element which will be replaced.
newElement : Element
Element which will be inserted in the place of the old element.
Returns
boolean
Whether old element was successfully replaced.
-
setAttribute( key, value, element ) → void
module:engine/view/upcastwriter~UpcastWriter#setAttribute
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 : Element
Element for which attribute will be set.
Returns
void
Related:
-
setCustomProperty( key, value, element ) → void
module:engine/view/upcastwriter~UpcastWriter#setCustomProperty
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 : Element | DocumentFragment
Element for which custom property will be set.
Returns
void
Related:
-
setStyle( properties, element ) → void
module:engine/view/upcastwriter~UpcastWriter#setStyle:OBJECT
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 : Element
Element for which style will be added.
Returns
void
Related:
-
setStyle( property, value, element ) → void
module:engine/view/upcastwriter~UpcastWriter#setStyle:KEY_VALUE
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 : Element
Element for which style will be added.
Returns
void
Related:
-
unwrapElement( element ) → void
module:engine/view/upcastwriter~UpcastWriter#unwrapElement
Removes given element from view structure and places its children in its position. It does nothing if element has no parent.
Parameters
element : Element
Element to unwrap.
Returns
void
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.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.