Class: TextHighlighter

TextHighlighter

TextHighlighter that provides text highlighting functionality to dom elements.


new TextHighlighter()

Source:

Methods


<static> createWrapper(options)

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.

Source:
Returns:
Type
HTMLElement

deserializeHighlights(json)

Deserializes highlights.

Parameters:
Name Type Description
json object

JSON object with highlights definition.

Source:
Throws:

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

Returns:
  • array of deserialized highlights.
Type
Array

destroy()

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

Source:

find(text [, caseSensitive])

Finds and highlights given text.

Parameters:
Name Type Argument Description
text string

text to search for

caseSensitive boolean <optional>

if set to true, performs case sensitive search (default: true)

Source:

focusUsingId(id, descriptors)

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.

Source:

getColor()

Returns highlighting color.

Source:
Returns:
Type
string

getHighlights(params)

Returns highlights from given container.

Parameters:
Name Type Description
params
Properties
Name Type Argument 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.

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.

Source:
Returns:
  • array of highlights.
Type
Array

highlightHandler()

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.

Source:

highlightRange(range, wrapper)

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

Parameters:
Name Type Description
range Range
wrapper HTMLElement
Source:
Returns:
  • array of created highlights.
Type
Array

isHighlight(el)

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

Parameters:
Name Type Description
el

element to check.

Source:
Returns:
Type
boolean

normalizeHighlights(highlights)

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.

Source:
Returns:
  • array of normalized highlights. Order and number of returned highlights may be different than
    input highlights.
Type
Array

registerDefaultEvents()

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

Source:

removeHighlights(element, id)

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.

Source:

serializeHighlights(id)

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.

Source:
Returns:
  • stringified JSON with highlights definition
Type
string

setColor(color)

Sets highlighting color.

Parameters:
Name Type Description
color string

valid CSS color.

Source:

Type Definitions


HighlightDescriptor

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
Properties:
Name Type Description
id string
serialisedDescriptor string
Source:

Class: TextHighlighter

TextHighlighter


new TextHighlighter(element [, options], registerEventsOnConstruction)

Creates TextHighlighter instance and binds to given DOM elements.

Parameters:
Name Type Argument Description
element HTMLElement

DOM element to which highlighted will be applied.

options object <optional>

additional options.

Properties
Name Type Description
version string

The version of the text highlighting functionality to use.
There are two 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

highlight color.

excludeNodes string

Node types to exclude when calculating offsets and determining where to inject highlights.

highlightedClass string

class added to highlight, 'highlighted' by default.

contextClass string

class added to element to which highlighter is applied,
'highlighter-context' by default.

useDefaultEvents boolean

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.

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.

Source:

Methods


<static> createWrapper(options)

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.

Source:
Returns:
Type
HTMLElement

deserializeHighlights(json)

Deserializes highlights.

Parameters:
Name Type Description
json object

JSON object with highlights definition.

Source:
Throws:

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

Returns:
  • array of deserialized highlights.
Type
Array

destroy()

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

Source:

find(text [, caseSensitive])

Finds and highlights given text.

Parameters:
Name Type Argument Description
text string

text to search for

caseSensitive boolean <optional>

if set to true, performs case sensitive search (default: true)

Source:

focusUsingId(id, descriptors)

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.

Source:

getColor()

Returns highlighting color.

Source:
Returns:
Type
string

getHighlights(params)

Returns highlights from given container.

Parameters:
Name Type Description
params
Properties
Name Type Argument 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.

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.

Source:
Returns:
  • array of highlights.
Type
Array

highlightHandler()

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.

Source:

highlightRange(range, wrapper)

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

Parameters:
Name Type Description
range Range
wrapper HTMLElement
Source:
Returns:
  • array of created highlights.
Type
Array

isHighlight(el)

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

Parameters:
Name Type Description
el

element to check.

Source:
Returns:
Type
boolean

normalizeHighlights(highlights)

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.

Source:
Returns:
  • array of normalized highlights. Order and number of returned highlights may be different than
    input highlights.
Type
Array

registerDefaultEvents()

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

Source:

removeHighlights(element, id)

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.

Source:

serializeHighlights(id)

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.

Source:
Returns:
  • stringified JSON with highlights definition
Type
string

setColor(color)

Sets highlighting color.

Parameters:
Name Type Description
color string

valid CSS color.

Source:

Type Definitions


HighlightDescriptor

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
Properties:
Name Type Description
id string
serialisedDescriptor string
Source: