Class Applier Module

5. Documentation for Class Applier module

Documentation Home

Class Applier Module

This module adds, removes and toggles classes on all text nodes within a Range or Selection.

You can see a live example of this module in action here.

Example

<script type="text/javascript">
    var cssApplier;

    window.onload = function() {
        rangy.init();
        cssApplier = rangy.createCssClassApplier("someClass", {normalize: true});
    });
</script>

<input type="button" value="Toggle someClass on selection" onclick="cssApplier.toggleSelection();">

API

rangy.createCssClassApplier(String theClass[Object options[, Array tagNames]](,))

=options parameter new in v1.2=

=tagNames parameter new in v1.1=

Creates and returns a CssClassApplier object. Elements created by this object are given the class theClass. Each property of the options parameter object is optional and uses the appropriate default value if not specified. The available properties are:

• elementTagName: The tag name of the element to use for surrounding text. This may be any inline element that may contain text. The default is "span".
• elementProperties: An object containing properties that are copied to each element created to surround text
• ignoreWhiteSpace: Boolean value indicating whether to ignore insignificant white space text nodes (such as a line break and/or indentation between <p> tags in the HTML source of the page). The default is true.
• applyToEditableOnly: Boolean value indicating whether to only apply the class to editable content (contentEditable true or designMode "on"). The default is false.
• normalize: Boolean value indicating whether the CssClassApplier will merge adjacent text nodes and adjacent spans marked with its own unique class whenever it acts on a range or selection. As per the normalize function parameter in Rangy 1.1.

From version 1.1, you can also specify a list of tag names corresponding to elements to which the class can be applied. This may either be an array (such as ["b", "strong", "a"]("span",)) or a comma-separated string (such as "span, b, strong, a"). If omitted, the default is "span". You may alternatively specify "*" to indicate that the class may be applied to any element that may contain text. This is not recommended, however: when an element is partially selected, Rangy splits and copies the element, and if that element is block level (such as <p>), it will change the layout. This is a limitation that will likely be rectified in a future version.

Note that prior to version 1.1, elements created by a CssClassApplier object were given an additional class unique to the object whose purpose is to identify elements that the object may interact with. Thanks to improvements to this module, this no longer happens in version 1.1.

CssClassApplier API

applyToSelection([[Window|win]])

Surrounds all text nodes within the selection for the specified window with <span> elements with this CssClassApplier's class. If no window is provided, the current window's selection is used.

---

undoToSelection([[Window|win]])

Removes this CssClassApplier's class from all text within the selection for the specified window. If no window is provided, the current window's selection is used.

---

isAppliedToSelection([[Window|win]])

Returns a Boolean indicating whether all of the text contained within the selection for the specified window is contained within <span> elements with this CssClassApplier's class. If no window is provided, the current window's selection is used.

---

toggleSelection([[Window|win]])

Applies this CssClassApplier's class to all of the text contained within the selection for the specified window unless all the text already has the class, in which case it is removed. If no window is provided, the current window's selection is used.

---

applyToRange(Range range)

Surrounds all text nodes within the specified Rangy range with <span> elements with this CssClassApplier's class.

---

undoToRange(Range range)

Removes this CssClassApplier's class from all text within the specified Rangy range.

---

isAppliedToRange(Range range)

Returns a Boolean indicating whether all of the text contained within the specified Rangy range is contained within <span> elements with this CssClassApplier's class.

---

toggleRange(Range range)

Applies this CssClassApplier's class to all of the text contained within the specified Rangy range unless all the text already has the class, in which case it is removed.

---

detach([[Document|doc]])

=Deprecated from v1.1=

Removes this CssClassApplier's unique class from all elements within the specified document. If no document is provided, the current document is used.

Since no unique classes are used from version 1.1, this method no longer has any effect.