Chrome Annotation Extension Template

Create your own Chrome extension to augment values with tooltips showing extra information about them.

Example use cases include:

1. resolve UUID values to entity information (either static data or query your own server)
2. annotate unix timestamps and UTC ISO8601 time signatures with a more user-friendly local date (example extension)
3. annotate currency values with conversions
4. add explanations on top of cryptic notation that you came up with (example of adding hints on top of cryptic infix operators)

Blog Post

See the accompanying blog post for a deeper explanation.

Steps

Step 1

Fork this repo.

Step 2: Modify the manifest.json

Specify what your extension's name is and specify on which domains it should run.

Step 3: Define a matching function

Specify a function that extracts your values of interest out of HTML text nodes. This function better be fast and it needs to return a list of matches. It should return [] if the HTML node has no interesting values and a one-element array if there is one. Currently only one value per text node is supported.

The returned value will then be passed to your resolution function.

UUID example:

function uuidMatchingFn(node) {
  // ignore very big text nodes
  // (we are periodically iterating over the whole document)
  if (node.data.length > 1000) {
    return false;
  } else {
    // we don't perform an exact match (/^...$/) since we want to be able
    // to annotate even text that might INCLUDE a UUID (e.g. per-entity resources)
    const uuidsInNode = node.data.match(new RegExp(uuidRegex, 'g')) || []
    // more than 1 match not interesting as it wouldn't be clear which UUID the tooltip is for
    // and splitting text nodes is beyond the scope for now
    return (uuidsInNode.length === 1) ? uuidsInNode : [];
  }
}

Step 4: Define a resolution function

The values that we discover in the HTML document then need to be resolved into HTML snippets to display to the user in the tooltip. The resolution function should be an asynchronous function that returns an HTML snippet (if the value does not correspond to any entity simply return an explanation to the user in HTML format).

UUID example:

async function uuidResolveFn(uuid) {
  const knownUUIDs = [
    { uuid: '7a18a230-f4d0-4fbb-b706-0a16479409a5', html: `The best <b>UUID</b> ever!` }
  ]
  const matchingResult = knownUUIDs.find(x => x.uuid === uuid);
  const html = matchingResult ? matchingResult.html : `<i>UNKNOWN UUID</i>`;
  await randomDelay(200, 2000);
  return html;
}

Step 5: Pass the two functions to the init() function

init({
  matchingFn: uuidMatchingFn,
  resolveFn: uuidResolveFn
})

UUID example

Step 6: Profit!

You got yourself a Chrome extension!

Now you can load your unpacked extension.

Step 7: Keep up to date

By only modifying manifest.json and content.js and reguarly merging the changes from this upstream repository you can take full advantage of any future changes in this template!