Rangy

The TextRange module is a Rangy plugin designed for text-based manipulation and searching of ranges and selections. Key capabilities include:

• Boundary Manipulation: Move range boundaries using character or word offsets.
• Customizable Tokenization: Use a custom word tokenizer for different languages or rules.
• Smart Visibility Awareness: Automatically ignores text nodes inside <script> or <style> elements, or those hidden by CSS display and visibility properties.
• Text Searching: Use range.findText() to search for text or regular expressions within the page or a specific range, with support for whole-word and case-sensitivity flags.
• Persistence: Save and restore selections and ranges as text offsets within a node.
• Text Extraction: Retrieve visible text within a range or selection, and use innerText for elements.

The SaveRestore module is a Rangy plugin that allows you to save a user's current selection (or multiple ranges) and restore them later. It works by inserting invisible marker elements (<span> tags with the class rangySelectionBoundary) into the DOM to act as anchors.

To use it, you must first ensure the module is loaded via Rangy's createModule mechanism. Once loaded, the API is attached to the rangy object.

Workflow:

1. Call rangy.saveSelection(window) to capture the current selection. This returns a savedSelection object containing the necessary metadata and range information.
2. Perform other DOM manipulations.
3. Call rangy.restoreSelection(savedSelection) to re-apply the captured selection to the window.

In Rangy, a WrappedSelection is a high-level wrapper around the browser's native selection mechanism. It manages one or more WrappedRange objects.

When you call addRange on a WrappedSelection, you are adding a WrappedRange to the selection's internal list of ranges. The WrappedSelection tracks properties like anchorNode, focusNode, anchorOffset, focusOffset, rangeCount, isCollapsed, and type (e.g., 'Caret', 'Range', or 'None').

If the browser supports multiple ranges (like modern W3C compliant browsers), the WrappedSelection manages a collection of ranges. In older IE environments, it may use ControlRange to simulate multiple selections by treating a group of elements as a single Control selection.

Rangy can be initialized manually using api.init(). If you are loading Rangy after the document has already loaded, use api.addInitListener(callback) to register a function that will execute as soon as Rangy is initialized.

Additionally, api.shim(window) can be used to initialize the library and notify shim listeners, which is useful for polyfilling missing native APIs in older browsers.

The Serializer module allows you to convert DOM Ranges and Selections into string formats. This is useful for persisting a user's selection (e.g., in a cookie or local storage) and restoring it later.

Key features include:

• Checksums: By default, serialized ranges include a checksum of the root node to ensure the selection is only restored if the DOM structure hasn't changed significantly.
• Cookie Support: Built-in methods to save and restore selections directly from/to cookies.

To use these features, ensure the Serializer module is loaded as part of your Rangy installation.

The findText method accepts an options object to control the search behavior:

• caseSensitive (boolean): Whether the search should be case-sensitive.
• withinRange (Range|null): If provided, the search is restricted to this specific range.
• wholeWordsOnly (boolean): If true, only matches that constitute whole words are returned.
• wrap (boolean): Whether to wrap the search (e.g., searching from the end of the document backwards).
• direction (string): The direction of the search ("forward" or "backward").
• wordOptions (Object|null): Custom word tokenization settings.
• characterOptions (Object|null): Custom character/whitespace handling settings.

When performing text-based operations, you can control how whitespace and collapsed characters are handled using characterOptions.

Available configuration keys:

• includeBlockContentTrailingSpace (boolean): Whether to include trailing spaces inside block elements.
• includeSpaceBeforeBr (boolean): Whether to include spaces preceding a <br> element.
• includeSpaceBeforeBlock (boolean): Whether to include spaces preceding a block element.
• includePreLineTrailingSpace (boolean): Whether to include trailing spaces in elements with white-space: pre-line.
• ignoreCharacters (string): A string of characters to be ignored during text operations.

Rangy provides a global config object to control its behavior. Key configuration options include:

• alertOnFail: Boolean. If true, Rangy will trigger a browser alert() if it fails to initialize or encounters a critical error.
• alertOnWarn: Boolean. If true, Rangy will trigger a browser alert() for warnings.
• preferTextRange: Boolean. Determines whether to prefer the legacy TextRange API over the standard Range API where available.
• autoInitialize: Boolean. Determines if Rangy should automatically initialize. This can be controlled by setting a global rangyAutoInitialize variable before Rangy loads.