Class CKEDITOR.dom.range

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.
Defined in: core/dom/range.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	CKEDITOR.dom.range(document) Creates a CKEDITOR.dom.range instance that can be used inside a specific DOM Document.

Field Summary
Field Attributes	Field Name and Description
	collapsed Indicates that this is a collapsed range.
	document The document within which the range can be used.
	endContainer Node within which the range ends.
	endOffset Offset within the ending node of the range.
	startContainer Node within which the range begins.
	startOffset Offset within the starting node of the range.

Method Summary
Method Attributes	Method Name and Description
	checkBoundaryOfElement(element, checkType) Check whether a range boundary is at the inner boundary of a given element.
	checkEndOfBlock()
	checkStartOfBlock()
	clone()
	cloneContents() The content nodes of the range are cloned and added to a document fragment, which is returned.
	collapse(toStart)
	createBookmark(serializable) Creates a bookmark object, which can be later used to restore the range by using the moveToBookmark function.
	createBookmark2(normalized) Creates a "non intrusive" and "mutation sensible" bookmark.
	createIterator()
	deleteContents(mergeThen) Deletes the content nodes of the range permanently from the DOM tree.
	enlarge(unit, excludeBrs) Expands the range so that partial units are completely contained.
	extractContents(mergeThen) The content nodes of the range are cloned and added to a document fragment, meanwhile they're removed permanently from the DOM tree.
	fixBlock(isStart, blockTag)
	getBoundaryNodes()
	getCommonAncestor(includeSelf, ignoreTextNode) Find the node which fully contains the range.
	getEnclosedNode() Get the single node enclosed within the range if there's one.
	getNextNode(evaluator, guard, boundary) Traverse with CKEDITOR.dom.walker to retrieve the next element before the range start.
	getPreviousNode(evaluator, guard, boundary) Traverse with CKEDITOR.dom.walker to retrieve the previous element before the range start.
	getTouchedEndNode()
	getTouchedStartNode()
	insertNode(node) Inserts a node at the start of the range.
	moveToBookmark(bookmark)
	moveToElementEditablePosition(el, isMoveToEnd) Moves the range boundaries to the first/end editing point inside an element.
	moveToElementEditEnd(target)
	moveToElementEditStart(target)
	moveToPosition(node, position)
	optimize() Transforms the startContainer and endContainer properties from text nodes to element nodes, whenever possible.
	optimizeBookmark() Move the range out of bookmark nodes if they'd been the container.
	selectNodeContents(node)
	setEnd(endNode, endOffset) Sets the end position of a Range.
	setEndAfter(node)
	setEndAt(node, position)
	setEndBefore(node)
	setStart(startNode, startOffset) Sets the start position of a Range.
	setStartAfter(node)
	setStartAt(node, position)
	setStartBefore(node)
	shrink(mode, selectContents) Descrease the range to make sure that boundaries always anchor beside text nodes or innermost element.
	splitBlock(blockTag)
	splitElement(element) Branch the specified element from the collapsed range position and place the caret between the two result branches.
	trim(ignoreStart, ignoreEnd)

Class Detail

CKEDITOR.dom.range(document)

Since: 3.0

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

// 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();

Parameters:
{CKEDITOR.dom.document} document: The document into which the range features will be available.

Field Detail

{Undefined} collapsed

Since: 3.0

Indicates that this is a collapsed range. A collapsed range has it's start and end boudaries 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"

{Undefined} document

Since: 3.0

The document within which the range can be used.

// Selects the body contents of the range document.
range.selectNodeContents( range.document.getBody() );

{Undefined} endContainer

Since: 3.0

Node within which the range ends.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.endContainer.getName() );  // "body"

{Undefined} endOffset

Since: 3.0

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

{Undefined} startContainer

Since: 3.0

Node within which the range begins.

var range = new CKEDITOR.dom.range( editor.document );
range.selectNodeContents( editor.document.getBody() );
alert( range.startContainer.getName() );  // "body"

{Undefined} startOffset

Since: 3.0

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"

Method Detail

{Boolean} checkBoundaryOfElement(element, checkType)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{CKEDITOR.dom.element} element: The target element to check.
{Number} checkType: The boundary to check for both the range and the element. It can be CKEDITOR.START or CKEDITOR.END.

Returns:: {Boolean} "true" if the range boundary is at the inner boundary of the element.

{Undefined} checkEndOfBlock()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} checkStartOfBlock()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} clone()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} cloneContents()

Since: 3.0

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

NO EXAMPLE AVAILABLE

{Undefined} collapse(toStart)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} toStart

{Object} createBookmark(serializable)

Since: 3.0

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 tags in the range boundaries. The advantage of it is that it is possible to handle DOM mutations when moving back to the bookmark. Attention: 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. See GetBookmarkNode.

NO EXAMPLE AVAILABLE

Parameters:
{Boolean} serializable Optional: Indicates that the bookmark nodes must contain ids, which can be used to restore the range even when these nodes suffer mutations (like a clonation or innerHTML change).

Returns:: {Object} And object representing a bookmark.

{Object} createBookmark2(normalized)

Since: 3.0

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.

NO EXAMPLE AVAILABLE

Parameters:
{Boolean} normalized Optional: Indicates that the bookmark must normalized. When normalized, the successive text nodes are considered a single node. To sucessful load a normalized bookmark, the DOM tree must be also normalized before calling moveToBookmark.

Returns:: {Object} An object representing the bookmark.

{Undefined} createIterator()

Since: 3.0

Defined in: plugins/domiterator/plugin.js.

NO EXAMPLE AVAILABLE

{Undefined} deleteContents(mergeThen)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{Boolean} mergeThen Optional: Merge any splitted elements result in DOM true due to partial selection.

{Undefined} enlarge(unit, excludeBrs)

Since: 3.0

Expands the range so that partial units are completely contained.

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} unit: {Number} The unit type to expand with.
{Boolean} excludeBrs Optional, Default: false: Whether include line-breaks when expanding.

{Undefined} extractContents(mergeThen)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{Boolean} mergeThen Optional: Merge any splitted elements result in DOM true due to partial selection.

{Undefined} fixBlock(isStart, blockTag)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} isStart
{Undefined} blockTag

{Undefined} getBoundaryNodes()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} getCommonAncestor(includeSelf, ignoreTextNode)

Since: 3.0

Find the node which fully contains the range.

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} includeSelf
{Boolean} ignoreTextNode: Whether ignore CKEDITOR.NODE_TEXT type.

{Undefined} getEnclosedNode()

Since: 3.0

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

NO EXAMPLE AVAILABLE

{CKEDITOR.dom.element|null} getNextNode(evaluator, guard, boundary)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{Function} evaluator: Function used as the walker's evaluator.
{Function} guard Optional: Function used as the walker's guard.
{CKEDITOR.dom.element} boundary Optional: A range ancestor element in which the traversal is limited, default to the root editable if not defined.

Returns:: {CKEDITOR.dom.element|null} The returned node from the traversal.

{CKEDITOR.dom.element|null} getPreviousNode(evaluator, guard, boundary)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{Function} evaluator: Function used as the walker's evaluator.
{Function} guard Optional: Function used as the walker's guard.
{CKEDITOR.dom.element} boundary Optional: A range ancestor element in which the traversal is limited, default to the root editable if not defined.

Returns:: {CKEDITOR.dom.element|null} The returned node from the traversal.

{Undefined} getTouchedEndNode()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} getTouchedStartNode()

Since: 3.0

NO EXAMPLE AVAILABLE

{Undefined} insertNode(node)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} moveToBookmark(bookmark)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} bookmark

{Undefined} moveToElementEditablePosition(el, isMoveToEnd)

Since: 3.0

Moves the range boundaries to the first/end editing point inside an element. For example, in an element tree like " Text", the start editing point is "^ Text" (inside ).

NO EXAMPLE AVAILABLE

Parameters:
{CKEDITOR.dom.element} el: The element into which look for the editing spot.
{Boolean} isMoveToEnd: Whether move to the end editable position.

{Undefined} moveToElementEditEnd(target)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} target

See:

{Undefined} moveToElementEditStart(target)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} target

See:

{Undefined} moveToPosition(node, position)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node
{Undefined} position

{Undefined} optimize()

Since: 3.0

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.

NO EXAMPLE AVAILABLE

{Undefined} optimizeBookmark()

Since: 3.0

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

NO EXAMPLE AVAILABLE

{Undefined} selectNodeContents(node)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} setEnd(endNode, endOffset)

Since: 3.0

Sets the end position of a Range.

NO EXAMPLE AVAILABLE

Parameters:
{CKEDITOR.dom.node} endNode: The node to end the range.
{Number} endOffset: An integer greater than or equal to zero representing the offset for the end of the range from the start of endNode.

{Undefined} setEndAfter(node)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} setEndAt(node, position)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node
{Undefined} position

{Undefined} setEndBefore(node)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} setStart(startNode, startOffset)

Since: 3.0

Sets the start position of a Range.

NO EXAMPLE AVAILABLE

Parameters:
{CKEDITOR.dom.node} startNode: The node to start the range.
{Number} startOffset: An integer greater than or equal to zero representing the offset for the start of the range from the start of startNode.

{Undefined} setStartAfter(node)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} setStartAt(node, position)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node
{Undefined} position

{Undefined} setStartBefore(node)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} node

{Undefined} shrink(mode, selectContents)

Since: 3.0

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

NO EXAMPLE AVAILABLE

Parameters:

{Number} mode

( CKEDITOR.SHRINK_ELEMENT | CKEDITOR.SHRINK_TEXT ) The shrinking mode.

CKEDITOR.SHRINK_ELEMENT: Shrink the range boundaries to the edge of the innermost element.
CKEDITOR.SHRINK_TEXT: Shrink the range boudaries to anchor by the side of enclosed text node, range remains if there's no text nodes on boundaries at all.

{Boolean} selectContents

Whether result range anchors at the inner OR outer boundary of the node.

{Undefined} splitBlock(blockTag)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} blockTag

{CKEDITOR.dom.element} splitElement(element)

Since: 3.0

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.

NO EXAMPLE AVAILABLE

Parameters:
{CKEDITOR.dom.element} element

Returns:: {CKEDITOR.dom.element} Root element of the new branch after the split.

{Undefined} trim(ignoreStart, ignoreEnd)

Since: 3.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} ignoreStart
{Undefined} ignoreEnd

CKEditor 3 JavaScript API Documentation

Namespaces

Classes

Class CKEDITOR.dom.range