Global

Members

(constant) DATA_ATTR :string

Source:

Attribute added by default to every highlight.

Type:
  • string

(constant) IGNORE_TAGS :Array.<string>

Source:

Don't highlight content of these tags.

Type:
  • Array.<string>

(constant) TIMESTAMP_ATTR :string

Source:

Attribute used to group highlight wrappers.

Type:
  • string

Methods

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

Source:

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

Parameters:
Name Type Description
arr Array.<String>
Returns:
Type
Array.<String>

createWrapper(options, doc) → {HTMLElement}

Source:

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.
doc Document

the document to create the wrapper element with.
Returns:
Type
HTMLElement

dom(elopt) → {object}

Source:

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:

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:

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:

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:

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:

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, doc) → {string}

Source:

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.
doc Document

The document to create new elements in as a part of the process of
extracting highlighted text.
Returns:

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

Type
string

getHighlighterNamespace(element, namespaces)

Source:

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:

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:

Groups given highlights by timestamp.

Parameters:
Name Type Description
highlights Array
timestampAttr string
Returns:

Grouped highlights.

Type
Array

haveSameColor(a, b) → {boolean}

Source:

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:

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:

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:

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:

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:
Parameters:
Name Type Description
offsetWithinNode number
text string
Returns:
Type
number

normaliseText(text)

Source:

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:

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:

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:

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:

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:

Returns array without duplicated values.

Parameters:
Name Type Description
arr Array
Returns:
Type
Array

validateIndependenciaDescriptors(descriptors) → {boolean}

Source:

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:
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:

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:
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:
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