@xyfir/annotate-html

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
... });

Usage / Examples

You should check the epubjs package (find-markers.js and insert.js specifically) for a detailed, working example of this package being used.