IndependenciaHighlighter

IndependenciaHighlighter

new IndependenciaHighlighter(element, optionsopt)

Source:

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.
highlightWhiteSpaceChars boolean

Whether or not to deserialise highlights into the DOM when they only contain white space characters.
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:

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:

Highlights current range.

Parameters:
Name Type Description
keepRange boolean

Don't remove range after highlighting. Default: false.

focusUsingId(id, descriptors)

Source:

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:

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:

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:

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:

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:

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