# TextHighlighter

TextHighlighter that provides text highlighting functionality to dom elements.

## Constructor

#### new TextHighlighter(element, optionsopt, registerEventsOnConstruction)

Source:
  - text-highlighter.js, line 25

Creates TextHighlighter instance and binds to given DOM elements.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`element` | HTMLElement |  | DOM element to which highlighted will be applied.
`options` | object | <optional> | additional options. ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`version` | string |  |  | The version of the text highlighting functionality to use. There are three options: primitivo (v1-2014) is for the initial implementation using interdependent highlight locators. (Lots of issues for requirements beyond simple all or nothing highlights) independencia (v2-2019) is for an improved implementation focusing on making highlights independent from eachother and other element nodes within the context DOM object. v2 uses data attributes as the source of truth about the text range selected to create the original highlight. This allows us freedom to manipulate the DOM at will and handle overlapping highlights a lot better.
`color` | string | <optional> | `#ffff7b` | highlight color.
`excludeNodes` | Array.<string> | <optional> | `["SCRIPT", "STYLE", "SELECT", "OPTION", "BUTTON", "OBJECT", "APPLET", "VIDEO", "AUDIO", "CANVAS", "EMBED", "PARAM", "METER", "PROGRESS"]` | Node types to exclude when calculating offsets and determining where to inject highlights.
`highlightedClass` | string | <optional> | `highlighted` | class added to highlight, 'highlighted' by default.
`namespaceDataAttribute` | string | <optional> | `data-highlighted` | Namespace data attribute to identify highlights for a particular highlighter instance.
`excludeWhiteSpaceAndReturns` | boolean |  |  | Whether or not to exclude white space and carriage returns while calculating text content offsets. The white space that is excluded is only the white space that comes directly after carriage returns.
`priorities` | Record.<string, number> |  |  | Defines priorities for multiple highlighters, the keys are the namespaces for highlighters and the values are the priorities where the higher number has the higher priority. For example { userHighlights: 1, staticHighlights: 2 } would mean that highlights from the "static" highlighter will always appear above highlights from the "user" highlighter.
`contextClass` | string | <optional> | `highlighter-context` | class added to element to which highlighter is applied, 'highlighter-context' by default.
`useDefaultEvents` | boolean | <optional> | `true` | Whether or not to use the default events to listen for text selections. The default events are "mouseup" and "touchend". Set this to false and register TextHiglighter.highlightHandler with your own events. It is down to you to remove the listener from your custom events when destroying instances of the text highlighter.
`normalizeElements` | boolean | <optional> | `false` | Whether or not to normalise elements on the DOM when highlights are created, deserialised into the DOM, focused and deselected. Normalising events has a huge performance implication when enabling highlighting for a root element that contains thousands of nodes. This only applies for the independencia v2-2019 version.
`keepRange` | boolean | <optional> | `false` | Whether or not to keep the highlight selection after highlights are created. If set to true then the selection will stay active.
`onRemoveHighlight` | function |  |  | function called before highlight is removed. Highlight is passed as param. Function should return true if highlight should be removed, or false - to prevent removal.
`onBeforeHighlight` | function |  |  | function called before highlight is created. Range object is passed as param. Function should return true to continue processing, or false - to prevent highlighting.
`preprocessDescriptors` | function |  |  | function called when a user has made a selection to create a highlight, this is called before the highlight are loaded into the DOM. This should be used to carry out tasks like customising the span wrapper used to inject highlights with data attributes specific to your application. (This is only utilised by v2-2019 onwards)
`onAfterHighlight` | function |  |  | function called after highlight is created. Array of created wrappers is passed as param. This is called once the highlights have been loaded into the DOM. (The callback interface differs between versions, see specific highlighter classes for more info)
`registerEventsOnConstruction` | boolean |  | Whether or not to attempt to register events when the text highlighter is first instantiated. In the case options.useDefaultEvents is false, even with this enabled the events won't be registered, this is only relevant if you want more control and register events at a later point.

### Methods

#### (static) createWrapper(options) → {HTMLElement}

Source:
  - text-highlighter.js, line 34

Creates wrapper for highlights.
TextHighlighter instance calls this method each time it needs to create highlights and pass options retrieved
in constructor.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | object | the same object as in TextHighlighter constructor.

##### Returns:

Type
  HTMLElement

#### deserializeHighlights(json) → {Array}

Source:
  - text-highlighter.js, line 283

Deserializes highlights.

##### Parameters:

Name | Type | Description
--- | --- | ---
`json` | object | JSON object with highlights definition.

##### Throws:

exception when can't parse JSON or JSON has invalid structure.

##### Returns:

- array of deserialized highlights.

Type
  Array

#### destroy()

Source:
  - text-highlighter.js, line 145

Permanently disables highlighting.
Unbinds events and remove context element class.

#### find(text, caseSensitiveopt)

Source:
  - text-highlighter.js, line 293

Finds and highlights given text.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`text` | string |  | text to search for
`caseSensitive` | boolean | <optional> | if set to true, performs case sensitive search (default: true)

#### focusUsingId(id, descriptors)

Source:
  - text-highlighter.js, line 341

Focuses a highlight, bringing it forward in the case it is sitting behind another
overlapping highlight, or a highlight it is nested inside.

This is only supported by independencia (v2-2019) and onwards.
For older versions, this will simply do nothing.

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` | string | The id of the highlight present in the class names of all elements in the DOM that represent the highlight.
`descriptors` | string | Optional serialised descriptors, useful in the case a highlight has no representation in the DOM where empty highlight wrapper nodes are removed to use less dom elements.

#### getColor() → {string}

Source:
  - text-highlighter.js, line 218

Returns highlighting color.

##### Returns:

Type
  string

#### getHighlights(params) → {Array}

Source:
  - text-highlighter.js, line 248

Returns highlights from given container.

##### Parameters:

Name | Type | Description
--- | --- | ---
`params` |  | ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`container` | HTMLElement | <optional> | return highlights from this element. Default: the element the highlighter is applied to.
`andSelf` | boolean | <optional> | if set to true and container is a highlight itself, add container to returned results. Default: true.
`dataAttr` | string | <optional> | Namespaced used to identify highlights for a specific highlighter instance.
`grouped` | boolean | <optional> | if set to true, highlights are grouped in logical groups of highlights added in the same moment. Each group is an object which has got array of highlights, 'toString' method and 'timestamp' property. Default: false.

##### Returns:

- array of highlights.

Type
  Array

#### highlightHandler()

Source:
  - text-highlighter.js, line 171

Listener to events that can trigger the creation of a highlight.
By default this is triggered on "mouseup" and "touchend" events.
If you disable the default events by setting options.useDefaultEvents
you will need to register this handler with your own events and make sure you
remove the listener when you destroy the instance of the TextHighlighter as well.

#### highlightRange(range, wrapper) → {Array}

Source:
  - text-highlighter.js, line 187

Highlights range.
Wraps text of given range object in wrapper element.

##### Parameters:

Name | Type | Description
--- | --- | ---
`range` | Range |
`wrapper` | HTMLElement |

##### Returns:

- array of created highlights.

Type
  Array

#### isHighlight(el, dataAttr) → {boolean}

Source:
  - text-highlighter.js, line 260

Returns true if element is a highlight.
All highlights have 'data-highlighted' attribute.

##### Parameters:

Name | Type | Description
--- | --- | ---
`el` |  | element to check.
`dataAttr` |  | namespace used to identify highlights for a specific highlighter instance.

##### Returns:

Type
  boolean

#### normalizeHighlights(highlights) → {Array}

Source:
  - text-highlighter.js, line 200

Normalizes highlights. Ensure at least text nodes are normalized, carries out some flattening and nesting
where necessary.

##### Parameters:

Name | Type | Description
--- | --- | ---
`highlights` | Array | highlights to normalize.

##### Returns:

- array of normalized highlights. Order and number of returned highlights may be different than
  input highlights.

Type
  Array

#### registerDefaultEvents()

Source:
  - text-highlighter.js, line 158

Registers the default event listeners that trigger the proecss
of creating a highlight.

#### removeHighlights(element, id)

Source:
  - text-highlighter.js, line 230

Removes highlights from element. If element is a highlight itself, it is removed as well.
If no element is given, all highlights all removed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`element` | HTMLElement | element to remove highlights from. if empty, the root element of the highlighter will be used.
`id` | string | The unique id of a highlight represented by a collection of elements.

#### serializeHighlights(id) → {string}

Source:
  - text-highlighter.js, line 272

Serializes all highlights in the element the highlighter is applied to.
the id is not used in the initial version of the highlighter.

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` | string | The unique identifier grouping a set of highlight elements together.

##### Returns:

- stringified JSON with highlights definition

Type
  string

#### setColor(color)

Source:
  - text-highlighter.js, line 209

Sets highlighting color.

##### Parameters:

Name | Type | Description
--- | --- | ---
`color` | string | valid CSS color.

### Type Definitions

#### HighlightDescriptor

Source:
  - text-highlighter.js, line 353

##### Properties:

Name | Type | Description
--- | --- | ---
`id` | string |
`serialisedDescriptor` | string |

Deselects a highlight, bringing any nested highlights in the list of descriptors
forward.

This is only supported by independencia (v2-2019) and onwards.
For older versions, this will simply do nothing.

##### Type:

- object