hypothesis/annotator — pull request #18 by csillag (2013-11-15 17:35:45+00:00)
Title: Introducing typed anchor support

This work involves a comprehensive overhaul of two-phase anchoring, and introduces typed anchors.

Some concepts to learn and keep in mind:

* We have `anchoring strategies`, which can create `anchors` out of the `targets` of the annotations, using the data in the `selectors`, and also utilizing the `document access strategy` in place, to inspect the document.
* Anchors are created `virtual`, which means that they don't exist inside the DOM yet; they just know where they should go.
* Anchors are objects. There can be different kinds of anchors, implemented in different classes.
* Any anchoring strategy is free to produce any kind of anchor.
* When the conditions are right (for example, the relevant part of the DOM is rendered), anchors can be `realized`, which means that the corresponding `highlights` are created in the DOM.
* Anchors can also be `virtualized` again, which means that the highlights are removed from the DOM. (This can be done on a per-page basis.)
* Highlights are objects. There can be different kinds of highlights, implemented in different classes.
* The highlight classes are responsible for all actual DOM manipulation.
* Highlights are created by anchors. Typically, a given type of anchor always creates a given type of highlight.
* An anchor can several highlights, if it spans several pages.
* We always think about the document as if it had pages. Individual pages can be rendered an un-rendered at will.
* Simple HTML documents have only one page, which is always rendered.
* When a page is rendered, all the anchors on it are realized. (The highlights are created.)
* When a page is un-rendered, the anchors are (partially) virtualized. (The highlights disappear.)
* An anchor can be partially realized, if some of it's pages are rendered, and some are not.
* All the code of Annotator (and H) outside the actual anchors/highlights is forbidden to assume anything about the internals of anchors/highlights; they can only access them via the interface defined on the abstract classes. (Anchor and Highlight)
* Annotator core does not contain any anchoring strategy, or anchor, or highlight implementation. It understands no selectors, and can't create any annotations by itself.
* The ability to create and anchor text annotations have been moved to the TextAnchors plugin, which
* Recognizes the new selection upon releasing of the mouse button
* Can create targets with selectors appropriate for text anchors
* Has the TextRangeAnchor class (the anchor implementation for text ranges, defined by start and end character offsets)
* Has the TextHighlight class (the highligh implementation for text ranges)
* Has the two basic anchoring strategies for text (xpath and position based.)
* Both anchoring strategies defined here produce TextRangeAnchors, which in turn produce TextHighlights when realized.
* To get even more functionality, load the FuzzyTextAnchors plugin, too, which
* adds two more anchoring strategies, working with the same selectors, and producing the and anchors.

With this, Annotator Core has been freed from (almost) all the text-specific parts, which have been moved to the TextAnchors and FuzzyTextAnchors plugins. Other plugins can now implement other kind of anchors easily.

* * *

This PR obsoletes both #16 and #17, and incorporate the changes based on the feedback.

See also this diagram about how the components work together:

![components](http://hypothes.is/wp-content/uploads/2013/11/components.png)

This diagram is annotated; open the image in a new frame, and launch the bookmarklet from [image3.dokku](http://image3.dokku.hypothes.is/) (or any later dokku instance, which have image support).