W3C home > Mailing lists > Public > public-annotation@w3.org > July 2015

JavaScript Anchoring Utility Libraries

From: Randall Leeds <randall@bleeds.info>
Date: Mon, 13 Jul 2015 18:10:18 +0000
Message-ID: <CAAL6JQjv+Fu36=GKbTeeuEa4XzJ8yWQSgqQ-YseqiY7CahwgcA@mail.gmail.com>
To: Web Annotation <public-annotation@w3.org>, "dev@list.hypothes.is" <dev@list.hypothes.is>, "annotator-dev@lists.okfn.org" <annotator-dev@lists.okfn.org>
As part of work I've been doing over the last couple months I've created
three JavaScript libraries that implement client-side support for some of
the Web Annotation Data Model selector types on HTML (+ embedded SVG)
documents.

The goals are three-fold:

1) Rewrite Hypothesis anchoring code to be better tested and more clear
2) Expose anchoring utilities to the widest possible audience (no
dependencies on Hypothesis or Annotator code)
3) Experiment with a scripting API for client-side anchoring

These modules expose one class each, all of them implementing an implicit
abstract interface for an anchor that looks like this:

Anchor.fromSelector
Static method to convert from a JavaScript Object to an instance

Anchor.fromRange
Static method to convert from a DOM Range to an instance

Anchor.prototype.toSelector
Method to convert from an instance to a JavaScript Object representation of
a Web Annotation Data Model selector

Anchor.prototype.toRange
Method to onvert from an instance to a DOM Range

Pseudocode for anchoring a selector:

var selector = JSON.parse(data);
// Possibly inspect the type of the selector
var anchor = SomeAnchorType.fromSelector(selector);
var range = anchor.toRange();

Pseudocode for describing a user selection as a selector:

var range = window.getSelection().getRangeAt(0);
var anchor = SomeAnchorType.fromRange(range);
var selector = anchor.toSelector();
var data = JSON.stringify(selector);

These are the libraries:

Fragment Selector: https://github.com/hypothesis/dom-anchor-fragment
Text Position Selector:
https://github.com/hypothesis/dom-anchor-text-position
Text Quote Selector: https://github.com/hypothesis/dom-anchor-text-quote

All of these have been published on npm as alpha versions, which means you
have to specify the version explicitly when installing them for now.

I would appreciate any feedback on these and I hope that they are useful
for implementations or discussion. I will publish 1.0 final versions of
these within the next few days, hopefully after I get positive feedback
from at least a couple readers.

Cheers
Received on Monday, 13 July 2015 18:10:55 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 18:54:38 UTC