Basic Options & APIs

Options

`highlighter = new Highlighter([opts])`

Create a new highlighter instance.

opts will be merged into the default options (shown bellow).

{
    $root: document.documentElement,    // root element for addEventlistener / DFS / ...
    exceptSelectors: null,              // if an element matches the selector, it won't be highlighted
    style: {
        className: 'highlight-wrap'     // the classname for wrap element
    }
}

exceptSelectors needs null or Array<string>. It suports id selectors, class selectors and tag selectors.

For example, to skip h1 and .title elements:

var highlighter = new Highlighter({
    exceptSelectors: ['h1', '.title']
});

APIs

`highlighter.run()`

Start auto-highlighting. When the user select a text segement, a highlighting will be added to the text automatically.

`highlighter.stop()`

It will stop the auto-highlighting.

`highlighter.dispose()`

When you don't want the highlighter anymore, remember to call it first. It will remove some listeners and do some cleanup.

`highlighter.fromRange(range)`

You can pass a Range object to it and then it will be highlighted. You can use window.getSelection().getRangeAt(0) to get a range object or use document.createRange() to create a new range.

Use it as bellow:

const selection = window.getSelection();
if (selection.isCollapsed) {
    highlighter.fromRange(selection.getRangeAt(0));
}

`highlighter.fromStore(start, end, text, id)`

Mostly, you use this api to highlight text by the persisted infomation stored from backend.

These four values are from the HighlightSource object. HighlightSource object is a special object created by web-highlighter when highlighted area created. For persistence in backend (database), it's necessary to find a data structure to represent a dom node. This structure is called HighlightSource in web-highlighter.

Four attributes' meanings:

start Object: meta info about the beginning element
end Object: meata info about then end element
text string: text content
id string: unique id

`highlighter.remove(id)`

Remove (clean) a highlighted area by it's unique id. The id will be generated by web-highlighter by default. You can also add a hook for your own rule. Hooks doc here.

`highlighter.removeAll()`

Remove all highlighted areas belonging to the root.

`highlighter.addClass(classname, id)`

Add a classname for highlighted areas (wrap elements) by unique id. You can change a highlighted area's style by using this api.

`highlighter.removeClass(classname, id)`

Remove the classname by unique id. It's highlighter.addClass's inverse operation.

`highlighter.getDoms([id])`

Get all the wrap nodes in a highlighted area. A highlighted area may contain many segments. It will return all the dom nodes wrapping these segements.

If the id is not passed, it will return all the areas' wrap nodes.

`highlighter.getIdByDom(node)`

If you have a wrap node, it can return the unique highlight id for you.

Event Listener

web-highlighter use listeners to handle the events.

e.g.

var highlighter = new Highlighter();
highlighter.on(Highlighter.event.CREATE, function (data, inst, e) {
    // ...
});

The callback function will receive three parameters:

data any: event data
inst Highligher: current Highligher instance
e Event: some event is triggered by the browser (such as click), web-highlighter will expose it

Highlighter.event is EventType type. It contains：

EventType.CLICK: click the highlighted area
EventType.HOVER: mouse enter the highlighted area
EventType.HOVER_OUT: mouse leave the highlighted area
EventType.CREATE: a highlighted area is created
EventType.REMOVE: a highlighted area is removed

Different event has different data. Attributes below:

`EventType.CLICK`

name	description	type
`id`	the highlight id	string

`EventType.HOVER`

name	description	type
`id`	the highlight id	string

`EventType.HOVER_OUT`

name	description	type
`id`	the highlight id	string

`EventType.CREATE`

no parameter e

name	description	type
`source`	`HighlightSource` object	Array
`type`	the reason for creating	string

source is a HighlightSource object. It is an object created by web-highlighter when highlighted area created. For persistence in backend (database), it's necessary to use a data structure which can be serialized (JSON.stringify()) to represent a dom node in browsers. HighlightSource is the data structure designed for this.

type explains why a highlighted area is be created. Now type has two possible values: from-input and from-store. from-input shows that a highlighted area is created because of user's selection. from-store means it from a storage.

`EventType.REMOVE`