@xyfir/annotate-html NPM

Annotate HTML with annotations from xyAnnotations.

This is mostly a lower-level library to be used in other packages (like epubjs).

API

Check the source code and JSDOC comments for each module, they're heavily documented and should explain everything necessary.

The main methods you'll probably need are briefly described below.

import * as AnnotateHTML from '@xyfir/annotate-html';

`findMarkers()`

const markers = AnnotateHTML.findMarkers(html, chapter, items);

html: string - The HTML string to search for markers in
chapter: number - The index of the chapter within the book
items: object[] - The annotation set items to search
markers: object - Markers that point to matches for Before and After subsearches within the chapter

`buildString()`

const newHTML = AnnotateHTML.buildString({
  set,
  html,
  mode,
  action: (key, type) => `...`,
  chapter,
  markers
});

set: object
- The annotation set to insert
html: string
- The HTML string to insert annotations into
mode: number
- See the INSERT_MODES export.
action: function
- This is a template function that takes two parameters, key and type, and returns a string that will be used for the onclick or href attributes of the inserted element based on mode.
- key identifies the item being clicked with the following format: 'setId-itemId'.
- type is the type of highlight (should always be "annotation" unless you have some custom setup).
chapter: number
- The index of the chapter within the book
markers: object
- Markers that point to matches for Before and After subsearches within the book

`INSERT_MODES`

All inserted elements are given a class of xy-{type}, which usually should be xy-annotation unless you specified a custom type.

AnnotateHTML.INSERT_MODES = {
  // Wrap the matches within an element
  WRAP: {
    // <a href="...">{match}</a>
    LINK,
    // <span onclick="...">{match}</span>
    ONCLICK
  },
  // Add a reference at the end of the match
  REFERENCE: {
    // {match}<a href="..."><sup>xy</sup></a>
    LINK,
    // {match}<span onclick="..."><sup>xy</sup></span>
    ONCLICK
  }
};

AnnotateHTML.buildString({ ...
  mode: AnnotateHTML.INSERT_MODES.WRAP.LINK
... });