Guide

Guide

TextHighlighter constructor

Consider following code:

var hltr = new TextHighlighter(el, options);

• el (mandatory) - is a HTML element to which highlighter is applied to. This means that highlighting is working only within this element.
• options (optional) - is an object with additional options, especially highlighter callback functions. For the full list of options see API reference.

If you love jQuery you may also use built-in jQuery wrapper:

$('#sandbox').textHighlighter(/* options */);
var hltr = $('#sandbox').getHighlighter()

Callbacks

There are three callback function which can be specified in constructor options:

• onBeforeHighlight - this function is called before any highlight is created. It receives range object as its only argument. This function should return boolean value. Return true to continue highlighting or false to prevent highlighting.
• onAfterHighlight - this function is called after highlighting is done. It receives three arguments: range, created highlights and a timestamp. Range is the same range object as in onBeforeHighlight. Second arguments is an array of created and normalized highlights (span tags). The last arguments is the timestamp. Please note that during single highlighting process it may be necessary to create multiple span elements. All these span elements get the same timestamp, so timestamps allow to group span elements in one logical highlight.
• onRemoveHighlight - this function is called before highlight is removed. Removing highlight is passed as arguments. This function should return true to finally remove the highlight or false to prevent removal.

Highlighting

Highlighting is done by wrapping selected text in span tags. Just select any text and a colorful highlight should appear.

You may also use find method, which finds and highlights all occurrences of given text.

Highlighting triggers onBeforeHighlight and onAfterHighlight callbacks.

Normalization

Highlighting process may require to wrap text in multiple span elements. These spans are normalized which ensures that highlighting is done with minimal possible number of span tags. Also highlights should not be nested if possible. This keeps DOM as clean as possible without redundant elements.

Obtaining highlights

Existing highlights can be obtained by getHighlights(params) method. In its simplest form it returns array of highlighted span tags in whole element the higlighter was applied to. It can be tweaked, however, by params object:

• container - returns highlights from this element. Default: the element the highlighter is applied to.
• andSelf - if set to true and container is a highlight itself, add container to returned results. Default: true.
• grouped - if set to true highlights are grouped by timestamp attribute and the method returns array of object. Each object represents a logical highlight and has the following form:

{
    chunks: Array[3]
    timestamp: "1419513807235"
    toString: function () { ... }
}

Where chunks is the array of span elements which belongs to the highlight, timestamp is the actual timestamp of the highlight and toString is method which returns text content gathered from each chunk.

Removing highlights

To remove highlights use removeHighlights([element]) method. If element is given, it removes highlights from that element. If element is highlight itself it is removed as well. If element is omitted, it removes highlights from whole element the highlighter was applied to.

This method triggers onRemoveHighlight callback.

Serialization

Serialization allows you to store all highlights in textual form:

var serialized = hltr.serializeHighlights();

Serialized highlights can be deserialized later:

hltr.deserializeHighlights(serialized);