CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

UIElement (engine/view)

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

class
See source

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

Properties

  • readonly inherited

    childCount : number

    See source

    Number of element's children.

  • readonly inherited

    document : Document

    See source

    The document instance to which this node belongs.

  • readonly inherited

    index : null | number

    See source

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

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

  • readonly inherited

    isEmpty : boolean

    See source

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

  • readonly inherited

    name : string

    See source

    Name of the element.

  • readonly inherited

    nextSibling : null | Node

    See source

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

  • readonly inherited

    parent : null | Element | DocumentFragment

    See source

    Parent element. Null by default. Set by _insertChild.

  • readonly inherited

    previousSibling : null | Node

    See source

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

  • readonly inherited

    root : Element | DocumentFragment

    See source

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

  • internal readonly inherited

    _unsafeAttributesToRender : Array<string>

    See source

    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.

    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

  • internal

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

    See source

    Creates new instance of UIElement.

    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.

    [ attrs ] : ElementAttributes

    Collection of attributes.

    [ children ] : Node | Iterable<Node>

    A list of nodes to be inserted into created element.

    Related:

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • inherited

    findAncestor( patterns ) → null | Element

    See source

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

    Parameters

    patterns : Array<MatcherPattern | ( Element ) => boolean>

    Patterns used to match correct ancestor. See Matcher.

    Returns

    null | Element

    Found element or null if no matching ancestor was found.

    Related:

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • inherited

    getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>

    See source

    Returns ancestors array of this node.

    Parameters

    options : object

    Options object.

    Properties
    [ options.includeSelf ] : boolean

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

    [ 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 {}

    Returns

    Array<Node | DocumentFragment>

    Array with ancestors.

  • inherited

    getAttribute( key ) → undefined | string

    See source

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

    Parameters

    key : string

    Attribute key.

    Returns

    undefined | string

    Attribute value.

  • inherited

    getAttributeKeys() → IterableIterator<string>

    See source

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

    Returns

    IterableIterator<string>

    Keys for attributes.

  • inherited

    getAttributes() → IterableIterator<tuple>

    See source

    Returns iterator that iterates over this element's attributes.

    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

    IterableIterator<tuple>

  • inherited

    getChild( index ) → undefined | Node

    See source

    Gets child at the given index.

    Parameters

    index : number

    Index of child.

    Returns

    undefined | Node

    Child node.

  • inherited

    getChildIndex( node ) → number

    See source

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

    Parameters

    node : Node

    Child node.

    Returns

    number

    Index of the child node.

  • inherited

    getChildren() → IterableIterator<Node>

    See source

    Gets child nodes iterator.

    Returns

    IterableIterator<Node>

    Child nodes iterator.

  • inherited

    getClassNames() → Iterable<string>

    See source

    Returns iterator that contains all class names.

    Returns

    Iterable<string>

  • inherited

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

    See source

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

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

    Returns

    null | Element | DocumentFragment

  • inherited

    getCustomProperties() → IterableIterator<tuple>

    See source

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

    Returns

    IterableIterator<tuple>

  • inherited

    getCustomProperty( key ) → unknown

    See source

    Returns the custom property value for the given key.

    Parameters

    key : string | symbol

    Returns

    unknown

  • inherited

    getFillerOffset() → null | number

    See source

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

    Returns

    null | number

  • inherited

    getIdentity() → string

    See source

    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:

    '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

  • inherited

    getNormalizedStyle( property ) → StyleValue

    See source

    Returns a normalized style object or single style value.

    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

    StyleValue

  • inherited

    getPath() → Array<number>

    See source

    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.

    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.

  • inherited

    getStyle( property ) → undefined | string

    See source

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

    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

    undefined | string

  • inherited

    getStyleNames( [ expand ] ) → Iterable<string>

    See source

    Returns iterator that contains all style names.

    Parameters

    [ expand ] : boolean

    Expand shorthand style properties and return all equivalent style representations.

    Returns

    Iterable<string>

  • inherited

    hasAttribute( key ) → boolean

    See source

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

    Parameters

    key : string

    Attribute key.

    Returns

    boolean

    true if attribute with the specified key exists in the element, false otherwise.

  • inherited

    hasClass( className ) → boolean

    See source

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

    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 : Array<string>

    Returns

    boolean

  • inherited

    hasStyle( property ) → boolean

    See source

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

    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 : Array<string>

    Returns

    boolean

  • inherited

    is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

    Checks whether this object is of type Element or its subclass.

    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

    Parameters

    type : 'element' | 'view:element'

    Returns

    this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • inherited

    is( type ) → this is AttributeElement

    See source

    Checks whether this object is of type AttributeElement.

    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( 'element', 'b' ); // -> true if this is a bold element
attributeElement.is( 'attributeElement', 'b' ); // -> same as above
text.is( 'element', 'b' ); -> false

    Parameters

    type : 'attributeElement' | 'view:attributeElement'

    Returns

    this is AttributeElement

  • inherited

    is( type ) → this is EmptyElement

    See source

    Checks whether this object is of type EmptyElement.

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

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

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

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

    Parameters

    type : 'emptyElement' | 'view:emptyElement'

    Returns

    this is EmptyElement

  • inherited

    is( type ) → this is EditableElement | RootEditableElement

    See source

    Checks whether this object is of type EditableElement or its subclass.

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

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

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

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

    Parameters

    type : 'editableElement' | 'view:editableElement'

    Returns

    this is EditableElement | RootEditableElement

  • inherited

    is( type ) → this is ContainerElement | EditableElement | RootEditableElement

    See source

    Checks whether this object is of type ContainerElement or its subclass.

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

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

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

    containerElement.is( 'element', 'div' ); // -> true if this is a div container element
containerElement.is( 'contaienrElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

    Parameters

    type : 'containerElement' | 'view:containerElement'

    Returns

    this is ContainerElement | EditableElement | RootEditableElement

  • inherited

    is( type ) → this is Text

    See source

    Checks whether this object is of type Text.

    text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'view:$text' ); // -> true
text.is( 'view:node' ); // -> true

text.is( 'model:$text' ); // -> false
text.is( 'element' ); // -> false
text.is( 'range' ); // -> false

    Parameters

    type : '$text' | 'view:$text'

    Returns

    this is Text

  • inherited

    is( type ) → this is Position

    See source

    Checks whether this object is of type Position.

    position.is( 'position' ); // -> true
position.is( 'view:position' ); // -> true

position.is( 'model:position' ); // -> false
position.is( 'element' ); // -> false
position.is( 'range' ); // -> false

    Parameters

    type : 'position' | 'view:position'

    Returns

    this is Position

  • inherited

    is( type ) → this is TextProxy

    See source

    Checks whether this object is of type TextProxy.

    textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'view:$textProxy' ); // -> true

textProxy.is( 'model:$textProxy' ); // -> false
textProxy.is( 'element' ); // -> false
textProxy.is( 'range' ); // -> false

    Note: Until version 20.0.0 this method wasn't accepting '$textProxy' type. The legacy 'textProxy' type is still accepted for backward compatibility.

    Parameters

    type : '$textProxy' | 'view:$textProxy'

    Returns

    this is TextProxy

  • inherited

    is( type ) → this is DocumentFragment

    See source

    hecks whether this object is of type DocumentFragment.

    docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'view:documentFragment' ); // -> true

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

    Parameters

    type : 'documentFragment' | 'view:documentFragment'

    Returns

    this is DocumentFragment

  • inherited

    is( type ) → this is UIElement

    See source

    Checks whether this object is of type UIElement.

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

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

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

    uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
uiElement.is( 'uiElement', 'span' ); // -> same as above
text.is( 'element', 'span' ); -> false

    Parameters

    type : 'uiElement' | 'view:uiElement'

    Returns

    this is UIElement

  • inherited

    is( type ) → this is RootEditableElement

    See source

    Checks whether this object is of type RootEditableElement.

    rootEditableElement.is( 'rootElement' ); // -> true
rootEditableElement.is( 'editableElement' ); // -> true
rootEditableElement.is( 'element' ); // -> true
rootEditableElement.is( 'node' ); // -> true
rootEditableElement.is( 'view:editableElement' ); // -> true
rootEditableElement.is( 'view:element' ); // -> true
rootEditableElement.is( 'view:node' ); // -> true

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

    Assuming that the object being checked is a root editable element, you can also check its name:

    rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element
rootEditableElement.is( 'rootElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false

    Parameters

    type : 'rootElement' | 'view:rootElement'

    Returns

    this is RootEditableElement

  • inherited

    is( type ) → this is RawElement

    See source

    Checks whether this object is of type RawElement.

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

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

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

    rawElement.is( 'img' ); // -> true if this is an img element
rawElement.is( 'rawElement', 'img' ); // -> same as above
text.is( 'img' ); -> false

    Parameters

    type : 'rawElement' | 'view:rawElement'

    Returns

    this is RawElement

  • inherited

    is( type ) → this is Range

    See source

    Checks whether this object is of type Range.

    range.is( 'range' ); // -> true
range.is( 'view:range' ); // -> true

range.is( 'model:range' ); // -> false
range.is( 'element' ); // -> false
range.is( 'selection' ); // -> false

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is Range

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type AttributeElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'attributeElement' | 'view:attributeElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type RawElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rawElement' | 'view:rawElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type UIElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'uiElement' | 'view:uiElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type RootEditableElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'view:rootElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type EmptyElement has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'emptyElement' | 'view:emptyElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type EditableElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'editableElement' | 'view:editableElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type ContainerElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'containerElement' | 'view:containerElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type Element or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'view:element'
    name : N

    Returns

    boolean

  • inherited

    is( type ) → this is DocumentSelection

    See source

    Checks whether this object is of type DocumentSelection.

    `docSelection.is( 'selection' ); // -> true
docSelection.is( 'documentSelection' ); // -> true
docSelection.is( 'view:selection' ); // -> true
docSelection.is( 'view:documentSelection' ); // -> true

docSelection.is( 'model:documentSelection' ); // -> false
docSelection.is( 'element' ); // -> false
docSelection.is( 'node' ); // -> false

    Parameters

    type : 'documentSelection' | 'view:documentSelection'

    Returns

    this is DocumentSelection

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether this object is of type Selection or DocumentSelection.

    selection.is( 'selection' ); // -> true
selection.is( 'view:selection' ); // -> true

selection.is( 'model:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'range' ); // -> false

    Parameters

    type : 'selection' | 'view:selection'

    Returns

    this is Selection | DocumentSelection

  • inherited

    is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

    Checks whether this object is of type Node or its subclass.

    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

    Parameters

    type : 'node' | 'view:node'

    Returns

    this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • inherited

    isAfter( node ) → boolean

    See source

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean

  • inherited

    isAttached() → boolean

    See source

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

    Returns

    boolean

  • inherited

    isBefore( node ) → boolean

    See source

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean

  • inherited

    isSimilar( otherElement ) → boolean

    See source

    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.

    Parameters

    otherElement : Item

    Returns

    boolean

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

    // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired.

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • render( domDocument, domConverter ) → HTMLElement

    See source

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

    const myUIElement = downcastWriter.createUIElement( 'span' );
myUIElement.render = function( domDocument, domConverter ) {
	const domElement = this.toDomElement( domDocument );

	domConverter.setContentOf( domElement, '<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
    domConverter : DomConverter

    Instance of the DomConverter used to optimize the output.

    Returns

    HTMLElement

  • inherited

    shouldRenderUnsafeAttribute( attributeName ) → boolean

    See source

    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.

    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

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

    Stops delegating events. It can be used at different levels:

    • To stop delegating all events.
    • To stop delegating a specific event to all emitters.
    • To stop delegating a specific event to a specific emitter.

    Parameters

    [ event ] : string

    The name of the event to stop delegating. If omitted, stops it all delegations.

    [ emitter ] : Emitter

    (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

    Stops listening for events. It can be used at different levels:

    • To stop listening to a specific callback.
    • To stop listening to a specific event.
    • To stop listening to all events fired by a specific object.
    • To stop listening to all events fired by all objects.

    Parameters

    [ emitter ] : Emitter

    The object to stop listening to. If omitted, stops it for all objects.

    [ event ] : string

    (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

    [ callback ] : Function

    (Requires the event) The function to be removed from the call list for the given event.

    Returns

    void

  • toDomElement( domDocument ) → HTMLElement

    See source

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

    Parameters

    domDocument : Document

    Returns

    HTMLElement

  • inherited

    toJSON() → unknown

    See source

    Custom toJSON method to solve child-parent circular dependencies.

    Returns

    unknown

    Clone of this object with the parent property removed.

  • internal inherited

    _addClass( className ) → void

    See source

    Adds specified class.

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

    Parameters

    className : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal inherited

    _appendChild( items ) → number

    See source

    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.

    Parameters

    items : string | Item | Iterable<string | Item>

    Items to be inserted.

    Returns

    number

    Number of appended nodes.

    Fires

    Related:

  • internal inherited

    _clone( deep ) → UIElement

    See source

    Clones provided element.

    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

    UIElement

    Clone of this element.

  • internal inherited

    _fireChange( type, node ) → void

    See source

    Parameters

    type : ChangeType

    Type of the change.

    node : Node

    Changed node.

    Returns

    void

    Fires

  • internal

    _insertChild( index, items ) → number

    See source

    Overrides _insertChild method. Throws CKEditorError view-uielement-cannot-add to prevent adding any child nodes to UIElement.

    Parameters

    index : number
    items : Item | Iterable<Item>

    Returns

    number

  • internal inherited

    _remove() → void

    See source

    Removes node from parent.

    Returns

    void

  • internal inherited

    _removeAttribute( key ) → boolean

    See source

    Removes attribute from the element.

    Parameters

    key : string

    Attribute key.

    Returns

    boolean

    Returns true if an attribute existed and has been removed.

    Fires

    Related:

  • internal inherited

    _removeChildren( index, howMany ) → Array<Node>

    See source

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

    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

    Related:

  • internal inherited

    _removeClass( className ) → void

    See source

    Removes specified class.

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

    Parameters

    className : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal inherited

    _removeCustomProperty( key ) → boolean

    See source

    Removes the custom property stored under the given key.

    Parameters

    key : string | symbol

    Returns

    boolean

    Returns true if property was removed.

    Related:

  • internal inherited

    _removeStyle( property ) → void

    See source

    Removes specified style.

    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 : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal inherited

    _setAttribute( key, value ) → void

    See source

    Adds or overwrite attribute with a specified key and value.

    Parameters

    key : string

    Attribute key.

    value : unknown

    Attribute value.

    Returns

    void

    Fires

    Related:

  • internal inherited

    _setCustomProperty( key, value ) → void

    See source

    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.

    Parameters

    key : string | symbol
    value : unknown

    Returns

    void

    Related:

  • internal inherited

    _setStyle( properties ) → void

    See source

    Adds style to the element.

    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

    properties : Record<string, string>

    Object with key - value pairs.

    Returns

    void

    Fires

    Related:

  • internal inherited

    _setStyle( property, value ) → void

    See source

    Adds style to the element.

    element._setStyle( 'color', 'red' );

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

    Parameters

    property : string

    Property name.

    value : string

    Value to set.

    Returns

    void

    Fires

    Related:

Events

  • inherited

    change( eventInfo, changedNode )

    See source

    Fired when list of elements children, attributes or data changes.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node

  • inherited

    change:attributes( eventInfo, changedNode )

    See source

    Fired when list of elements children, attributes or data changes.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node

  • inherited

    change:children( eventInfo, changedNode )

    See source

    Fired when list of elements children, attributes or data changes.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node

  • inherited

    change:text( eventInfo, changedNode )

    See source

    Fired when list of elements children, attributes or data changes.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node