UIElement (engine/view)

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

class

Hierarchy

Node
- Element
  - UIElement

UI element class. It should be used to represent editing UI which needs to be injected into the editing view If possible, you should keep your UI outside the editing view. However, if that is not possible, UI elements can be used.

How a UI element is rendered is in your control (you pass a callback to downcastWriter#createUIElement()). The editor will ignore your UI element – the selection cannot be placed in it, it is skipped (invisible) when the user modifies the selection by using arrow keys and the editor does not listen to any mutations which happen inside your UI elements.

The limitation is that you cannot convert a model element to a UI element. UI elements need to be created for markers or as additinal elements inside normal container elements.

To create a new UI element use the downcastWriter#createUIElement() method.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

childCount : Number

readonly inherited

Number of element's children.

See source
document : Document

readonly inherited

The document instance to which this node belongs.

See source
index : Number | null

readonly inherited

Index of the node in the parent element or null if the node has no parent.

See source

Accessing this property throws an error if this node's parent element does not contain it. This means that view tree got broken.
isAllowedInsideAttributeElement : Boolean

readonly inherited

Whether the element is allowed inside an AttributeElement and can be wrapped with AttributeElement by DowncastWriter.

See source
isEmpty : Boolean

readonly inherited

Is true if there are no nodes inside this element, false otherwise.

See source
name : String

readonly inherited

Name of the element.

See source
nextSibling : Node | null

readonly inherited

Node's next sibling, or null if it is the last child.

See source
parent : Element | DocumentFragment | null

readonly inherited

Parent element. Null by default. Set by _insertChild.

See source
previousSibling : Node | null

readonly inherited

Node's previous sibling, or null if it is the first child.

See source
root : Node | DocumentFragment

readonly inherited

Top-most ancestor of the node. If the node has no parent it is the root itself.

See source
_attrs : Map

protected inherited

Map of attributes, where attributes names are keys and attributes values are values.

See source
_children : Array.<Node>

protected inherited

Array of child nodes.

See source
_classes : Set

protected inherited

Set of classes associated with element instance.

See source
_customProperties : Map

protected inherited

Map of custom properties. Custom properties can be added to element instance, will be cloned but not rendered into DOM.

See source
_isAllowedInsideAttributeElement : Boolean

protected inherited

Whether an element is allowed inside an AttributeElement and can be wrapped with AttributeElement by DowncastWriter.

See source
_styles : StylesMap

protected inherited

Normalized styles.

See source

Methods

constructor( document, name, [ attributes ], [ children ] )

protected
Creates new instance of UIElement.

See source
Throws CKEditorError view-uielement-cannot-add when third parameter is passed, to inform that usage of UIElement is incorrect (adding child nodes to UIElement is forbidden).

Parameters

document : Document

The document instance to which this element belongs.

name : String

Node name.

[ attributes ] : Object | Iterable

Collection of attributes.

[ children ] : Node | Iterable.<Node>

A list of nodes to be inserted into created element.

Related:
- DowncastWriter#createUIElement
findAncestor( patterns ) → Element | null

inherited
Returns ancestor element that match specified pattern. Provided patterns should be compatible with Matcher as it is used internally.

See source
Parameters

patterns : Object | String | RegExp | function

Patterns used to match correct ancestor. See Matcher.

Returns

Element | null

Found element or null if no matching ancestor was found.

Related:
- Matcher
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array

inherited

Returns ancestors array of this node.

See source

Parameters

options : Object

Options object.

Properties

[ options.includeSelf ] : Boolean

When set to true this node will be also included in parent's array.

Defaults to false

[ options.parentFirst ] : Boolean

When set to true, array will be sorted from node's parent to root element, otherwise root element will be the first item in the array.

Defaults to false

Returns

Array

Array with ancestors.
getAttribute( key ) → String | undefined

inherited

Gets attribute by key. If attribute is not present - returns undefined.

See source

Parameters

key : String

Attribute key.

Returns

String | undefined

Attribute value.
getAttributeKeys() → Iterable.<String>

inherited

Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.

See source

Returns

Iterable.<String>

Keys for attributes.
getAttributes() → Iterable.<*>

inherited

Returns iterator that iterates over this element's attributes.

See source

Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native Map object and also can be passed in Node constructor.

Returns

Iterable.<*>
getChild( index ) → Node

inherited

Gets child at the given index.

See source

Parameters

index : Number

Index of child.

Returns

Node

Child node.
getChildIndex( node ) → Number

inherited

Gets index of the given child node. Returns -1 if child node is not found.

See source

Parameters

node : Node

Child node.

Returns

Number

Index of the child node.
getChildren() → Iterable.<Node>

inherited

Gets child nodes iterator.

See source

Returns

Iterable.<Node>

Child nodes iterator.
getClassNames() → Iterable.<String>

inherited

Returns iterator that contains all class names.

See source

Returns

Iterable.<String>
getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null

inherited

Returns a Element or DocumentFragment which is a common ancestor of both nodes.

See source

Parameters

node : Node

The second node.

options : Object

Options object.

Properties

[ options.includeSelf ] : Boolean

When set to true both nodes will be considered "ancestors" too. Which means that if e.g. node A is inside B, then their common ancestor will be B.

Defaults to false

Returns

Element | DocumentFragment | null
getCustomProperties() → Iterable.<*>

inherited

Returns an iterator which iterates over this element's custom properties. Iterator provides [ key, value ] pairs for each stored property.

See source

Returns

Iterable.<*>
getCustomProperty( key ) → *

inherited

Returns the custom property value for the given key.

See source

Parameters

key : String | Symbol

Returns

*
getFillerOffset() → null

inherited

Returns null because filler is not needed for UIElements.

See source

Returns

null

Always returns null.
getIdentity() → String

inherited
Returns identity string based on element's name, styles, classes and other attributes. Two elements that are similar will have same identity string. It has the following format:

See source
```
'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'
```
For example:
```
const element = writer.createContainerElement( 'foo', {
	banana: '10',
	apple: '20',
	style: 'color: red; border-color: white;',
	class: 'baz'
} );

// returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"'
element.getIdentity();
```
Note: Classes, styles and other attributes are sorted alphabetically.

Returns

String
getNormalizedStyle( property ) → Object | String | undefined

inherited
Returns a normalized style object or single style value.

See source
For an element with style set to: margin:1px 2px 3em;
```
element.getNormalizedStyle( 'margin' ) );
```
will return:
```
{
	top: '1px',
	right: '2px',
	bottom: '3em',
	left: '2px'    // a normalized value from margin shorthand
}
```
and reading for single style value:
```
styles.getNormalizedStyle( 'margin-left' );
```
Will return a 2px string.

Note: This method will return normalized values only if a particular style processor rule is enabled. See StylesMap#getNormalized() for details.

Parameters

property : String

Name of CSS property

Returns

Object | String | undefined

`getPath() → Array.<Number>`

inherited

Gets a path to the node. The path is an array containing indices of consecutive ancestors of this node, beginning from root, down to this node's index.

See source

const abc = downcastWriter.createText( 'abc' );
const foo = downcastWriter.createText( 'foo' );
const h1 = downcastWriter.createElement( 'h1', null, downcastWriter.createText( 'header' ) );
const p = downcastWriter.createElement( 'p', null, [ abc, foo ] );
const div = downcastWriter.createElement( 'div', null, [ h1, p ] );
foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
h1.getPath(); // Returns [ 0 ].
div.getPath(); // Returns [].

Returns

Array.<Number>: The path.

getStyle( property ) → String | undefined

inherited
Returns style value for the given property mae. If the style does not exist undefined is returned.

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

For an element with style set to 'margin:1px':
```
// Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

const element = view.change( writer => {
	const element = writer.createElement();
	writer.setStyle( 'margin', '1px' );
	writer.setStyle( 'margin-bottom', '3em' );

	return element;
} );

element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'
```
Parameters

property : String

Returns

String | undefined
getStyleNames() → Iterable.<String>

inherited

Returns iterator that contains all style names.

See source

Returns

Iterable.<String>
hasAttribute( key ) → Boolean

inherited

Returns a boolean indicating whether an attribute with the specified key exists in the element.

See source

Parameters

key : String

Attribute key.

Returns

Boolean

true if attribute with the specified key exists in the element, false otherwise.
hasClass( className )

inherited
Returns true if class is present. If more then one class is provided - returns true only when all classes are present.

See source
```
element.hasClass( 'foo' ); // Returns true if 'foo' class is present.
element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.
```
Parameters

className : String
hasStyle( property )

inherited
Returns true if style keys are present. If more then one style property is provided - returns true only when all properties are present.

See source
```
element.hasStyle( 'color' ); // Returns true if 'border-top' style is present.
element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.
```
Parameters

property : String
is( type ) → Boolean

inherited
Checks whether this object is of the given type.

See source
This method is useful when processing view objects that are of unknown type. For example, a function may return a DocumentFragment or a Node that can be either a text node or an element. This method can be used to check what kind of object is returned.
```
someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment
```
Since this method is also available on a range of model objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:
```
viewElement.is( 'view:element' ); // -> true
viewElement.is( 'model:element' ); // -> false
```
By using this method it is also possible to check a name of an element:
```
imgElement.is( 'element', 'img' ); // -> true
imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise
```
The list of view objects which implement the is() method:
Parameters

type : String

Type to check.

Returns

Boolean
isAfter( node ) → Boolean

inherited

Returns whether this node is after given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

See source

Parameters

node : Node

Node to compare with.

Returns

Boolean
isAttached() → Boolean

inherited

Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).

See source

Returns

Boolean
isBefore( node ) → Boolean

inherited

Returns whether this node is before given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

See source

Parameters

node : Node

Node to compare with.

Returns

Boolean
isSimilar( otherElement ) → Boolean

inherited

Checks if this element is similar to other element. Both elements should have the same name and attributes to be considered as similar. Two similar elements can contain different set of children nodes.

See source

Parameters

otherElement : Element

Returns

Boolean
render( domDocument ) → HTMLElement
Renders this UIElement to DOM. This method is called by DomConverter. Do not use inheritance to create custom rendering method, replace render() method instead:

See source
```
const myUIElement = downcastWriter.createUIElement( 'span' );
myUIElement.render = function( domDocument ) {
	const domElement = this.toDomElement( domDocument );
	domElement.innerHTML = '<b>this is ui element</b>';

	return domElement;
};
```
If changes in your UI element should trigger some editor UI update you should call the editor.ui.update() method after rendering your UI element.

Parameters

domDocument : Document

Returns

HTMLElement
toDomElement( domDocument ) → HTMLElement

Creates DOM element based on this view UIElement. Note that each time this method is called new DOM element is created.

See source

Parameters

domDocument : Document

Returns

HTMLElement
toJSON() → Object

inherited

Custom toJSON method to solve child-parent circular dependencies.

See source

Returns

Object

Clone of this object with the parent property removed.
_addClass( className )

protected inherited
Adds specified class.

See source
```
element._addClass( 'foo' ); // Adds 'foo' class.
element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.
```
Parameters

className : Array.<String> | String

Fires
- change
Related:
- DowncastWriter#addClass
_appendChild( items ) → Number

protected inherited
Insert 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
Parameters

items : Item | Iterable.<Item>

Items to be inserted.

Returns

Number

Number of appended nodes.

Fires
- change
Related:
- DowncastWriter#insert
_clone( [ deep ] ) → Element

protected inherited

Clones provided element.

See source

Parameters

[ 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

Element

Clone of this element.
_fireChange( type, node )

protected inherited
Parameters

type : ChangeType

Type of the change.

node : Node

Changed node.

Fires
- change
_insertChild( index, items ) → Number

protected inherited
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
Parameters

index : Number

Position where nodes should be inserted.

items : Item | Iterable.<Item>

Items to be inserted.

Returns

Number

Number of inserted nodes.

Fires
- change
Related:
- DowncastWriter#insert
_remove()

protected inherited

Removes node from parent.

See source
_removeAttribute( key ) → Boolean

protected inherited
Removes attribute from the element.

See source
Parameters

key : String

Attribute key.

Returns

Boolean

Returns true if an attribute existed and has been removed.

Fires
- change
Related:
- DowncastWriter#removeAttribute
_removeChildren( index, [ howMany ] ) → Array.<Node>

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

See source
Parameters

index : Number

Number of the first node to remove.

[ howMany ] : Number

Number of nodes to remove.

Defaults to 1

Returns

Array.<Node>

The array of removed nodes.

Fires
- change
Related:
- DowncastWriter#remove
_removeClass( className )

protected inherited
Removes specified class.

See source
```
element._removeClass( 'foo' );  // Removes 'foo' class.
element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.
```
Parameters

className : Array.<String> | String

Fires
- change
Related:
- DowncastWriter#removeClass
_removeCustomProperty( key ) → Boolean

protected inherited
Removes the custom property stored under the given key.

See source
Parameters

key : String | Symbol

Returns

Boolean

Returns true if property was removed.

Related:
- DowncastWriter#removeCustomProperty
_removeStyle( property )

protected inherited
Removes specified style.

See source
```
element._removeStyle( 'color' );  // Removes 'color' style.
element._removeStyle( [ 'color', 'border-top' ] ); // 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 : Array.<String> | String

Fires
- change
Related:
- DowncastWriter#removeStyle
_setAttribute( key, value )

protected inherited
Adds or overwrite attribute with a specified key and value.

See source
Parameters

key : String

Attribute key.

value : String

Attribute value.

Fires
- change
Related:
- DowncastWriter#setAttribute
_setCustomProperty( key, value )

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

See source
Parameters

key : String | Symbol

value : *

Related:
- DowncastWriter#setCustomProperty
_setStyle( property, [ value ] )

protected inherited
Adds style to the element.

See source
```
element._setStyle( 'color', 'red' );
element._setStyle( {
	color: 'red',
	position: 'fixed'
} );
```
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 | Object

Property name or object with key - value pairs.

[ value ] : String

Value to set. This parameter is ignored if object is provided as the first parameter.

Fires
- change
Related:
- DowncastWriter#setStyle

Events

change( eventInfo )

inherited

Parameters

eventInfo : EventInfo

An object containing information about the fired event.
change:attributes( eventInfo, changedNode )

inherited

Fired when list of elements attributes changes.

See source

Change event is bubbled – it is fired on all ancestors.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : Node
change:children( eventInfo, changedNode )

inherited

Fired when list of elements children changes.

See source

Change event is bubbled – it is fired on all ancestors.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : Node
change:text( eventInfo, changedNode )

inherited

Fired when text nodes data changes.

See source

Change event is bubbled – it is fired on all ancestors.

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

changedNode : Node

UIElement (engine/view)

Filtering

Properties

childCount : Numbermodule:engine/view/uielement~UIElement#childCount

document : Documentmodule:engine/view/uielement~UIElement#document

index : Number | nullmodule:engine/view/uielement~UIElement#index

isAllowedInsideAttributeElement : Booleanmodule:engine/view/uielement~UIElement#isAllowedInsideAttributeElement

isEmpty : Booleanmodule:engine/view/uielement~UIElement#isEmpty

name : Stringmodule:engine/view/uielement~UIElement#name

nextSibling : Node | nullmodule:engine/view/uielement~UIElement#nextSibling

parent : Element | DocumentFragment | nullmodule:engine/view/uielement~UIElement#parent

previousSibling : Node | nullmodule:engine/view/uielement~UIElement#previousSibling

root : Node | DocumentFragmentmodule:engine/view/uielement~UIElement#root

_attrs : Mapmodule:engine/view/uielement~UIElement#_attrs

_children : Array.<Node>module:engine/view/uielement~UIElement#_children

_classes : Setmodule:engine/view/uielement~UIElement#_classes

_customProperties : Mapmodule:engine/view/uielement~UIElement#_customProperties

_isAllowedInsideAttributeElement : Booleanmodule:engine/view/uielement~UIElement#_isAllowedInsideAttributeElement

_styles : StylesMapmodule:engine/view/uielement~UIElement#_styles

Methods

constructor( document, name, [ attributes ], [ children ] )module:engine/view/uielement~UIElement#constructor

Parameters

Related:

findAncestor( patterns ) → Element | nullmodule:engine/view/uielement~UIElement#findAncestor

Parameters

Returns

Related:

getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Arraymodule:engine/view/uielement~UIElement#getAncestors

Parameters

Returns

getAttribute( key ) → String | undefinedmodule:engine/view/uielement~UIElement#getAttribute

Parameters

Returns

getAttributeKeys() → Iterable.<String>module:engine/view/uielement~UIElement#getAttributeKeys

Returns

getAttributes() → Iterable.<*>module:engine/view/uielement~UIElement#getAttributes

Returns

getChild( index ) → Nodemodule:engine/view/uielement~UIElement#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/view/uielement~UIElement#getChildIndex

Parameters

Returns

getChildren() → Iterable.<Node>module:engine/view/uielement~UIElement#getChildren

Returns

getClassNames() → Iterable.<String>module:engine/view/uielement~UIElement#getClassNames

Returns

getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | nullmodule:engine/view/uielement~UIElement#getCommonAncestor

Parameters

Returns

getCustomProperties() → Iterable.<*>module:engine/view/uielement~UIElement#getCustomProperties

Returns

getCustomProperty( key ) → *module:engine/view/uielement~UIElement#getCustomProperty

Parameters

Returns

getFillerOffset() → nullmodule:engine/view/uielement~UIElement#getFillerOffset

Returns

getIdentity() → Stringmodule:engine/view/uielement~UIElement#getIdentity

Returns

getNormalizedStyle( property ) → Object | String | undefinedmodule:engine/view/uielement~UIElement#getNormalizedStyle

Parameters

Returns

getPath() → Array.<Number>module:engine/view/uielement~UIElement#getPath

Returns

getStyle( property ) → String | undefinedmodule:engine/view/uielement~UIElement#getStyle

Parameters

Returns

getStyleNames() → Iterable.<String>module:engine/view/uielement~UIElement#getStyleNames

Returns

hasAttribute( key ) → Booleanmodule:engine/view/uielement~UIElement#hasAttribute

Parameters

Returns

hasClass( className )module:engine/view/uielement~UIElement#hasClass

Parameters

hasStyle( property )module:engine/view/uielement~UIElement#hasStyle

Parameters

is( type ) → Booleanmodule:engine/view/uielement~UIElement#is

Parameters

Returns

isAfter( node ) → Booleanmodule:engine/view/uielement~UIElement#isAfter

`childCount : Number`

`document : Document`

`index : Number | null`

`isAllowedInsideAttributeElement : Boolean`

`isEmpty : Boolean`

`name : String`

`nextSibling : Node | null`

`parent : Element | DocumentFragment | null`

`previousSibling : Node | null`

`root : Node | DocumentFragment`

`_attrs : Map`

`_children : Array.<Node>`

`_classes : Set`

`_customProperties : Map`

`_isAllowedInsideAttributeElement : Boolean`

`_styles : StylesMap`

`constructor( document, name, [ attributes ], [ children ] )`

`findAncestor( patterns ) → Element | null`

`getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array`

`getAttribute( key ) → String | undefined`

`getAttributeKeys() → Iterable.<String>`

`getAttributes() → Iterable.<*>`

`getChild( index ) → Node`

`getChildIndex( node ) → Number`

`getChildren() → Iterable.<Node>`

`getClassNames() → Iterable.<String>`

`getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null`

`getCustomProperties() → Iterable.<*>`

`getCustomProperty( key ) → *`

`getFillerOffset() → null`

`getIdentity() → String`

`getNormalizedStyle( property ) → Object | String | undefined`

`getPath() → Array.<Number>`

`getStyle( property ) → String | undefined`

`getStyleNames() → Iterable.<String>`

`hasAttribute( key ) → Boolean`

`hasClass( className )`

`hasStyle( property )`

`is( type ) → Boolean`

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`isSimilar( otherElement ) → Boolean`

`render( domDocument ) → HTMLElement`

`toDomElement( domDocument ) → HTMLElement`

`toJSON() → Object`

`_addClass( className )`

`_appendChild( items ) → Number`

`_clone( [ deep ] ) → Element`

`_fireChange( type, node )`

`_insertChild( index, items ) → Number`

`_remove()`

`_removeAttribute( key ) → Boolean`

`_removeChildren( index, [ howMany ] ) → Array.<Node>`

`_removeClass( className )`

`_removeCustomProperty( key ) → Boolean`

`_removeStyle( property )`

`_setAttribute( key, value )`

`_setCustomProperty( key, value )`

`_setStyle( property, [ value ] )`