Skip to content

Text Range Module

Jump to bottom Edit New page
Tim edited this page Jul 16, 2014 · 17 revisions

8. Documentation for TextRange module

Documentation Home

TextRange Module

This module will be released in Rangy 1.3. It is incomplete and the API may change.

Rangy's TextRange module provides various methods for navigating and manipulating the visible text (see below for a definition of this) on a page by character or word.

Demo page

Visible text

  • Text inside a <script> or <style> element is not included
  • Text inside any elements hidden via CSS display: none or visibility: hidden is not included
  • Collapsed white space (for example in HTML such as <span>One   two</span>) is considered as a single space character
  • White space implied by block elements and <br> elements is included

Factors that are not taken into consideration:

  • CSS text-transform. For example, the text inside <span id="foo" style="text-transform: uppercase">hello</span> will be rendered on the page as "HELLO" but will be considered as "hello" by Rangy. rangy.innerText( document.getElementById("foo") ) will return "hello".
  • Text hidden via overflow or clip CSS rules.
  • CSS generated content. This content is generated by CSS content property in conjunction with :before and :after pseudo-elements. For example, with the style rule #foo:after { content: "Two"; }, the text inside <span id="foo">One</span>Three will be rendered on the page as "OneTwoThree" but will be considered as "OneThree" by Rangy.

API

wordOptions

Optional object used in options objects in several methods below. It governs how words are identified and may have any combination of the following properties:

  • includeTrailingSpace: Boolean specifying whether to include trailing space after a word within the word. Default is false.
  • wordRegex: regular expression object used to identify words. Default is /[- tokenizer`: Function used to tokenize text when identifying word boundaries (to be documented).

characterOptions

Optional object used in options objects in several methods below. It governs treatment of space characters and may have any combination of the following properties:

  • includeBlockContentTrailingSpace: Boolean specifying whether to consider a trailing space within a block as a space.
  • includeSpaceBeforeBr: Boolean specifying whether to consider a inline space immediately preceding a <br> element as a space. Default is true.
  • includePreLineTrailingSpace: Boolean specifying whether to consider a trailing space immediately preceding a line break within an element whose white-space CSS property is set to pre-line. Default is true.

Extensions to Range

The TextRange module adds the following to all Rangy Range objects. The API is based on methods from http://msdn.microsoft.com/en-us/library/ms533042(v=vs.85).aspx Internet Explorer's TextRange object.

moveStart(String unit, Number count[Object options](,))

moveEnd(String unit, Number count[Object options](,))

Moves the start or end of the range by the number of units specified by count. unit must be one of "word" and "character".

options is an optional object that governs how the range boundary move handles particular cases. It may have any combination of the following properties:

  • wordOptions: See above.
  • characterOptions: See above.

move(String unit, Number count[Object options](,))

Collapses the range to a single point and moves it by the number of units specified by count. unit must be one of "word" and "character".

If count is negative, the range is collapsed to the start, otherwise it is collapsed to the end.

options as per moveStart() and moveEnd() above.

expand(String unit[Object options](,))

Expands the range to encompass complete all units that it currently contains or partially contains. unit must be one of "word" and "character", although this method is only really useful for words. If "character" is specified, this method is identical to calling moveEnd("character", 1).

options is an optional object that governs how the range boundary move handles particular cases. It may have any combination of the following properties:

  • wordOptions: See above.
  • characterOptions: See above.
  • trim: Boolean specifying whether to trim trailing and leading spaces from the final range. Default is false.
  • trimStart: Boolean specifying whether to trim leading spaces from the expanded range. Only comes into effect if trim property is true. Default is true.
  • trimEnd: Boolean specifying whether to trim trailing spaces from the expanded range. Only comes into effect if trim property is true. Default is true.

text()

Returns the visible text contained in the range.

selectCharacters(Node containerNode, Number startIndex, Number endIndex)

Moves the range to contain text within containerNode specified by character indices startIndex and endIndex within the visible text of containerNode.

toCharacterRange(Node containerNode)

Returns the range as a pair of character indices relative to the start of the visible text of containerNode. The returned value is an object with properties start and end.

findText(mixed searchTerm[Object options](,))

Provides a means of searching text on a page, including using regular expressions. In conjunction with the CSS Class Applier module, this can be used to create a custom page search facility (as demonstrated on the demo page).

This method searches the visible text of the document for the text specified by searchTerm, which may be either a string or a regular expression object. The search starts from the start or end of the range (depending on search direction). The range moves to encompass the first match.

options is an optional object that allows flexible searching. Any combination of the following properties may be supplied:

  • caseSensitive: Default is false
  • withinRange: Specifies the scope of the search. If supplied, only the text within this range is searched. Default is null.
  • wholeWordsOnly: Whether to match only whole words. Default is false.
  • wrap: Whether the search should wrap around if the start or end of the search scope is reached without finding a match. Default is false.
  • direction: String that specifies the direction of the search. Set it to "backward" to perform a backward search. Default is "forward".
  • wordOptions: See above.
  • characterOptions: See above.

pasteHtml(String html)

Replaces the contents of the range with HTML specified by html.

Extensions to Selection

move(String unit, Number count[Object options](,))

Collapses the selection to a single point and moves it by the number of units specified by count. unit must be one of "word" and "character".

If count is negative, the selection is collapsed to the start, otherwise it is collapsed to the end.

See Range move() documentation for details.

expand(String unit[Object options](,))

Expands the selection to encompass complete all units that it currently contains or partially contains. See Range expand() documentation for details.

If the selection was originally backward then the expanded selection will also be backward, if programmatic creation of backward ranges is supported by the browser (in practice this means all major browsers except IE).

selectCharacters(Node containerNode, Number startIndex, Number endIndex[Boolean backward](,))

Selects a range of characters within the visible text of containerNode specified by startIndex and endIndex. The selection direction is governed by backward (although in IE, the selection will always be created forwards).

saveCharacterRanges(Node containerNode)

Returns an object specifying the selection as character indices within the visible text of containerNode. This object can later be used to restore the selection by passing it into restoreCharacterRanges().

restoreCharacterRanges(Node containerNode, Object characterRanges)

Restores a selection previously saved using saveCharacterRanges().

These two methods provide a character index-based selection save and restore which is not vulnerable to formatting changes (unlike Rangy's existing Selection Save Restore Module).

Extensions to the main rangy object

innerText(Element el)

Returns the visible text for the element el.

Nova página

Add a custom sidebar
Clone this wiki locally