# Global

##

### Members

#### (constant) DATA_ATTR :string

Source:
  - config.js, line 5

Attribute added by default to every highlight.

##### Type:

- string

#### (constant) IGNORE_TAGS :Array.<string>

Source:
  - config.js, line 19

Don't highlight content of these tags.

##### Type:

- Array.<string>

#### (constant) TIMESTAMP_ATTR :string

Source:
  - config.js, line 11

Attribute used to group highlight wrappers.

##### Type:

- string

### Methods

#### arrayToLower(arr) → {Array.<String>}

Source:
  - utils/arrays.js, line 18

Returns array of strings with all strings converted to lower case.

##### Parameters:

Name | Type | Description
--- | --- | ---
`arr` | Array.<String> |

##### Returns:

Type
  Array.<String>

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

Source:
  - utils/highlights.js, line 100

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

#### dom(elopt) → {object}

Source:
  - utils/dom.js, line 11

Utility functions to make DOM manipulation easier.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`el` | Node | HTMLElement | <optional> | base DOM element to manipulate

##### Returns:

Type
  object

#### extractRangeRelativeToRootElement(range, rootElement) → {Range|null}

Source:
  - utils/highlights.js, line 885

Extracts a sub-range from a given window selection range
that only includes the given root element and its descendants.

##### Parameters:

Name | Type | Description
--- | --- | ---
`range` | RangeLite | The current text selection range for the window.
`rootElement` | HTMLElement | The root element to extract a sub-range for.

##### Returns:

The sub-range or null if rootElement is not in the text selection.

Type
  Range | null

#### findHigherPriorityHighlights(rootElement, node, priorities, namespaceDataAttribute) → {Array.<HTMLElement>}

Source:
  - utils/highlights.js, line 685

Collects all the higher priority highlight nodes
when trying to focus or deserialise a portion of a highlight
into a given DOM node.

##### Parameters:

Name | Type | Description
--- | --- | ---
`rootElement` | HTMLElement | The parent element.
`node` | HTMLElement | The current node.
`priorities` | Record.<string, number> | The priorities for multiple highlighters.
`namespaceDataAttribute` | string | The namespace data attribute for highlights for a provided text highlighter instance.

##### Returns:

Type
  Array.<HTMLElement>

#### findNodesAndOffsets(highlight, parentNode, excludeNodeNames, excludeWhiteSpaceAndReturns) → {NodesAndOffsetsResult}

Source:
  - utils/highlights.js, line 217

Determine where to inject a highlight based on it's offset.
A highlight can span multiple nodes, so in here we accumulate
all those nodes with offset and length of the content in the node
included in the highlight.

The normalisedOffset returned for each node when excludeWithSpaceAndReturns
is set to true represents the normalised offset in the original text and NOT
the normalised text.

##### Parameters:

Name | Type | Description
--- | --- | ---
`highlight` | * |
`parentNode` | * |
`excludeNodeNames` | * |
`excludeWhiteSpaceAndReturns` | boolean |

##### Returns:

Type
  NodesAndOffsetsResult

#### getFirstDescendantTerminalNode(rootNode) → {Node}

Source:
  - utils/highlights.js, line 926

Finds the first descendant node without any children
of it's own starting with the given root node.

##### Parameters:

Name | Type | Description
--- | --- | ---
`rootNode` | Node | The root node from which to find the first descendant terminal node for.

##### Returns:

the first descendant terminal node.

Type
  Node

#### getHighlightedTextForRange(range) → {string}

Source:
  - utils/highlights.js, line 562

Collects the human-readable highlighted text for all nodes in the selected range.

##### Parameters:

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

##### Returns:

The human-readable highlighted text for the given range.

Type
  string

#### getHighlightedTextRelativeToRoot(params) → {string}

Source:
  - utils/highlights.js, line 582

Collects the human-readable highlighted text for all nodes from the start text offset
relative to the root element.

##### Parameters:

Name | Type | Description
--- | --- | ---
`params` | Object | The root-relative parameters for extracting highlighted text.

##### Returns:

The human-readable highlighted text for the given root element, offset and length.

Type
  string

#### getHighlighterNamespace(element, namespaces)

Source:
  - utils/highlights.js, line 669

Returns the namespaces for the provided element given a list of namespaces

##### Parameters:

Name | Type | Description
--- | --- | ---
`element` | HTMLElement |
`namespaces` | Array.<string> |
`` | string |

#### getLastDescendantTerminalNode(rootNode) → {Node}

Source:
  - utils/highlights.js, line 942

Finds the last descendant node without any children
of it's own starting with the given root node.

##### Parameters:

Name | Type | Description
--- | --- | ---
`rootNode` | Node | The root node from which to find the last descendant terminal node for.

##### Returns:

the last descendant terminal node.

Type
  Node

#### groupHighlights(highlights, timestampAttr) → {Array}

Source:
  - utils/highlights.js, line 473

Groups given highlights by timestamp.

##### Parameters:

Name | Type | Description
--- | --- | ---
`highlights` | Array |
`timestampAttr` | string |

##### Returns:

Grouped highlights.

Type
  Array

#### haveSameColor(a, b) → {boolean}

Source:
  - utils/highlights.js, line 89

Returns true if elements a i b have the same color.

##### Parameters:

Name | Type | Description
--- | --- | ---
`a` | Node |
`b` | Node |

##### Returns:

Type
  boolean

#### isClosestHighlightParent(node, rootElement, dataAttr, id) → {boolean}

Source:
  - utils/highlights.js, line 718

Determines whether the highlight with the provided unique id is the closest parent
to the provided node of all the potential highlight wrappers.

In the case an id is not provided it will simply check if any highlight for the given
dataAttr namespace is the closest parent.

##### Parameters:

Name | Type | Default | Description
--- | --- | --- | ---
`node` | HTMLElement |  | The element we need to get parent information for.
`rootElement` | HTMLElement |  | The root element of the context to stop at.
`dataAttr` | string |  | The namespace data attribute for highlights for a provided text highlighter instance.
`id` | string | `null` | The unique id of the collection of elements representing a highlight.

##### Returns:

Type
  boolean

#### isHighestPriority(highlighterNamespace, priorities)

Source:
  - utils/priorities.js, line 11

Determines whether the provided highlighter has
the highest priority of a set of highlighters applied to
the same document.

##### Parameters:

Name | Type | Description
--- | --- | ---
`highlighterNamespace` | string |
`priorities` | Record.<string, number> |

##### Returns:

boolean

#### nodesInBetween(startNode, endNode) → {Array.<HTMLElement>}

Source:
  - utils/highlights.js, line 431

Gets all the nodes in between the provided start and end.

##### Parameters:

Name | Type | Description
--- | --- | ---
`startNode` | HTMLElement |
`endNode` | HTMLElement |

##### Returns:

Nodes that live in between the two.

Type
  Array.<HTMLElement>

#### normaliseBasedOnPrevSibling(node, parentNode, text) → {string}

Source:
  - utils/highlights.js, line 173

Checks whether previous siblings end with a carriage return followed by
zero or more whitespaces and selects the function that should be used to
normalise the text.

##### Parameters:

Name | Type | Description
--- | --- | ---
`node` | Node |
`parentNode` | Node |
`text` | string |

##### Returns:

Type
  string

#### normaliseOffset(offsetWithinNode, text) → {number}

Source:
  - utils/highlights.js, line 192

##### Parameters:

Name | Type | Description
--- | --- | ---
`offsetWithinNode` | number |
`text` | string |

##### Returns:

Type
  number

#### normaliseText(text)

Source:
  - utils/highlights.js, line 143

Deals with normalising text for when carriage returns and white space
that directly follows should be ignored.

##### Parameters:

Name | Type | Description
--- | --- | ---
`text` | string |

#### normaliseTextWithLeadingSpaces(text) → {string}

Source:
  - utils/highlights.js, line 157

Deals with normalising text for when carriage returns and white space
that directly follows or when white space and white space that directly
follows should be ignored.

##### Parameters:

Name | Type | Description
--- | --- | ---
`text` | string |

##### Returns:

Type
  string

#### refineRangeBoundaries(range) → {object}

Source:
  - utils/highlights.js, line 31

Takes range object as parameter and refines it boundaries

##### Parameters:

Name | Type | Description
--- | --- | ---
`range` |  |

##### Returns:

refined boundaries and initial state of highlighting algorithm.

Type
  object

#### scaleFromTransformMatrix(transformMatrix) → {number}

Source:
  - utils/transform.js, line 8

Extracts the scale from a 2D transform matrix.

##### Parameters:

Name | Type | Description
--- | --- | ---
`transformMatrix` | string | The 2D transform matrix.

##### Returns:

The combined scale element of the transform.

Type
  number

#### sortByDepth(arr, descending)

Source:
  - utils/highlights.js, line 77

Sorts array of DOM elements by its depth in DOM tree.

##### Parameters:

Name | Type | Description
--- | --- | ---
`arr` | Array.<HTMLElement> | array to sort.
`descending` | boolean | order of sort.

#### unique(arr) → {Array}

Source:
  - utils/arrays.js, line 6

Returns array without duplicated values.

##### Parameters:

Name | Type | Description
--- | --- | ---
`arr` | Array |

##### Returns:

Type
  Array

#### validateIndependenciaDescriptors(descriptors) → {boolean}

Source:
  - utils/highlights.js, line 869

Validation for descriptors to ensure they are of the correct format to be used
by the Independencia highlighter.

##### Parameters:

Name | Type | Description
--- | --- | ---
`descriptors` | array | The descriptors to be validated.

##### Returns:

- if the descriptors are valid or not.

Type
  boolean

### Type Definitions

#### NodeInfo

Source:
  - utils/highlights.js, line 744

##### Properties:

Name | Type | Description
--- | --- | ---
`nodeInfo.node` | HTMLElement | The html element (This will in most cases be a text node)
`nodeInfo.offset` | number | The offset within the node to be highlighted
`nodeInfo.length` | number | The length within the node that should be highlighted.

Focuses a set of highlight elements for a given id by ensuring if it has descendants that are highlights
it is moved inside of the innermost highlight.

The innermost highlight's styles will be applied and will be visible to the user
and given the "focus".

To focus the red highlight the following:

--
----
------
---------- Highlighted text

becomes:

--
----
------
-------- Highlighted text

and

--
---- Some text only highlighted in red
----
------ Text in blue and red
------
---------- Rest of the highlight in red, green and blue

becomes

--
---- Some text only highlighted in red
--
----
------ Text in blue and red
----
------
-------- Rest of the highlight in red, green and blue

##### Type:

- object

#### onAfterHighlightCallbackV1(range, highlights, timestamp)

Source:
  - highlighters/primitivo.js, line 13

PrimitivoHighlighter that provides text highlighting functionality to dom elements
for simple use cases.

##### Parameters:

Name | Type | Description
--- | --- | ---
`range` | Range |
`highlights` | Array.<HTMLElement> |
`timestamp` | number |

#### OnAfterHighlightCallbackV2(range, highlightDescriptors, timestamp, range, highlightDescriptors, timestamp, meta) → {PreprocessDescriptorsResult}

Source:
  - highlighters/independencia.js, line 17

##### Properties:

Name | Type | Description
--- | --- | ---
`0` | string | The span wrapper injected for the highlight.
`1` | string | The highlighted text.
`2` | number | The text offset relevant to the root element of a highlight.
`3` | number | Length of highlight.
`descriptors` | Array.<HlDescriptor> |
`meta` | Object | Any application-specific meta data created in the preprocessing stage that is used after highlights have been created.

IndependenciaHighlighter that provides text highlighting functionality to dom elements
with a focus on removing interdependence between highlights and other element nodes in the context element.

##### Parameters:

Name | Type | Description
--- | --- | ---
`range` | Range |
`highlightDescriptors` | Array.<HlDescriptor> |
`timestamp` | number |
`range` | Range |
`highlightDescriptors` | Array.<HlDescriptor> |
`timestamp` | number |
`meta` | Object |

##### Returns:

Type
  PreprocessDescriptorsResult

#### RangeLite

Source:
  - utils/highlights.js, line 1

##### Properties:

Name | Type | Description
--- | --- | ---
`node` | Node | The DOM node that makes up a portion of a highlight.
`offset` | number | Offset within the node for a portion of a highlight.
`normalisedOffset` | number | Offset within the node's original text that excludes characters that are normalised away.
`length` | number | Length of the portion highlighted in the node.
`normalisedText` | string | Node's text content stripped of carriage returns and white spaces that follow carriage returns.
`nodesAndOffsets` | Array.<NodeAndOffset> |
`allText` | string |
`startContainer` | HTMLElement |
`startOffset` | number |
`endContainer` | HTMLElement |
`endOffset` | number |

##### Type:

- Object