Home/CKEditor 4/API

CKEDITOR.dom.node

class

Hierarchy

domObject
- node

Mixes

event

Subclasses

comment
editable
element
nestedEditable
text

See source

Base class for classes representing DOM nodes. This constructor may return an instance of a class that inherits from this class, like CKEDITOR.dom.element or CKEDITOR.dom.text.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

readonly inherited
$ : Object
See source
The native DOM object represented by this class instance.
```
var element = new CKEDITOR.dom.element( 'span' );
alert( element.$.nodeType ); // '1'
```

Static properties

mixed static
useCapture : Boolean

See source

Methods

inherited
constructor( nativeDomObject ) → domObject

See source
Creates a domObject class instance.

Parameters

nativeDomObject : Object

A native DOM object.

Returns

domObject
appendTo( element ) → element
See source
Makes this node a child of another element.
```
var p = new CKEDITOR.dom.element( 'p' );
var strong = new CKEDITOR.dom.element( 'strong' );
strong.appendTo( p );

// Result: '<p><strong></strong></p>'.
```
Parameters

element : element

The target element to which this node will be appended.

Returns

element

The target element.
inherited
capture()

See source
Register event handler under the capturing stage on supported target.
inherited
clearCustomData()

See source
Removes any data stored in this object. To avoid memory leaks we must assure that there are no references left after the object is no longer needed.
clone( [ includeChildren ], [ cloneId ] ) → node

See source
Clones this node.

Note: Values set by {setCustomData} will not be available in the clone.

Parameters

[ includeChildren ] : Boolean

If true then all node's children will be cloned recursively.

Defaults to false

[ cloneId ] : Boolean

Whether ID attributes should be cloned, too.

Defaults to false

Returns

node

Clone of this node.
inherited
define( name, meta )

See source
Predefine some intrinsic properties on a specific event name.

Parameters

name : String

The event name

meta : Object
inherited
equals( object ) → Boolean
See source
Determines whether the specified object is equal to the current object.
```
var doc = new CKEDITOR.dom.document( document );
alert( doc.equals( CKEDITOR.document ) );   // true
alert( doc == CKEDITOR.document );          // false
```
Parameters

object : Object

The object to compare with the current object.

Returns

Boolean

true if the object is equal.
inherited
fire( eventName, [ data ], [ editor ] ) → Boolean | Object
See source
Fires an specific event in the object. All registered listeners are called at this point.
```
someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );             // Both listeners are called.

someObject.on( 'someEvent', function( event ) {
    alert( event.data );                    // 'Example'
} );
someObject.fire( 'someEvent', 'Example' );
```
Parameters

eventName : String

The event name to fire.

[ data ] : Object

Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

[ editor ] : editor

The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

Returns

Boolean | Object

A boolean indicating that the event is to be canceled, or data returned by one of the listeners.
inherited
fireOnce( eventName, [ data ], [ editor ] ) → Boolean | Object
See source
Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.
```
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );         // Above listener called.
someObject.fireOnce( 'someEvent' );     // Above listener called.
someObject.fire( 'someEvent' );         // No listeners called.
```
Parameters

eventName : String

The event name to fire.

[ data ] : Object

Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

[ editor ] : editor

The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

Returns

Boolean | Object

A booloan indicating that the event is to be canceled, or data returned by one of the listeners.
getAddress( [ normalized ] ) → Array

See source
Retrieves a uniquely identifiable tree address for this node. The tree address returned is an array of integers, with each integer indicating a child index of a DOM node, starting from document.documentElement.

For example, assuming <body> is the second child of <html> (<head> being the first), and we would like to address the third child under the fourth child of <body>, the tree address returned would be: [1, 3, 2].

The tree address cannot be used for finding back the DOM tree node once the DOM tree structure has been modified.

Parameters

[ normalized ] : Boolean

See getIndex.

Defaults to false

Returns

Array

The address.

since 3.6.1
`getAscendant( query, [ includeSelf ] ) → node`

See source

Gets the closest ancestor node of this node, specified by its name or using an evaluator function.

// Suppose we have the following HTML structure:
// <div id="outer"><div id="inner"><p><b>Some text</b></p></div></div>
// If node == <b>
ascendant = node.getAscendant( 'div' );             // ascendant == <div id="inner">
ascendant = node.getAscendant( 'b' );               // ascendant == null
ascendant = node.getAscendant( 'b', true );         // ascendant == <b>
ascendant = node.getAscendant( { div:1, p:1 } );    // Searches for the first 'div' or 'p': ascendant == <div id="inner">

// Using custom evaluator:
ascendant = node.getAscendant( function( el ) {
    return el.getId() == 'inner';
} );
// ascendant == <div id="inner">

Parameters

query : String | Function | Object: The name of the ancestor node to search or an object with the node names to search for or an evaluator function.
[ includeSelf ] : Boolean: Whether to include the current node in the search.

Returns

node: The located ancestor node or null if not found.

getCommonAncestor( node )

See source

Parameters

node : Object
inherited
getCustomData( key ) → Object
See source
Gets the value set to a data slot in this object.
```
var element = new CKEDITOR.dom.element( 'span' );
alert( element.getCustomData( 'hasCustomData' ) );      // e.g. 'true'
alert( element.getCustomData( 'nonExistingKey' ) );     // null
```
Parameters

key : String

The key used to identify the data slot.

Returns

Object

This value set to the data slot.
getDocument() → document
See source
Gets the document containing this element.
```
var element = CKEDITOR.document.getById( 'example' );
alert( element.getDocument().equals( CKEDITOR.document ) ); // true
```
Returns

document

The document.
getIndex( normalized ) → Number
See source
Gets the index of a node in an array of its parent.childNodes. Returns -1 if a node does not have a parent or when the normalized argument is set to true and the text node is empty and will be removed during the normalization.

Let us assume having the following childNodes array:
```
[ emptyText, element1, text, text, element2, emptyText2 ]

emptyText.getIndex()            // 0
emptyText.getIndex( true )      // -1
element1.getIndex();            // 1
element1.getIndex( true );      // 0
element2.getIndex();            // 4
element2.getIndex( true );      // 2
emptyText2.getIndex();          // 5
emptyText2.getIndex( true );    // -1
```
Parameters

normalized : Boolean

When true, adjacent text nodes are merged and empty text nodes are removed.

Returns

Number

Index of a node or -1 if a node does not have a parent or is removed during the normalization.
getNext( [ evaluator ] ) → node
See source
Gets the node that follows this element in its parent's child list.
```
var element = CKEDITOR.dom.element.createFromHtml( '<div><b>Example</b><i>next</i></div>' );
var last = element.getFirst().getNext();
alert( last.getName() ); // 'i'
```
Parameters

[ evaluator ] : Function

Filtering the result node.

Returns

node

The next node or null if not available.
getNextSourceNode( startFromSibling, nodeType, guard )

See source

Parameters

startFromSibling : Object

nodeType : Object

guard : Object
getParent( [ allowFragmentParent ] ) → element
See source
Gets the parent element for this node.
```
var node = editor.document.getBody().getFirst();
var parent = node.getParent();
alert( parent.getName() ); // 'body'
```
Parameters

[ allowFragmentParent ] : Boolean

Consider also parent node that is of fragment type CKEDITOR.NODE_DOCUMENT_FRAGMENT.

Defaults to false

Returns

element

The parent element.
getParents( [ closerFirst ] ) → Array
See source
Returns an array containing node parents and the node itself. By default nodes are in descending order.
```
// Assuming that body has paragraph as the first child.
var node = editor.document.getBody().getFirst();
var parents = node.getParents();
alert( parents[ 0 ].getName() + ',' + parents[ 2 ].getName() ); // 'html,p'
```
Parameters

[ closerFirst ] : Boolean

Determines the order of returned nodes.

Defaults to false

Returns

Array

Returns an array of CKEDITOR.dom.node.
getPosition( otherNode ) → Number

See source
Determines the position relation between this node and the given CKEDITOR.dom.node in the document. This node can be preceding (CKEDITOR.POSITION_PRECEDING) or following (CKEDITOR.POSITION_FOLLOWING) the given node. This node can also contain (CKEDITOR.POSITION_CONTAINS) or be contained by (CKEDITOR.POSITION_IS_CONTAINED) the given node. The function returns a bitmask of constants listed above or CKEDITOR.POSITION_IDENTICAL if the given node is the same as this node.

Parameters

otherNode : node

A node to check relation with.

Returns

Number

Position relation between this node and given node.
getPrevious( [ evaluator ] ) → node
See source
Gets the node that preceeds this element in its parent's child list.
```
var element = CKEDITOR.dom.element.createFromHtml( '<div><i>prev</i><b>Example</b></div>' );
var first = element.getLast().getPrev();
alert( first.getName() ); // 'i'
```
Parameters

[ evaluator ] : Function

Filtering the result node.

Returns

node

The previous node or null if not available.
getPreviousSourceNode( startFromSibling, nodeType, guard )

See source

Parameters

startFromSibling : Object

nodeType : Object

guard : Object

inherited
`getPrivate() → Object`

See source

Gets the private _ object which is bound to the native DOM object using getCustomData.

var elementA = new CKEDITOR.dom.element( nativeElement );
elementA.getPrivate().value = 1;
...
var elementB = new CKEDITOR.dom.element( nativeElement );
elementB.getPrivate().value; // 1

Returns

Object: The private object.

inherited
getUniqueId() → Number

See source
Gets an ID that can be used to identify this DOM object in the running session.

Note: This method does not work on text nodes prior to Internet Explorer 9.

Returns

Number

A unique ID.
hasAscendant( name, includeSelf )

See source

Parameters

name : Object

includeSelf : Object
inherited
hasListeners( eventName ) → Boolean
See source
Checks if there is any listener registered to a given event.
```
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) );    // true
alert( someObject.hasListeners( 'noEvent' ) );      // false
```
Parameters

eventName : String

The event name.

Returns

Boolean
hasNext() → Boolean

See source
Checks if the node is succeeded by any sibling.

Returns

Boolean
hasPrevious() → Boolean

See source
Checks if the node is preceded by any sibling.

Returns

Boolean
insertAfter( node ) → node
See source
Inserts this element after a node.
```
var em = new CKEDITOR.dom.element( 'em' );
var strong = new CKEDITOR.dom.element( 'strong' );
strong.insertAfter( em );

// Result: '<em></em><strong></strong>'
```
Parameters

node : node

The node that will precede this element.

Returns

node

The node preceding this one after insertion.
insertBefore( node ) → node
See source
Inserts this element before a node.
```
var em = new CKEDITOR.dom.element( 'em' );
var strong = new CKEDITOR.dom.element( 'strong' );
strong.insertBefore( em );

// result: '<strong></strong><em></em>'
```
Parameters

node : node

The node that will succeed this element.

Returns

node

The node being inserted.
insertBeforeMe( node ) → node
See source
Inserts a node before this node.
```
var em = new CKEDITOR.dom.element( 'em' );
var strong = new CKEDITOR.dom.element( 'strong' );
strong.insertBeforeMe( em );

// result: '<em></em><strong></strong>'
```
Parameters

node : node

The node that will preceed this element.

Returns

node

The node being inserted.
since 3.5.0
isReadOnly( [ checkOnlyAttributes ] ) → Boolean
See source
Checks if this node is read-only (should not be changed).
```
// For the following HTML:
// <b>foo</b><div contenteditable="false"><i>bar</i></div>

elB.isReadOnly(); // -> false
foo.isReadOnly(); // -> false
elDiv.isReadOnly(); // -> true
elI.isReadOnly(); // -> true
```
This method works in two modes depending on browser support for the element.isContentEditable property and the value of the checkOnlyAttributes parameter. The element.isContentEditable check is faster, but it is known to malfunction in hidden or detached nodes. Additionally, when processing some detached DOM tree you may want to imitate that this happens inside an editable container (like it would happen inside the CKEDITOR.editable). To do so, you can temporarily attach this tree to an element with the data-cke-editable attribute and use the checkOnlyAttributes mode.

Parameters

[ checkOnlyAttributes ] : Boolean

If true, only attributes will be checked, native methods will not be used. This parameter needs to be true to check hidden or detached elements. Introduced in 4.5.0.

Defaults to false

Returns

Boolean
ltrim()

See source
move( target, toStart )

See source

Parameters

target : Object

toStart : Object
inherited
on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → Object
See source
Registers a listener to a specific event in the current object.
```
someObject.on( 'someEvent', function() {
    alert( this == someObject );        // true
} );

someObject.on( 'someEvent', function() {
    alert( this == anotherObject );     // true
}, anotherObject );

someObject.on( 'someEvent', function( event ) {
    alert( event.listenerData );        // 'Example'
}, null, 'Example' );

someObject.on( 'someEvent', function() { ... } );                       // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called
```
Note: CKEditor's event system has a limitation that one function cannot be used as a listener for the same event more than once. Hence, to reuse it with multiple listeners, it should be wrapped into additional wrapper function:
```
function listener( evt ) { ... };

someObject.on( 'someEvent', function() {
    listener();
} );

someObject.on( 'someEvent', function( evt ) {
    listener( evt );
} );
```
Parameters

eventName : String

The event name to which listen.

listenerFunction : Function

The function listening to the event. A single CKEDITOR.eventInfo object instanced is passed to this function containing all the event data.

[ scopeObj ] : Object

The object used to scope the listener call (the this object). If omitted, the current object is used.

[ listenerData ] : Object

Data to be sent as the CKEDITOR.eventInfo.listenerData when calling the listener.

[ priority ] : Number

The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.

Defaults to 10

Returns

Object

An object containing the removeListener function, which can be used to remove the listener at any time.
inherited
once()

See source
Similiar with on but the listener will be called only once upon the next event firing.

CKEDITOR.event.on
chainable
remove( [ preserveChildren ] ) → node
See source
Removes this node from the document DOM.
```
var element = CKEDITOR.document.getById( 'MyElement' );
element.remove();
```
Parameters

[ preserveChildren ] : Boolean

Indicates that the children elements must remain in the document, removing only the outer tags.

Defaults to false

Returns

node

this
inherited
removeAllListeners()

See source
Removes any listener set on this object.

To avoid memory leaks we must assure that there are no references left after the object is no longer needed.
inherited
removeCustomData( key ) → Object

See source
Removes the value in the data slot under the given key.

Parameters

key : String

Returns

Object

Removed value or null if not found.
inherited
removeListener( eventName, listenerFunction )
See source
Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.
```
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener not called.
```
Parameters

eventName : String

The event name.

listenerFunction : Function

The listener function to unregister.
replace( nodeToReplace )

See source

Parameters

nodeToReplace : Object
rtrim()

See source
chainable inherited
setCustomData( key, value ) → domObject
See source
Sets a data slot value for this object. These values are shared by all instances pointing to that same DOM object.

Note: The created data slot is only guaranteed to be available on this unique DOM node, thus any wish to continue access to it from other element clones (either created by clone node or from innerHtml) will fail. For such usage please use CKEDITOR.dom.element.setAttribute instead.

Note: This method does not work on text nodes prior to Internet Explorer 9.
```
var element = new CKEDITOR.dom.element( 'span' );
element.setCustomData( 'hasCustomData', true );
```
Parameters

key : String

A key used to identify the data slot.

value : Object

The value to set to the data slot.

Returns

domObject

This DOM object instance.
trim()

See source

Static methods

mixed static
implementOn( targetObject )
See source
Implements the CKEDITOR.event features in an object.
```
var myObject = { message: 'Example' };
CKEDITOR.event.implementOn( myObject );

myObject.on( 'testEvent', function() {
    alert( this.message );
} );
myObject.fire( 'testEvent' ); // 'Example'
```
Parameters

targetObject : Object

The object into which implement the features.

CKEDITOR.dom.node

Filtering

Properties

readonly inherited $ : ObjectCKEDITOR.dom.node#s-

Static properties

mixed static useCapture : BooleanCKEDITOR.dom.node#useCapture

Methods

inherited constructor( nativeDomObject ) → domObjectCKEDITOR.dom.node#constructor

Parameters

Returns

appendTo( element ) → elementCKEDITOR.dom.node#appendTo

Parameters

Returns

inherited capture()CKEDITOR.dom.node#capture

inherited clearCustomData()CKEDITOR.dom.node#clearCustomData

clone( [ includeChildren ], [ cloneId ] ) → nodeCKEDITOR.dom.node#clone

Parameters

Returns

inherited define( name, meta )CKEDITOR.dom.node#define

Parameters

inherited equals( object ) → BooleanCKEDITOR.dom.node#equals

Parameters

Returns

inherited fire( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.dom.node#fire

Parameters

Returns

inherited fireOnce( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.dom.node#fireOnce

Parameters

Returns

getAddress( [ normalized ] ) → ArrayCKEDITOR.dom.node#getAddress

Parameters

Returns

since 3.6.1 getAscendant( query, [ includeSelf ] ) → nodeCKEDITOR.dom.node#getAscendant

Parameters

Returns

getCommonAncestor( node )CKEDITOR.dom.node#getCommonAncestor

Parameters

inherited getCustomData( key ) → ObjectCKEDITOR.dom.node#getCustomData

Parameters

Returns

getDocument() → documentCKEDITOR.dom.node#getDocument

Returns

getIndex( normalized ) → NumberCKEDITOR.dom.node#getIndex

Parameters

Returns

getNext( [ evaluator ] ) → nodeCKEDITOR.dom.node#getNext

Parameters

Returns

getNextSourceNode( startFromSibling, nodeType, guard )CKEDITOR.dom.node#getNextSourceNode

Parameters

getParent( [ allowFragmentParent ] ) → elementCKEDITOR.dom.node#getParent

Parameters

Returns

getParents( [ closerFirst ] ) → ArrayCKEDITOR.dom.node#getParents

Parameters

Returns

getPosition( otherNode ) → NumberCKEDITOR.dom.node#getPosition

Parameters

Returns

getPrevious( [ evaluator ] ) → nodeCKEDITOR.dom.node#getPrevious

Parameters

Returns

getPreviousSourceNode( startFromSibling, nodeType, guard )CKEDITOR.dom.node#getPreviousSourceNode

Parameters

inherited getPrivate() → ObjectCKEDITOR.dom.node#getPrivate

Returns

inherited getUniqueId() → NumberCKEDITOR.dom.node#getUniqueId

Returns

hasAscendant( name, includeSelf )CKEDITOR.dom.node#hasAscendant

Parameters

inherited hasListeners( eventName ) → BooleanCKEDITOR.dom.node#hasListeners

Parameters

Returns

hasNext() → BooleanCKEDITOR.dom.node#hasNext

Returns

hasPrevious() → BooleanCKEDITOR.dom.node#hasPrevious

Returns

insertAfter( node ) → nodeCKEDITOR.dom.node#insertAfter

Parameters

Returns

readonly inherited
`$ : Object`

mixed static
`useCapture : Boolean`

inherited
`constructor( nativeDomObject ) → domObject`

`appendTo( element ) → element`

inherited
`capture()`

inherited
`clearCustomData()`

`clone( [ includeChildren ], [ cloneId ] ) → node`

inherited
`define( name, meta )`

inherited
`equals( object ) → Boolean`

inherited
`fire( eventName, [ data ], [ editor ] ) → Boolean | Object`

inherited
`fireOnce( eventName, [ data ], [ editor ] ) → Boolean | Object`

`getAddress( [ normalized ] ) → Array`

since 3.6.1
`getAscendant( query, [ includeSelf ] ) → node`

`getCommonAncestor( node )`

inherited
`getCustomData( key ) → Object`

`getDocument() → document`

`getIndex( normalized ) → Number`

`getNext( [ evaluator ] ) → node`

`getNextSourceNode( startFromSibling, nodeType, guard )`

`getParent( [ allowFragmentParent ] ) → element`

`getParents( [ closerFirst ] ) → Array`

`getPosition( otherNode ) → Number`

`getPrevious( [ evaluator ] ) → node`

`getPreviousSourceNode( startFromSibling, nodeType, guard )`

inherited
`getPrivate() → Object`

inherited
`getUniqueId() → Number`

`hasAscendant( name, includeSelf )`

inherited
`hasListeners( eventName ) → Boolean`

`hasNext() → Boolean`

`hasPrevious() → Boolean`

`insertAfter( node ) → node`

`insertBefore( node ) → node`

`insertBeforeMe( node ) → node`

since 3.5.0
`isReadOnly( [ checkOnlyAttributes ] ) → Boolean`

`ltrim()`

`move( target, toStart )`

inherited
`on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → Object`

inherited
`once()`

chainable
`remove( [ preserveChildren ] ) → node`

inherited
`removeAllListeners()`

inherited
`removeCustomData( key ) → Object`

inherited
`removeListener( eventName, listenerFunction )`

`replace( nodeToReplace )`

`rtrim()`

chainable inherited
`setCustomData( key, value ) → domObject`

`trim()`

mixed static
`implementOn( targetObject )`