Nacho Portmanteau Meltdown

    @xyfir/annotate-html

    2.0.2 • Public • Published

    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.

    Install

    npm i @xyfir/annotate-html

    DownloadsWeekly Downloads

    3

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    9.45 kB

    Total Files

    4

    Last publish

    Collaborators

    • xyfir