CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.dom.range

class
See source

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

Filtering

Properties

  • readonly

    collapsed : Boolean

    See source

    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

  • readonly

    document : document

    See source

    The document within which the range can be used.

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

  • readonly

    endContainer : element | text

    See source

    Node within which the range ends.

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

  • readonly

    endOffset : Number

    See source

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

  • readonly

    root : element

    See source

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

  • readonly

    startContainer : element | text

    See source

    Node within which the range begins.

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

  • readonly

    startOffset : Number

    See source

    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

Methods