Element (engine/view)

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

class

View element.

The editing engine does not define a fixed semantics of its elements (it is "DTD-free"). This is why the type of the Element need to be defined by the feature developer. When creating an element you should use one of the following methods:

downcastWriter#createContainerElement() in order to create a ContainerElement,
downcastWriter#createAttributeElement() in order to create a AttributeElement,
downcastWriter#createEmptyElement() in order to create a EmptyElement.
downcastWriter#createUIElement() in order to create a UIElement.
downcastWriter#createEditableElement() in order to create a EditableElement.

Note that for view elements which are not created from the model, like elements from mutations, paste or data.set it is not possible to define the type of the element. In such cases the UpcastWriter#createElement() method should be used to create generic view elements.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

childCount : Number

readonly

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.
isEmpty : Boolean

readonly

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

See source
name : String

readonly

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

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

See source
_children : Array.<Node>

protected

Array of child nodes.

See source
_classes : Set

protected

Set of classes associated with element instance.

See source
_customProperties : Map

protected

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

See source
_styles : StylesMap

protected

Normalized styles.

See source
_unsafeAttributesToRender : Array.<String>

private readonly

A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms implemented in the DomConverter (for instance, shouldRenderAttribute) would filter them out.

See source

These attributes can be specified as an option when the element is created by the DowncastWriter. To check whether an unsafe an attribute should be permitted, use the shouldRenderUnsafeAttribute method.

Methods

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

protected
Creates a view element.

See source
Attributes can be passed in various formats:
```
new Element( viewDocument, 'div', { class: 'editor', contentEditable: 'true' } ); // object
new Element( viewDocument, 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
new Element( viewDocument, 'div', mapOfAttributes ); // map
```
Parameters

document : Document

The document instance to which this element belongs.

name : String

Node name.

[ attrs ] : Object | Iterable

Collection of attributes.

[ children ] : Node | Iterable.<Node>

A list of nodes to be inserted into created element.
findAncestor( patterns ) → Element | null
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

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>

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

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

Gets child at the given index.

See source

Parameters

index : Number

Index of child.

Returns

Node

Child node.
getChildIndex( node ) → Number

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>

Gets child nodes iterator.

See source

Returns

Iterable.<Node>

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

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

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 ) → *

Returns the custom property value for the given key.

See source

Parameters

key : String | Symbol

Returns

*
getFillerOffset()

Returns block filler offset or null if block filler is not needed.

See source

`getIdentity() → String`

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
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
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( [ expand ] ) → Iterable.<String>

Returns iterator that contains all style names.

See source

Parameters

[ expand ] : Boolean

Expand shorthand style properties and return all equivalent style representations.

Defaults to false

Returns

Iterable.<String>
hasAttribute( key ) → Boolean

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 )
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 )
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, [ name ] ) → Boolean
Checks whether this object is of the given.

See source
```
element.is( 'element' ); // -> true
element.is( 'node' ); // -> true
element.is( 'view:element' ); // -> true
element.is( 'view:node' ); // -> true

element.is( 'model:element' ); // -> false
element.is( 'documentSelection' ); // -> false
```
Assuming that the object being checked is an element, you can also check its name:
```
element.is( 'element', 'img' ); // -> true if this is an <img> element
text.is( 'element', 'img' ); -> false
```
Check the entire list of view objects which implement the is() method.

Parameters

type : String

Type to check.

[ name ] : String

Element name.

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

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
shouldRenderUnsafeAttribute( attributeName ) → Boolean

Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms like shouldRenderAttribute say it should not.

See source

Unsafe attribute names can be specified when creating an element via DowncastWriter.

Parameters

attributeName : String

The name of the attribute to be checked.

Returns

Boolean
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
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
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

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

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

Element (engine/view)

Filtering

Properties

childCount : Numbermodule:engine/view/element~Element#childCount

document : Documentmodule:engine/view/element~Element#document

index : Number | nullmodule:engine/view/element~Element#index

isEmpty : Booleanmodule:engine/view/element~Element#isEmpty

name : Stringmodule:engine/view/element~Element#name

nextSibling : Node | nullmodule:engine/view/element~Element#nextSibling

parent : Element | DocumentFragment | nullmodule:engine/view/element~Element#parent

previousSibling : Node | nullmodule:engine/view/element~Element#previousSibling

root : Node | DocumentFragmentmodule:engine/view/element~Element#root

_attrs : Mapmodule:engine/view/element~Element#_attrs

_children : Array.<Node>module:engine/view/element~Element#_children

_classes : Setmodule:engine/view/element~Element#_classes

_customProperties : Mapmodule:engine/view/element~Element#_customProperties

_styles : StylesMapmodule:engine/view/element~Element#_styles

_unsafeAttributesToRender : Array.<String>module:engine/view/element~Element#_unsafeAttributesToRender

Methods

constructor( document, name, [ attrs ], [ children ] )module:engine/view/element~Element#constructor

Parameters

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

Parameters

Returns

Related:

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

Parameters

Returns

getAttribute( key ) → String | undefinedmodule:engine/view/element~Element#getAttribute

Parameters

Returns

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

Returns

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

Returns

getChild( index ) → Nodemodule:engine/view/element~Element#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/view/element~Element#getChildIndex

Parameters

Returns

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

Returns

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

Returns

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

Parameters

Returns

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

Returns

getCustomProperty( key ) → *module:engine/view/element~Element#getCustomProperty

Parameters

Returns

getFillerOffset()module:engine/view/element~Element#getFillerOffset

getIdentity() → Stringmodule:engine/view/element~Element#getIdentity

Returns

getNormalizedStyle( property ) → Object | String | undefinedmodule:engine/view/element~Element#getNormalizedStyle

Parameters

Returns

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

Returns

getStyle( property ) → String | undefinedmodule:engine/view/element~Element#getStyle

Parameters

Returns

getStyleNames( [ expand ] ) → Iterable.<String>module:engine/view/element~Element#getStyleNames

Parameters

Returns

hasAttribute( key ) → Booleanmodule:engine/view/element~Element#hasAttribute

Parameters

Returns

hasClass( className )module:engine/view/element~Element#hasClass

Parameters

hasStyle( property )module:engine/view/element~Element#hasStyle

Parameters

is( type, [ name ] ) → Booleanmodule:engine/view/element~Element#is

Parameters

Returns

isAfter( node ) → Booleanmodule:engine/view/element~Element#isAfter

Parameters

Returns

`childCount : Number`

`document : Document`

`index : Number | null`

`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`

`_styles : StylesMap`

`_unsafeAttributesToRender : Array.<String>`

`constructor( document, name, [ attrs ], [ 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()`

`getIdentity() → String`

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

`getPath() → Array.<Number>`

`getStyle( property ) → String | undefined`

`getStyleNames( [ expand ] ) → Iterable.<String>`

`hasAttribute( key ) → Boolean`

`hasClass( className )`

`hasStyle( property )`

`is( type, [ name ] ) → Boolean`

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`isSimilar( otherElement ) → Boolean`

`shouldRenderUnsafeAttribute( attributeName ) → Boolean`

`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 ] )`

`change( eventInfo )`