AttributeElement (engine/view)

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

class

Attribute elements are used to represent formatting elements in the view (think – <b>, <span style="font-size: 2em">, etc.). Most often they are created when downcasting model text attributes.

Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various types (container element, attribute element, empty element, etc) when developing a feature.

To create a new attribute element instance use the DowncastWriter#createAttributeElement() 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
id : String | Number

readonly

Element identifier. If set, it is used by isSimilar, and then two elements are considered similar if, and only if they have the same id.

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 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
priority : Number

readonly

Element priority. Decides in what order elements are wrapped by DowncastWriter.

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
_clonesGroup : Set.<AttributeElement> | null

protected

Keeps all the attribute elements that have the same ids and still exist in the view tree.

See source

This property is managed by DowncastWriter.
_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
_id : String | Number

protected

Element identifier. If set, it is used by isSimilar, and then two elements are considered similar if, and only if they have the same _id.

See source
_priority : Number

protected

Element priority. Decides in what order elements are wrapped by DowncastWriter.

See source
_styles : StylesMap

protected inherited

Normalized styles.

See source

Static properties

DEFAULT_PRIORITY : Number

static

Default attribute priority.

See source

Methods

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

protected
Creates an attribute element.

See source
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.

Related:
- DowncastWriter#createAttributeElement
- Element
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

*
getElementsWithSameId() → Set.<AttributeElement>

Returns all attribute elements that has the same id and are in the view tree (were not removed).

See source

Note: If this element has been removed from the tree, returned set will not include it.

Throws attribute-element-get-elements-with-same-id-no-id if this element has no id.

Returns

Set.<AttributeElement>

Set containing all the attribute elements with the same id that were added and not removed from the view tree.
getFillerOffset() → Number | null

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

See source

Returns

Number | null

Block filler offset or null if block filler is not needed.
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, [ name ] ) → Boolean`

Checks whether this object is of the given.

See source

attributeElement.is( 'attributeElement' ); // -> true
attributeElement.is( 'element' ); // -> true
attributeElement.is( 'node' ); // -> true
attributeElement.is( 'view:attributeElement' ); // -> true
attributeElement.is( 'view:element' ); // -> true
attributeElement.is( 'view:node' ); // -> true

attributeElement.is( 'model:element' ); // -> false
attributeElement.is( 'documentFragment' ); // -> false

Assuming that the object being checked is an attribute element, you can also check its name:

attributeElement.is( 'b' ); // -> true if this is a bold element
attributeElement.is( 'attributeElement', 'b' ); // -> same as above
text.is( 'b' ); -> false

Check the entire list of view objects which implement the is() method.

Parameters

type : String: Type to check when name parameter is present. Otherwise, it acts like the name parameter.
[ 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.

See source
If none of elements has set id, then both elements should have the same name, attributes and priority to be considered as similar. Two similar elements can contain different set of children nodes.

If at least one element has id set, then both elements have to have the same id value to be considered similar.

Similarity is important for DowncastWriter. For example:
- two following similar elements can be merged together into one, longer element,
- unwrap checks similarity of passed element and processed element to decide whether processed element should be unwrapped,
- etc.
Parameters

otherElement : Element

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

protected

Clones provided element with priority.

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.

Returns

AttributeElement

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

AttributeElement (engine/view)

Filtering

Properties

childCount : Numbermodule:engine/view/attributeelement~AttributeElement#childCount

document : Documentmodule:engine/view/attributeelement~AttributeElement#document

id : String | Numbermodule:engine/view/attributeelement~AttributeElement#id

index : Number | nullmodule:engine/view/attributeelement~AttributeElement#index

isEmpty : Booleanmodule:engine/view/attributeelement~AttributeElement#isEmpty

name : Stringmodule:engine/view/attributeelement~AttributeElement#name

nextSibling : Node | nullmodule:engine/view/attributeelement~AttributeElement#nextSibling

parent : Element | DocumentFragment | nullmodule:engine/view/attributeelement~AttributeElement#parent

previousSibling : Node | nullmodule:engine/view/attributeelement~AttributeElement#previousSibling

priority : Numbermodule:engine/view/attributeelement~AttributeElement#priority

root : Node | DocumentFragmentmodule:engine/view/attributeelement~AttributeElement#root

_attrs : Mapmodule:engine/view/attributeelement~AttributeElement#_attrs

_children : Array.<Node>module:engine/view/attributeelement~AttributeElement#_children

_classes : Setmodule:engine/view/attributeelement~AttributeElement#_classes

_clonesGroup : Set.<AttributeElement> | nullmodule:engine/view/attributeelement~AttributeElement#_clonesGroup

_customProperties : Mapmodule:engine/view/attributeelement~AttributeElement#_customProperties

_id : String | Numbermodule:engine/view/attributeelement~AttributeElement#_id

_priority : Numbermodule:engine/view/attributeelement~AttributeElement#_priority

_styles : StylesMapmodule:engine/view/attributeelement~AttributeElement#_styles

Static properties

DEFAULT_PRIORITY : Numbermodule:engine/view/attributeelement~AttributeElement.DEFAULT_PRIORITY

Methods

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

Parameters

Related:

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

Parameters

Returns

Related:

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

Parameters

Returns

getAttribute( key ) → String | undefinedmodule:engine/view/attributeelement~AttributeElement#getAttribute

Parameters

Returns

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

Returns

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

Returns

getChild( index ) → Nodemodule:engine/view/attributeelement~AttributeElement#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/view/attributeelement~AttributeElement#getChildIndex

Parameters

Returns

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

Returns

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

Returns

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

Parameters

Returns

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

Returns

getCustomProperty( key ) → *module:engine/view/attributeelement~AttributeElement#getCustomProperty

Parameters

Returns

getElementsWithSameId() → Set.<AttributeElement>module:engine/view/attributeelement~AttributeElement#getElementsWithSameId

Returns

getFillerOffset() → Number | nullmodule:engine/view/attributeelement~AttributeElement#getFillerOffset

Returns

getIdentity() → Stringmodule:engine/view/attributeelement~AttributeElement#getIdentity

Returns

getNormalizedStyle( property ) → Object | String | undefinedmodule:engine/view/attributeelement~AttributeElement#getNormalizedStyle

Parameters

Returns

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

Returns

getStyle( property ) → String | undefinedmodule:engine/view/attributeelement~AttributeElement#getStyle

Parameters

Returns

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

Returns

hasAttribute( key ) → Booleanmodule:engine/view/attributeelement~AttributeElement#hasAttribute

Parameters

Returns

hasClass( className )module:engine/view/attributeelement~AttributeElement#hasClass

`childCount : Number`

`document : Document`

`id : String | Number`

`index : Number | null`

`isEmpty : Boolean`

`name : String`

`nextSibling : Node | null`

`parent : Element | DocumentFragment | null`

`previousSibling : Node | null`

`priority : Number`

`root : Node | DocumentFragment`

`_attrs : Map`

`_children : Array.<Node>`

`_classes : Set`

`_clonesGroup : Set.<AttributeElement> | null`

`_customProperties : Map`

`_id : String | Number`

`_priority : Number`

`_styles : StylesMap`

`DEFAULT_PRIORITY : Number`

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

`getElementsWithSameId() → Set.<AttributeElement>`

`getFillerOffset() → Number | 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, [ name ] ) → Boolean`

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`isSimilar( otherElement ) → Boolean`

`toJSON() → Object`

`_addClass( className )`

`_appendChild( items ) → Number`

`_clone( deep ) → AttributeElement`

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