[annotator-dev] Annotator architecture evolution

[Robert Casties]

Hi Nick,

On 24.06.13 18:04, Nick Stenning wrote:
> My primary concern is making integrators' lives easier.
> 
> Specifically, that means looking at how people currently use Annotator, and
> how with appropriate changes to the internal architecture they would be
> able to work faster and more productively.

That's really cool. I already liked the current architecture that
prevented me from having to write my own edit-annotation-text,
store-annotation and display-annotation-text code with optional markdown
for free!

But I had to hack some hooks into the core code when I tried to
integrate my digilib image annotation plugin with Annotator:

<https://github.com/robcast/annotator/blob/master/src/plugin/digilibintegrator.coffee>

and copy the auth plugin, to be able to send data (i.e. username and
password) and place a hook with the token request:

<https://github.com/robcast/annotator/blob/master/src/plugin/authlogin.coffee>

> # What's wrong right now?
> 
> ## UI coupling
> 
> Implementing your own UI is difficult. The current highlighter, editor and
> viewer are quite tightly bound to core Annotator and this has made life
> difficult for Hypothesis, AustESE, and others.

I had to integrate Annotator.js inside the digilib UI which in the end
was not as complicated as I initially thought ;-)

<http://hg.berlios.de/repos/digilib/file/d62806e28820/webapp/src/main/webapp/jquery/jquery.digilib.annotator.js>

But I had to do double bookkeeping to build a list of all annotations
(store plugin didn't offer this) and add my own local data to each
annotation.

> ## Inflexible matching
> 
> Annotator only supports one kind of selector by default, the
> XPointer/TextPositionSelector method that it's used since day one.

And setupAnnotation assumes the existence of "highlight" and "range"
members on the annotation object...

> We need to provide native support for matcher plugins, which receive
> annotations at load time, add arbitrary data to those annotations (in the
> XPointer case, this might be an array of DOM textNodes) which can be used
> by view plugins (e.g. Highlighter, Viewer, etc.).
> 
> This data wouldn't be serialized and as such we need a more general pattern
> for attaching local data to annotations. Something better than
> 
> 
> https://github.com/okfn/annotator/blob/8ff0778/src/plugin/store.coffee#L462-L473
> 
> anyway.

Yep.

Would this also cover the creation of annotations by the user?

We would like to change the algorithm that produces a simple DOM-path
like "div[5]/div[3]/span[5]" to one that looks for the nearest element
with an ID like "div(@id=qxc123)/span[5]".

> 2. Store plugins
> 
> Store plugins implement a common interface to CRUD and query operations on
> backend data stores. Each operation might succeed or fail due to model
> constraints, network outage, etc. A minimal interface might be:
> 
>   create :: obj -> Promise(ann)
>   update :: ann -> Promise(ann)
>   delete :: ann -> Promise(None)
>   query :: id -> Promise(([ann], queryMeta))

I would also like a way to get a list of all current annotations to be
able to do my own display refresh.

Or another way to iterate through all annotations like a "refresh"
action and a hook for my display code.

> ## Asynchrony
> 
> Things that need to be done asynchronously return Promises. 'Nuff said.

jQuery Promise? (I always thought I should finally try to understand
those...)

> This is, however, a big chunk of work, and I don't think it's going to be
> possible to do so without breaking some existing integrations. While
> obviously we should try and minimise breakage, I think it's possible that
> the result of some of this work will become Annotator v2.0.0 (for an
> explanation of why, see http://semver.org/).

I'm fine with with a 2.0.0 and I'm happy to throw my code away if the
new code is better :-)

Cheers
	Robert