# IndependenciaHighlighter

#### new IndependenciaHighlighter(element, optionsopt)

Source:
  - highlighters/independencia.js, line 45

Creates an IndependenciaHighlighter instance for functionality that focuses for highlight independence.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`element` | HTMLElement |  | DOM element to which highlighted will be applied.
`options` | object | <optional> | additional options. ###### Properties
Name | Type | Description
--- | --- | ---
`color` | string | highlight color.
`excludeNodes` | string | Node types to exclude when calculating offsets and determining where to inject highlights.
`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.
`normalizeElements` | boolean | 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.
`highlightedClass` | string | class added to highlight, 'highlighted' by default.
`contextClass` | string | class added to element to which highlighter is applied, 'highlighter-context' by default.
`namespaceDataAttribute` | string | Data attribute to identify highlights that belong to a particular highlight instance.
`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.
`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` | PreprocessDescriptors | function called after the user has carried out the action to trigger creation of highlights after making a text selection. This should be used to customise the highlight span wrapper with custom data attributes or styles required before the highlight is loaded into the DOM. This callback must return an array of highlight descriptors.
`onAfterHighlight` | OnAfterHighlightCallbackV2 | function called after highlight is created. Array of created wrappers is passed as param. This is called after the highlight has been created in the DOM.

### Methods

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

Source:
  - highlighters/independencia.js, line 294

Deserializes the independent form of 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

#### doHighlight(keepRange)

Source:
  - highlighters/independencia.js, line 91

Highlights current range.

##### Parameters:

Name | Type | Description
--- | --- | ---
`keepRange` | boolean | Don't remove range after highlighting. Default: false.

#### focusUsingId(id, descriptors)

Source:
  - highlighters/independencia.js, line 413

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` | object | The id of the highlight present in the class names of all elements in the DOM that represent the highlight. In order to utilise this functionality unique ids for highlights should be added to the class list in the highlight wrapper within the descriptors. You can do this in the onAfterHighlight callback when a highlight is first created. In the future it might be worth adding more flexiblity to allow for user-defined ways of storing ids to identify elements in the DOM. (e.g. choosing between class name or data attributes)
`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.

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

Source:
  - highlighters/independencia.js, line 210

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.
`dataAttr` | string | <optional> | Namespaced used to identify highlights for a specific highlighter instance.
`andSelf` | boolean | <optional> | if set to true and container is a highlight itself, add container to returned results. Default: true.
`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

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

Source:
  - highlighters/independencia.js, line 228

Returns true if element is a highlight.

##### Parameters:

Name | Type | Description
--- | --- | ---
`el` |  | element to check.
`dataAttr` |  | data attribute to determine if the element is a highlight

##### Returns:

Type
  boolean

#### normalizeHighlights()

Source:
  - highlighters/independencia.js, line 152

Normalizes highlights and the dom. Ensures text nodes within any given element node are merged together, elements with the
same ID next to each other are merged together and highlights with the same ID next to each other are merged together.

#### removeHighlights(element, id)

Source:
  - highlighters/independencia.js, line 169

Removes one highlight if an ID is provided, removes all highlights in the provided
element otherwise.

##### Parameters:

Name | Type | Description
--- | --- | ---
`element` | HTMLElement | element to remove highlights from
`id` | string | ID of highlight to remove Removes highlights from element using highlight ID. If no id is given, all highlights are removed.

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

Source:
  - highlighters/independencia.js, line 238

Serializes the highlight belonging to the ID.

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` |  | ID of the highlight to serialise

##### Returns:

- stringified JSON with highlights definition

Type
  string

### Type Definitions

#### HighlightDescriptor

Source:
  - highlighters/independencia.js, line 456

##### Properties:

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

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

In order to utilise this functionality unique ids for highlights should be added to the class list in the highlight
wrapper within the descriptors.
You can do this in the onAfterHighlight callback when a highlight is first created.

In the future it might be worth adding more flexiblity to allow for user-defined ways of storing ids to identify
elements in the DOM. (e.g. choosing between class name or data attributes)

##### Type:

- object