[annotator-dev] Remaining work on Annotator for 2.0

Fri Oct 24 00:53:04 UTC 2014

I thought I'd try and jot down the remaining items requiring work or
resolution on the path to Annotator 2.0. Broadly, this divides into four
main parts.

1. reenabling (or consciously deciding not to reenable) the
functionality provided by the Permissions, Auth, Tags, and Markdown
plugins
2. stabilising the Annotator API
3. documentation
4. release engineering

I'll flesh out each of these in turn with my current thinking.

---

1a. reenabling the functionality provided by the "permissions" plugin

This is mostly done. The plugin did three different jobs, which in
retrospect should never all have been part of the same component. It:

- allowed users to set a default value for the "permissions" field of
annotations
- presented basic view/edit permissions checkboxes in the editor
- controlled whether or not the view/edit buttons were shown in the
viewer depending on the annotation permissions

The first of these has simply gone. If you want to provide a default
value for the "permissions" field, you should be doing that on the
server where it can't be tampered with. Doing so client-side is still
trivially possible with a plugin of a few lines.

The second is now part of the Annotator default UI, which is an
opinionated configuration of several UI components.

The third has been made more flexible by making it possible to pass
"permitEdit" and "permitDelete" callback functions to viewer instances.
A default sane configuration of these is provided in the default UI.

---

1b. reenabling the functionality provided by the "auth" plugin

The groundwork for this has been laid. My current thinking is that we
will provide an option on the default storage implementation which
allows a developer to hijack the ajax requests it makes. In particular,
if I can provide a function to the storage component which will queue
requests until a valid auth token is received, and which will add
headers to those requests before they are sent, then I can effectively
reimplement the auth plugin.

---

1c. reenabling the functionality provided by the "tags" plugin

This could be implemented as a UI component which configures viewer and
editor instances with appropriate fields.

---

1d. reenabling the functionality provided by the "markdown" plugin

This could be implemented as an option to the viewer which allows the
ability to filter the annotation body before it is displayed, and a UI
component which configures a viewer instance.

---

2. stabilising the Annotator API

A lot has changed inside Annotator. The way plugins are instantiated has
changed. There are now non-plugin components (such as storages,
authorizers, identifiers, etc.) which can change an Annotator's
behaviour. We need to finalize what this API looks like and review the
naming of these components, so that we can guarantee API stability in
the future.

---

3. documentation

With so much changed, there will be a lot of documentation to update.
New plugins and components need to be documented. In addition, we will
provide some documentation to help people who use Annotator v1.2 to
upgrade. A stretch goal would be some decent generated API
documentation.

---

4. release engineering

The main items here are a) L10N strings updates and b) finalising built
artifacts. We'll aim to be publishing a final set of L10N strings
alongside an Annotator release candidate, with a view to being able to
include updated translations in the released Annotator 2.0. As for built
artifacts -- we may release Annotator in several packages with support
for different features and environments. For example, not everyone will
need to support IE8/9, but we may release a package which includes
support for these legacy browsers.

---

I am aiming to ship a beta release of Annotator 2.0 by December. Not all
of these items will be done by then, but we will need to have at least
the API stabilisation and authentication functionality, and to have made
a start on documentation.

Have I missed anything?

-N