CKEditor 4 Documentation

CKEDITOR.dom.range

Files

Represents a delimited piece of content in a DOM Document. It is contiguous in the sense that it can be characterized as selecting all of the content between a pair of boundary-points.

This class shares much of the W3C Document Object Model Range ideas and features, adding several range manipulation tools to it, but it's not intended to be compatible with it.

// Create a range for the entire contents of the editor document body.
var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
// Delete the contents.
range.deleteContents();

Usually you will want to work on a ranges rooted in the editor's editable element. Such ranges can be created with a shorthand method – editor.createRange.

var range = editor.createRange();
range.root.equals( editor.editable() ); // -> true

Note that the root of a range is an important property, which limits many algorithms implemented in range's methods. Therefore it is crucial, especially when using ranges inside inline editors, to specify correct root, so using the CKEDITOR.editor.createRange method is highly recommended.

Selection

Range is only a logical representation of a piece of content in a DOM. It should not be confused with a selection which represents "physically marked" content. It is possible to create unlimited number of various ranges, when only one real selection may exist at a time in a document. Ranges are used to read position of selection in the DOM and to move selection to new positions.

The editor selection may be retrieved using the CKEDITOR.editor.getSelection method:

var sel = editor.getSelection(),
    ranges = sel.getRange(); // CKEDITOR.dom.rangeList instance.

var range = ranges[ 0 ];
range.root; // -> editor's editable element.

A range can also be selected:

var range = editor.createRange();
range.selectNodeContents( editor.editable() );
sel.selectRanges( [ range ] );
Defined By

Properties

CKEDITOR.dom.range
view source
: Booleanreadonly
Indicates that this is a collapsed range. ...

Indicates that this is a collapsed range. A collapsed range has its start and end boundaries at the very same point so nothing is contained in it.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.collapsed ); // false
range.collapse();
alert( range.collapsed ); // true

Defaults to: true

CKEDITOR.dom.range
view source
: CKEDITOR.dom.documentreadonly
The document within which the range can be used. ...

The document within which the range can be used.

// Selects the body contents of the range document.
range.selectNodeContents( range.document.getBody() );
Node within which the range ends. ...

Node within which the range ends.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.endContainer.getName() ); // 'body'
CKEDITOR.dom.range
view source
: Numberreadonly
Offset within the ending node of the range. ...

Offset within the ending node of the range.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.endOffset ); // == editor.document.getBody().getChildCount()
CKEDITOR.dom.range
view source
: CKEDITOR.dom.elementreadonly

The ancestor DOM element within which the range manipulation are limited.

The ancestor DOM element within which the range manipulation are limited.

Node within which the range begins. ...

Node within which the range begins.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.startContainer.getName() ); // 'body'
CKEDITOR.dom.range
view source
: Numberreadonly
Offset within the starting node of the range. ...

Offset within the starting node of the range.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.startOffset ); // 0
Defined By

Methods

CKEDITOR.dom.range
view source
new( root ) : CKEDITOR.dom.range
Creates a CKEDITOR.dom.range instance that can be used inside a specific DOM Document. ...

Creates a CKEDITOR.dom.range instance that can be used inside a specific DOM Document.

Parameters

Returns

CKEDITOR.dom.range
view source
( endContainer )private
Setter for the endContainer. ...

Setter for the endContainer.

Available since: 4.4.6

Parameters

CKEDITOR.dom.range
view source
( startContainer )private
Setter for the startContainer. ...

Setter for the startContainer.

Available since: 4.4.6

Parameters

CKEDITOR.dom.range
view source
( element, checkType ) : Boolean
Check whether a range boundary is at the inner boundary of a given element. ...

Check whether a range boundary is at the inner boundary of a given element.

Parameters

Returns

  • Boolean

    true if the range boundary is at the inner boundary of the element.

CKEDITOR.dom.range
view source
( ) : Boolean
Note: Calls to this function may produce changes to the DOM. ...

Note: Calls to this function may produce changes to the DOM. The range may be updated to reflect such changes.

Returns

  • Boolean
CKEDITOR.dom.range
view source
( ) : Boolean
Check if elements at which the range boundaries anchor are read-only, with respect to contenteditable attribute. ...

Check if elements at which the range boundaries anchor are read-only, with respect to contenteditable attribute.

Returns

  • Boolean
CKEDITOR.dom.range
view source
( ) : Boolean
Note: Calls to this function may produce changes to the DOM. ...

Note: Calls to this function may produce changes to the DOM. The range may be updated to reflect such changes.

Returns

  • Boolean
CKEDITOR.dom.range
view source
( ) : CKEDITOR.dom.range
Clones this range. ...

Clones this range.

Returns

The content nodes of the range are cloned and added to a document fragment, which is returned. ...

The content nodes of the range are cloned and added to a document fragment, which is returned.

Note: Text selection may lost after invoking this method (caused by text node splitting).

Returns

CKEDITOR.dom.range
view source
( toStart )
Makes range collapsed by moving its start point (or end point if toStart==true) to the second end. ...

Makes range collapsed by moving its start point (or end point if toStart==true) to the second end.

Parameters

  • toStart : Boolean

    Collapse range "to start".

CKEDITOR.dom.range
view source
( [serializable] ) : Object
Creates a bookmark object, which can be later used to restore the range by using the moveToBookmark function. ...

Creates a bookmark object, which can be later used to restore the range by using the moveToBookmark function.

This is an "intrusive" way to create a bookmark. It includes <span> tags in the range boundaries. The advantage of it is that it is possible to handle DOM mutations when moving back to the bookmark.

Note: The inclusion of nodes in the DOM is a design choice and should not be changed as there are other points in the code that may be using those nodes to perform operations.

Parameters

  • serializable : Boolean (optional)

    Indicates that the bookmark nodes must contain IDs, which can be used to restore the range even when these nodes suffer mutations (like cloning or innerHTML change).

Returns

  • Object

    And object representing a bookmark.

CKEDITOR.dom.range
view source
( [normalized] ) : Object
Creates a "non intrusive" and "mutation sensible" bookmark. ...

Creates a "non intrusive" and "mutation sensible" bookmark. This kind of bookmark should be used only when the DOM is supposed to remain stable after its creation.

Parameters

  • normalized : Boolean (optional)

    Indicates that the bookmark must be normalized. When normalized, the successive text nodes are considered a single node. To successfully load a normalized bookmark, the DOM tree must also be normalized before calling moveToBookmark.

Returns

  • Object

    An object representing the bookmark.

    • start : Array

      Start container's address (see CKEDITOR.dom.node.getAddress).

    • end : Array

      Start container's address.

    • startOffset : Number
    • endOffset : Number
    • collapsed : Boolean
    • normalized : Boolean
    • is2 : Boolean

      This is "bookmark2".

Creates a {CKEDITOR.dom.iterator} instance for this range. ...

Creates a {CKEDITOR.dom.iterator} instance for this range.

Returns

CKEDITOR.dom.range
view source
( [mergeThen] )
Deletes the content nodes of the range permanently from the DOM tree. ...

Deletes the content nodes of the range permanently from the DOM tree.

Parameters

  • mergeThen : Boolean (optional)

    Merge any splitted elements result in DOM true due to partial selection.

Gets CKEDITOR.dom.elementPath for the endContainer. ...
CKEDITOR.dom.range
view source
( unit, [excludeBrs] )
Expands the range so that partial units are completely contained. ...

Expands the range so that partial units are completely contained.

Parameters

  • unit : Object

    {Number} The unit type to expand with.

  • excludeBrs : Boolean (optional)

    Whether include line-breaks when expanding.

    Defaults to: false

The content nodes of the range are cloned and added to a document fragment, meanwhile they are removed permanently fr...

The content nodes of the range are cloned and added to a document fragment, meanwhile they are removed permanently from the DOM tree.

Parameters

  • mergeThen : Boolean (optional)

    Merge any splitted elements result in DOM true due to partial selection.

Returns

CKEDITOR.dom.range
view source
( [isStart], blockTag ) : CKEDITOR.dom.element
Wraps inline content found around the range's start or end boundary with a block element. ...

Wraps inline content found around the range's start or end boundary with a block element.

// Assuming the following range:
// <h1>foo</h1>ba^r<br />bom<p>foo</p>
// The result of executing:
range.fixBlock( true, 'p' );
// will be:
// <h1>foo</h1><p>ba^r<br />bom</p><p>foo</p>

Non-collapsed range:

// Assuming the following range:
// ba[r<p>foo</p>bo]m
// The result of executing:
range.fixBlock( false, 'p' );
// will be:
// ba[r<p>foo</p><p>bo]m</p>

Parameters

  • isStart : Boolean (optional)

    Whether the start or end boundary of a range should be checked.

    Defaults to: false

  • blockTag : String

    The name of a block element in which content will be wrapped. For example: 'p'.

Returns

CKEDITOR.dom.range
view source
( ) : Object
Returns two nodes which are on the boundaries of this range. ...

Returns two nodes which are on the boundaries of this range.

Returns

CKEDITOR.dom.range
view source
( [includeSelf], [ignoreTextNode] ) : CKEDITOR.dom.element
Find the node which fully contains the range. ...

Find the node which fully contains the range.

Parameters

  • includeSelf : Boolean (optional)

    Defaults to: false

  • ignoreTextNode : Boolean (optional)

    Whether ignore CKEDITOR.NODE_TEXT type.

    Defaults to: false

Returns

Get the single node enclosed within the range if there's one. ...

Get the single node enclosed within the range if there's one.

Returns

Gets next node which can be a container of a selection. ...

Gets next node which can be a container of a selection. This methods mimics a behavior of right/left arrow keys in case of collapsed selection. It does not return an exact position (with offset) though, but just a selection's container.

Note: use this method on a collapsed range.

Available since: 4.3

Returns

CKEDITOR.dom.range
view source
( evaluator, [guard], [boundary] ) : CKEDITOR.dom.element/null
Traverse with CKEDITOR.dom.walker to retrieve the next element before the range start. ...

Traverse with CKEDITOR.dom.walker to retrieve the next element before the range start.

Parameters

  • evaluator : Function

    Function used as the walker's evaluator.

  • guard : Function (optional)

    Function used as the walker's guard.

  • boundary : CKEDITOR.dom.element (optional)

    A range ancestor element in which the traversal is limited, default to the root editable if not defined.

Returns

See getNextEditableNode. ...
CKEDITOR.dom.range
view source
( evaluator, [guard], [boundary] ) : CKEDITOR.dom.element/null
Traverse with CKEDITOR.dom.walker to retrieve the previous element before the range start. ...

Traverse with CKEDITOR.dom.walker to retrieve the previous element before the range start.

Parameters

  • evaluator : Function

    Function used as the walker's evaluator.

  • guard : Function (optional)

    Function used as the walker's guard.

  • boundary : CKEDITOR.dom.element (optional)

    A range ancestor element in which the traversal is limited, default to the root editable if not defined.

Returns

Get the node adjacent to the range end or endContainer. ...

Get the node adjacent to the range end or endContainer.

Returns

Get the node adjacent to the range start or startContainer. ...

Get the node adjacent to the range start or startContainer.

Returns

CKEDITOR.dom.range
view source
( node )
Inserts a node at the start of the range. ...

Inserts a node at the start of the range. The range will be expanded the contain the node.

Parameters

CKEDITOR.dom.range
view source
( bookmark )
Moves this range to the given bookmark. ...

Moves this range to the given bookmark. See createBookmark and createBookmark2.

If serializable bookmark passed, then its <span> markers will be removed.

Parameters

  • bookmark : Object
CKEDITOR.dom.range
view source
( element, isMoveToEnd ) : Boolean
Moves the range boundaries to the closest editing point after/before an element. ...

Moves the range boundaries to the closest editing point after/before an element.

For example, if the start element has id="start", <p><b>foo</b><span id="start">start</start></p>, the closest previous editing point is <p><b>foo</b>^<span id="start">start</start></p> (between <b> and <span>).

See also: moveToElementEditablePosition.

Available since: 4.3

Parameters

  • element : CKEDITOR.dom.element

    The starting element.

  • isMoveToEnd : Boolean

    Whether move to the end of editable. Otherwise, look back.

Returns

  • Boolean

    Whether the range was moved.

CKEDITOR.dom.range
view source
( target ) : Boolean
See moveToElementEditablePosition. ...

See moveToElementEditablePosition.

Parameters

  • target : Object

Returns

  • Boolean

    Whether range was moved.

CKEDITOR.dom.range
view source
( target ) : Boolean
See moveToElementEditablePosition. ...

See moveToElementEditablePosition.

Parameters

  • target : Object

Returns

  • Boolean

    Whether range was moved.

CKEDITOR.dom.range
view source
( el, isMoveToEnd ) : Boolean
Moves the range boundaries to the first/end editing point inside an element. ...

Moves the range boundaries to the first/end editing point inside an element.

For example, in an element tree like <p><b><i></i></b> Text</p>, the start editing point is <p><b><i>^</i></b> Text</p> (inside <i>).

Parameters

  • el : CKEDITOR.dom.element

    The element into which look for the editing spot.

  • isMoveToEnd : Boolean

    Whether move to the end editable position.

Returns

  • Boolean

    Whether range was moved.

CKEDITOR.dom.range
view source
( node, position )
Moves the range to given position according to specified node. ...

Moves the range to given position according to specified node.

// HTML: <p>Foo <b>bar</b></p>
range.moveToPosition( elB, CKEDITOR.POSITION_BEFORE_START );
// Range will be moved to: <p>Foo ^<b>bar</b></p>

See also setStartAt and setEndAt.

Parameters

CKEDITOR.dom.range
view source
( range )
Moves the range to the exact position of the specified range. ...

Moves the range to the exact position of the specified range.

Parameters

CKEDITOR.dom.range
view source
( )
Transforms the startContainer and endContainer properties from text nodes to element nodes, whenever possible. ...

Transforms the startContainer and endContainer properties from text nodes to element nodes, whenever possible. This is actually possible if either of the boundary containers point to a text node, and its offset is set to zero, or after the last char in the node.

CKEDITOR.dom.range
view source
( )
Move the range out of bookmark nodes if they'd been the container. ...

Move the range out of bookmark nodes if they'd been the container.

CKEDITOR.dom.range
view source
( atEnd )
Recursively remove any empty path blocks at the range boundary. ...

Recursively remove any empty path blocks at the range boundary.

Parameters

  • atEnd : Boolean

    Removal to perform at the end boundary, otherwise to perform at the start.

CKEDITOR.dom.range
view source
( )
Scrolls the start of current range into view. ...

Scrolls the start of current range into view.

Select this range as the only one with CKEDITOR.dom.selection.selectRanges. ...

Select this range as the only one with CKEDITOR.dom.selection.selectRanges.

Returns

CKEDITOR.dom.range
view source
( node )
Select nodes content. ...

Select nodes content. Range will start and end inside this node.

Parameters

CKEDITOR.dom.range
view source
( endNode, endOffset )
Sets the end position of a Range. ...

Sets the end position of a Range.

Parameters

  • endNode : CKEDITOR.dom.node

    The node to end the range.

  • endOffset : Number

    An integer greater than or equal to zero representing the offset for the end of the range from the start of endNode.

CKEDITOR.dom.range
view source
( node )
Sets end of this range after the specified node. ...

Sets end of this range after the specified node.

// Range: <p>foo^<b>bar</b></p>
range.setEndAfter( elB );
// The range will be changed to:
// <p>foo[<b>bar</b>]</p>

Parameters

CKEDITOR.dom.range
view source
( node, position )
Moves the end of this range to given position according to specified node. ...

Moves the end of this range to given position according to specified node.

// HTML: <p>^Foo <b>bar</b></p>
range.setEndAt( textBar, CKEDITOR.POSITION_BEFORE_START );
// The range will be changed to:
// <p>[Foo <b>]bar</b></p>

See also setStartAt and moveToPosition.

Parameters

CKEDITOR.dom.range
view source
( node )
Sets end of this range before the specified node. ...

Sets end of this range before the specified node.

// Range: <p>^foo<b>bar</b></p>
range.setStartAfter( textBar );
// The range will be changed to:
// <p>[foo<b>]bar</b></p>

Parameters

CKEDITOR.dom.range
view source
( startNode, startOffset )
Sets the start position of a range. ...

Sets the start position of a range.

Parameters

  • startNode : CKEDITOR.dom.node

    The node to start the range.

  • startOffset : Number

    An integer greater than or equal to zero representing the offset for the start of the range from the start of startNode.

CKEDITOR.dom.range
view source
( node )
Sets start of this range after the specified node. ...

Sets start of this range after the specified node.

// Range: <p>foo<b>bar</b>^</p>
range.setStartAfter( textFoo );
// The range will be changed to:
// <p>foo[<b>bar</b>]</p>

Parameters

CKEDITOR.dom.range
view source
( node, position )
Moves the start of this range to given position according to specified node. ...

Moves the start of this range to given position according to specified node.

// HTML: <p>Foo <b>bar</b>^</p>
range.setStartAt( elB, CKEDITOR.POSITION_AFTER_START );
// The range will be changed to:
// <p>Foo <b>[bar</b>]</p>

See also setEndAt and moveToPosition.

Parameters

CKEDITOR.dom.range
view source
( node )
Sets start of this range after the specified node. ...

Sets start of this range after the specified node.

// Range: <p>foo<b>bar</b>^</p>
range.setStartBefore( elB );
// The range will be changed to:
// <p>foo[<b>bar</b>]</p>

Parameters

CKEDITOR.dom.range
view source
( mode, selectContents )
Descrease the range to make sure that boundaries always anchor beside text nodes or innermost element. ...

Descrease the range to make sure that boundaries always anchor beside text nodes or innermost element.

Parameters

CKEDITOR.dom.range
view source
( blockTag )
...

Parameters

  • blockTag : Object
CKEDITOR.dom.range
view source
( element ) : CKEDITOR.dom.element
Branch the specified element from the collapsed range position and place the caret between the two result branches. ...

Branch the specified element from the collapsed range position and place the caret between the two result branches.

Note: The range must be collapsed and been enclosed by this element.

Parameters

Returns

Gets CKEDITOR.dom.elementPath for the startContainer. ...
CKEDITOR.dom.range
view source
( [ignoreStart], [ignoreEnd] )
...

Parameters

  • ignoreStart : Boolean (optional)

    Defaults to: false

  • ignoreEnd : Boolean (optional)

    precise desc/algorithm

    Defaults to: false