[annotator-dev] Refining sub-component flexibility

Tue Oct 14 07:01:44 UTC 2014

In reviewing the current master branch today I came upon two simple
refinements I will try to make this week, but feel free to jump in and do
so yourselves. I hope by laying out the motivation and the philosophy here
it helps us see more places for improvement.

I hacked up an open annotation storage adapter today. It wraps any other
storage implementation to translate annotations to JSON that maps to open
annotation through a JSON LD context.

However, it became clear that there's very little need for such an adapter
if an annotator instance itself can work with the right "shape" directly
(targets, selectors and bodies as resources). With that scenario, all
that's needed is a context and no further transformations are necessary.

The sort of things blocking this are components that assume the names and
paths of the properties they work on.

An example is the text highlighter. Can we, instead of passing it
annotations to its API, pass ranges? The API can return the highlight
elements. The default UI, which is actually more than just UI, can then
pass the ranges and receive the highlights, setting the
`._local.highlights` property. With such a change, the assumption that
ranges are at `annotation.ranges` is isolated to the application core, the
"ui" which we might better call the annotation (as opposed to the library /
framework).

I'm not sure where else we could make similar improvements, but I wouldn't
be surprised to find them.

I did also notice that the adder needlessly deals with the annotation
directly, when it has no real business knowing the purpose it serves in
being a button. That could similar be lifted to the application.

Aiming to do this as much as possible at this stage feels good, as it tends
to reduce the amount of internal state buried in various components, makes
them more reusable, and avoids mutating inputs by leaving it to the caller
to manage the return value thus reducing side effects. If things start to
get tedious in the main application logic we can look for ways to reduce
boilerplate once we can see it all clearly.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/annotator-dev/attachments/20141014/c1383074/attachment-0003.html>