RawElement (engine/view)

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

class

Hierarchy

Node
- Element
  - RawElement

The raw element class.

The raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures in the editor content without, for instance, worrying about compatibility with other editor features. Raw elements are a perfect tool for integration with external frameworks and data sources.

Unlike UI elements, raw elements act like real editor content (similar to ContainerElement or EmptyElement), they are considered by the editor selection and they can work as widgets.

To create a new raw element, use the downcastWriter#createRawElement() 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.
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
_styles : StylesMap

protected inherited

Normalized styles.

See source
_unsafeAttributesToRender : Array.<String>

private readonly inherited

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 new instance of a raw element.

See source
Throws the view-rawelement-cannot-add CKEditorError when the children parameter is passed to inform that the usage of RawElement is incorrect (adding child nodes to RawElement is forbidden).

Parameters

document : Document

The document instance to which this element belongs.

name : String

A node name.

[ attrs ] : Object | Iterable

The collection of attributes.

[ children ] : Node | Iterable.<Node>

A list of nodes to be inserted into the created element.

Related:
- DowncastWriter#createRawElement
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 raw elements.

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

inherited

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

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( domElement, domConverter )
This allows rendering the children of a RawElement on the DOM level. This method is called by the DomConverter with the raw DOM element passed as an argument, leaving the number and shape of the children up to the integrator.

See source
This method must be defined for the raw element to work:
```
const myRawElement = downcastWriter.createRawElement( 'div' );

myRawElement.render = function( domElement, domConverter ) {
	domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
};
```
Parameters

domElement : HTMLElement

The native DOM element representing the raw view element.

domConverter : DomConverter

Instance of the DomConverter used to optimize the output.
shouldRenderUnsafeAttribute( attributeName ) → Boolean

inherited

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

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.

RawElement (engine/view)

Filtering

Properties

childCount : Numbermodule:engine/view/rawelement~RawElement#childCount

document : Documentmodule:engine/view/rawelement~RawElement#document

index : Number | nullmodule:engine/view/rawelement~RawElement#index

isEmpty : Booleanmodule:engine/view/rawelement~RawElement#isEmpty

name : Stringmodule:engine/view/rawelement~RawElement#name

nextSibling : Node | nullmodule:engine/view/rawelement~RawElement#nextSibling

parent : Element | DocumentFragment | nullmodule:engine/view/rawelement~RawElement#parent

previousSibling : Node | nullmodule:engine/view/rawelement~RawElement#previousSibling

root : Node | DocumentFragmentmodule:engine/view/rawelement~RawElement#root

_attrs : Mapmodule:engine/view/rawelement~RawElement#_attrs

_children : Array.<Node>module:engine/view/rawelement~RawElement#_children

_classes : Setmodule:engine/view/rawelement~RawElement#_classes

_customProperties : Mapmodule:engine/view/rawelement~RawElement#_customProperties

_styles : StylesMapmodule:engine/view/rawelement~RawElement#_styles

_unsafeAttributesToRender : Array.<String>module:engine/view/rawelement~RawElement#_unsafeAttributesToRender

Methods

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

Parameters

Related:

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

Parameters

Returns

Related:

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

Parameters

Returns

getAttribute( key ) → String | undefinedmodule:engine/view/rawelement~RawElement#getAttribute

Parameters

Returns

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

Returns

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

Returns

getChild( index ) → Nodemodule:engine/view/rawelement~RawElement#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/view/rawelement~RawElement#getChildIndex

Parameters

Returns

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

Returns

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

Returns

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

Parameters

Returns

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

Returns

getCustomProperty( key ) → *module:engine/view/rawelement~RawElement#getCustomProperty

Parameters

Returns

getFillerOffset() → nullmodule:engine/view/rawelement~RawElement#getFillerOffset

Returns

getIdentity() → Stringmodule:engine/view/rawelement~RawElement#getIdentity

Returns

getNormalizedStyle( property ) → Object | String | undefinedmodule:engine/view/rawelement~RawElement#getNormalizedStyle

Parameters

Returns

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

Returns

getStyle( property ) → String | undefinedmodule:engine/view/rawelement~RawElement#getStyle

Parameters

Returns

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

Parameters

Returns

hasAttribute( key ) → Booleanmodule:engine/view/rawelement~RawElement#hasAttribute

Parameters

Returns

hasClass( className )module:engine/view/rawelement~RawElement#hasClass

Parameters

hasStyle( property )module:engine/view/rawelement~RawElement#hasStyle

Parameters

is( type ) → Booleanmodule:engine/view/rawelement~RawElement#is

Parameters

Returns

isAfter( node ) → Booleanmodule:engine/view/rawelement~RawElement#isAfter

`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() → null`

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

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`isSimilar( otherElement ) → Boolean`

`render( domElement, domConverter )`

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