The Annotator libraries¶

To get the Annotator up and running on your website you’ll need to either link to a hosted version or deploy the Annotator source files yourself. Details of both are provided below.

http://assets.annotateit.org/annotator/{version}/annotator-full.min.js
http://assets.annotateit.org/annotator/{version}/annotator.min.js
http://assets.annotateit.org/annotator/{version}/annotator.{pluginname}.min.js
http://assets.annotateit.org/annotator/{version}/annotator.min.css

<script src="http://assets.annotateit.org/annotator/v1.2.5/annotator-full.min.js"></script>
<link rel="stylesheet" href="http://assets.annotateit.org/annotator/v1.2.5/annotator.min.css">

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
<script src="http://assets.annotateit.org/annotator/v1.1.0/annotator-full.min.js"></script>
<link rel="stylesheet" href="http://assets.annotateit.org/annotator/v1.1.0/annotator.min.css">

Setting up Annotator¶

Setting up Annotator requires only a single line of code. Use jQuery to select the element that you would like to annotate eg. <div id="content">...</div> and call the .annotator() method on it:

jQuery(function ($) {
    $('#content').annotator();
});

Annotator will now be loaded on the #content element. Select some text to see it in action.

Options¶

You can optionally specify options:

readOnly

True to allow viewing annotations, but not creating or editing them. Defaults to false.

jQuery(function ($) {
    $('#content').annotator({
        readOnly: true
    });
});

Setting up the default plugins¶

We include a special setup function in the annotator-full.min.js file that installs all the default plugins for you automatically. To run it just add a call to .annotator("setupPlugins").

jQuery(function ($) {
    $('#content').annotator()
                 .annotator('setupPlugins');
});

This will set up the following:

1. The Tags, Filter & Unsupported plugins.
2. The Auth, Permissions and Store plugins, for interaction with the AnnotateIt store.
3. If the Showdown library has been included on the page the Markdown Plugin will also be loaded.

You can further customise the plugins by providing an object containing options for individual plugins. Or to disable a plugin set it’s attribute to false.

jQuery(function ($) {
    // Customise the default plugin options with the third argument.
    $('#content').annotator()
                 .annotator('setupPlugins', {}, {
                   // Disable the tags plugin
                   Tags: false,
                   // Filter plugin options
                   Filter: {
                     addAnnotationFilter: false, // Turn off default annotation filter
                     filters: [{label: 'Quote', property: 'quote'}] // Add a quote filter
                   }
                 });
});

Adding more plugins¶

To add a plugin first make sure that you’re loading the script into the page. Then call .annotator('addPlugin', 'PluginName') to load the plugin. Options can also be passed to the plugin as additional parameters after the plugin name.

Here we add the tags plugin to the page:

jQuery(function ($) {
    $('#content').annotator()
                 .annotator('addPlugin', 'Tags');
});

For more information on available plugins check the navigation to the right of this article. Or to create your own check the creating a plugin section.

Saving annotations¶

In order to keep your annotations around longer than a single page view you’ll need to set up a store on your server or use an external service like AnnotateIt. For more information on storing annotations check out the Store Plugin on the wiki.

What’s the authentication system for?¶

The simplest way to explain the role of the authentication system is by example. Consider the following:

1. Alice builds a website with documents which need annotating, DocLand.
2. Alice registers DocLand with AnnotateIt, and receives a “consumer key/secret” pair.
3. Alice’s users (Bob is one of them) login to her DocLand, and receive an authentication token, which is a cryptographic combination of (among other things) their unique user ID at DocLand, and DocLand’s “consumer secret”.
4. Bob’s browser sends requests to AnnotateIt to save annotations, and these include the authentication token as part of the payload.
5. AnnotateIt can verify the Bob is a real user from DocLand, and thus stores his annotation.

So why go to all this trouble? Well, the point is really to save you trouble. By implementing this authentication system (which shares key ideas with the industry standard OAuth) you can provide your users with the ability to annotate documents on your website without needing to worry about implementing your own Annotator backend. You can use AnnotateIt to provide the backend: all you have to do is implement a token generator on your website (described below).

This is the simple explanation, but if you’re in need of more technical details, keep reading.

Technical overview¶

How do we authorise users’ browsers to create annotations on a Consumer’s behalf? There are three (and a half) entities involved:

1. The Service Provider (SP; AnnotateIt in the above example)
2. The Consumer (C; DocLand)
3. The User (U; Bob), and the User Agent (UA; Bob’s browser)

Annotations are stored by the SP, which provides an API that the Annotator’s “Store” plugin understands.

Text to be annotated, and configuration of the clientside Annotator, is provided by the Consumer.

Users will typically register with the Consumer – we make no assumptions about your user registration/authentication process other than that it exists – and the UA will, when visiting appropriate sections of C’s site, request an authToken from C. Typically, an authToken will only be provided if U is currently logged into C’s site.

Technical specification¶

It’s unlikely you’ll need to understand all of the following to get up and running using AnnotateIt – you can probably just copy and paste the Python example given below – but it’s worth reading what follows if you’re doing anything unusual (such as giving out tokens to unauthenticated users).

The Annotator authToken is a type of JSON Web Token. This document won’t describe the details of the JWT specification, other than to say that the token payload is signed by the consumer secret with the HMAC-SHA256 algorithm, allowing the backend to verify that the contents of the token haven’t been interfered with while travelling from the consumer. Numerous language implementations exist already (PyJWT, jwt for Ruby, php-jwt, JWT-CodeIgniter...).

The required contents of the token payload are:

You may wish the payload to contain other information (e.g. userRole or userGroups) and arbitrary additional keys may be added to the token. This will only be useful if the Annotator client and the SP pay attention to these keys.

Lastly, note that the Annotator frontend does not verify the authenticity of the tokens it receives. Only the SP is required to verify authenticity of auth tokens before authorizing a request from the Annotator frontend.

For reference, here’s a Python implementation of a token generator, suitable for dropping straight into your Flask or Django project:

import datetime
import jwt

# Replace these with your details
CONSUMER_KEY = 'yourconsumerkey'
CONSUMER_SECRET = 'yourconsumersecret'

# Only change this if you're sure you know what you're doing
CONSUMER_TTL = 86400

def generate_token(user_id):
    return jwt.encode({
      'consumerKey': CONSUMER_KEY,
      'userId': user_id,
      'issuedAt': _now().isoformat() + 'Z',
      'ttl': CONSUMER_TTL
    }, CONSUMER_SECRET)

def _now():
    return datetime.datetime.utcnow().replace(microsecond=0)

Now all you need to do is expose an endpoint in your web application that returns the token to logged-in users (say, http://example.com/api/token), and you can set up the Annotator like so:

$(body).annotator()
       .annotator('setupPlugins', {tokenUrl: 'http://example.com/api/token'});

Colophon¶

Original planning documents at:

• http://lists.okfn.org/pipermail/okfn-help/2010-December/000977.html

Rehashed in Feb 2012:

• http://lists.okfn.org/pipermail/annotator-dev/2012-January/000188.html

Interface Overview¶

The following elements are added to the Annotator interface by this plugin.

Usage¶

Adding the permissions plugin to the annotator is very simple. Simply add the annotator to the page using the .annotator() jQuery plugin and retrieve the annotator object using .data('annotator'). We now add the plugin and pass an options object to set the current user.

var annotator = $('#content').annotator().data('annotator');
annotator.addPlugin('Permissions', {
  user: 'Alice'
});

By default all annotations are publicly viewable/editable/deleteable. We can set our own permissions using the options object.

var annotator = $('#content').annotator().data('annotator');
annotator.addPlugin('Permissions', {
  user: 'Alice',
  permissions: {
    'read':   [],
    'update': ['Alice'],
    'delete': ['Alice'],
    'admin':  ['Alice']
  }
});

Now only our current user can edit the annotations but anyone can view them.

The options object allows you to completely define the way permissions are handled for your site.

• user: The current user (required).
• permissions: An object defining annotation permissions.
• userId: A callback that returns the user id.
• userString: A callback that returns the users name.
• userAuthorize: A callback that allows custom authorisation.
• showViewPermissionsCheckbox: If false hides the “Anyone can view…” checkbox.
• showEditPermissionsCheckbox: If false hides the “Anyone can edit…” checkbox.

// Simple example.
annotator.addPlugin('Permissions', {
  user: 'Alice'
});

// Complex example.
annotator.addPlugin('Permissions', {
  user: {
    id: 6,
    username: 'Alice',
    location: 'Brighton, UK'
  }
});

annotator.addPlugin('Permissions', {
  user: 'Alice',
  permissions: {
    'read':   ['Alice'],
    'update': ['Alice'],
    'delete': ['Alice'],
    'admin':  ['Alice']
  }
});

annotator.addPlugin('Permissions', {
  user: {id: 6, name:'Alice'},
  permissions: {
    'read':   [6],
    'update': [6],
    'delete': [6],
    'admin':  [6]
  }
});

annotator.addPlugin('Permissions', {
  user: {id: 6, name:'Alice'},
  userId: function (user) {
    if (user && user.id) {
      return user.id;
    }
    return user;
  }
});
// When called.
userId({id: 6, name:'Alice'}) // => Returns 6

annotator.addPlugin('Permissions', {
  user: {id: 6, name:'Alice'},
  userString: function (user) {
    if (user && user.name) {
      return user.name;
    }
    return user;
  }
});
// When called.
userString({id: 6, name:'Alice'}) // => Returns 'Alice'

// This is the default implementation as an example.
annotator.addPlugin('Permissions', {
  user: 'Alice',
    userAuthorize: function(action, annotation, user) {
      var token, tokens, _i, _len;
      if (annotation.permissions) {
        tokens = annotation.permissions[action] || [];
        if (tokens.length === 0) {
          return true;
        }
        for (_i = 0, _len = tokens.length; _i < _len; _i++) {
          token = tokens[_i];
          if (this.userId(user) === token) {
            return true;
          }
        }
        return false;
      } else if (annotation.user) {
        if (user) {
          return this.userId(user) === this.userId(annotation.user);
        } else {
          return false;
        }
      }
      return true;
    },
});
// When called.
userAuthorize('update', aliceAnnotation, 'Alice') // => Returns true
userAuthorize('Alice', bobAnnotation, 'Bob')   // => Returns false

For users¶

If you wish to use a provided translation, you need to add a link tag pointing to the .po file, as well as include gettext.js before you load the Annotator. For example, for a French translation:

<link rel="gettext" type="application/x-po" href="locale/fr/annotator.po">
<script src="lib/vendor/gettext.js"></script>

This should be all you need to do to get the Annotator interface displayed in French.

For translators¶

We now use Transifex to manage localisation efforts on Annotator. If you wish to contribute a translation you’ll first need to sign up for a free account at

https://www.transifex.net/plans/signup/free/

Once you’re signed up, you can go to

https://www.transifex.net/projects/p/annotator/

and get translating!

For developers¶

Any localisable string in the core of Annotator should be wrapped with a call to the gettext function, _t, e.g.

console.log(_t("Hello, world!"))

Any localisable string in an Annotator plugin should be wrapped with a call to the gettext function, Annotator._t, e.g.

console.log(Annotator._t("Hello from a plugin!"))

To update the localisation template (locale/annotator.pot), you should run the i18n:update Cake task:

cake i18n:update

You should leave it up to individual translators to update their individual .po files with the locale/l10n-update tool.

Core storage API¶

The storage API is defined in terms of a prefix and a number of endpoints. It attempts to follow the principles of REST, and emits JSON documents to be parsed by the Annotator. Each of the following endpoints for the storage API is expected to be found on the web at prefix + path. For example, if the prefix were http://example.com/api, then the index endpoint would be found at http://example.com/api/annotations.

General rules are those common to most REST APIs. If a resource cannot be found, return 404 NOT FOUND. If an action is not permitted for the current user, return 401 NOT AUTHORIZED, otherwise return 200 OK. Send JSON text with the header Content-Type: application/json.

Below you can find details of the six core endpoints, root, index, create, read, update, delete, as well as an optional search API.

WARNING:

The spec below requires you return 303 SEE OTHER from the create and update endpoints. Ideally this is what you’d do, but unfortunately most modern browsers (Firefox and Webkit) still make a hash of CORS requests when they include redirects. A simple workaround for the time being is to return 200 OK and the JSON annotation that would be returned by the read endpoint in the body of the create and update responses. See bugs in Chromium and Webkit.

$ curl http://example.com/api/
{
  "name": "Annotator Store API",
  "version": "2.0.0"
}

$ curl http://example.com/api/annotations
[
  {
    "text": "Example annotation text",
    "ranges": [ ... ],
    ...
  },
  {
    "text": "Another annotation",
    "ranges": [ ... ],
    ...
  },
  ...
]

$ curl -i -X POST \
       -H 'Content-Type: application/json' \
       -d '{"text": "Annotation text"}' \
       http://example.com/api/annotations
HTTP/1.0 303 SEE OTHER
Location: http://example.com/api/annotations/d41d8cd98f00b204e9800998ecf8427e
...

$ curl http://example.com/api/annotations/d41d8cd98f00b204e9800998ecf8427e
{
  "id": "d41d8cd98f00b204e9800998ecf8427e",
  "text": "Annotation text",
  ...
}

$ curl -i -X PUT \
       -H 'Content-Type: application/json' \
       -d '{"text": "Updated annotation text"}' \
       http://example.com/api/annotations/d41d8cd98f00b204e9800998ecf8427e
HTTP/1.0 303 SEE OTHER
Location: http://example.com/api/annotations/d41d8cd98f00b204e9800998ecf8427e
...

$ curl -i -X DELETE http://example.com/api/annotations/d41d8cd98f00b204e9800998ecf8427e
HTTP/1.0 204 NO CONTENT
Content-Length: 0

Search API¶

You may also choose to implement a search API, which can be used by the Store plugin’s loadFromSearch configuration option.

$ curl http://example.com/api/search?text=annotation
{
  "total": 43127,
  "rows": [
    {
      "id": "d41d8cd98f00b204e9800998ecf8427e",
      "text": "Updated annotation text",
      ...
    },
    ...
  ]
}

Storage Implementations¶

• Reference backend, a Python Flask app: https://github.com/okfn/annotator-store (in particular, see store.py, although be aware that this file also deals with authentication and authorization, making the code a good deal more complex than would be required to implement what is described above).
• PHP (Silex) and MongoDB-based basic implementation: https://github.com/julien-c/annotator-php (in particular, see index.php).

Getting Started¶

Building a plugin is very simple. Simply attach a function that creates your plugin to the Annotator.Plugin namespace. The function will receive the following arguments.

element

The DOM element that is currently being annotated.

Additional arguments (such as options) can be passed in by the user when the plugin is added to the Annotator. These will be passed in after the element.

Annotator.Plugin.HelloWorld = function (element) {
  var myPlugin = {};
  // Create your plugin here. Then return it.
  return myPlugin;
};

// Setup the annotator on the page.
var content = $('#content').annotator();

// Add your plugin.
content.annotator('addPlugin', 'HelloWorld' /*, any other options */);

Annotator.Plugin.Message = function (element, message) {
  var plugin = {};

  plugin.pluginInit = function () {
      this.annotator.viewer.addField({
        load: function (field, annotation) {
          field.innerHTML = message;
        }
      })
  };

  return plugin;
}

// Setup the annotator on the page.
var content = $('#content').annotator();

// Add your plugin to the annotator and display the message "Hello World"
// in the viewer.
content.annotator('addPlugin', 'Message', 'Hello World');

Extending Annotator.Plugin¶

All supported Annotator plugins use a base “class” that has some useful features such as event handling. To use this you simply need to extend the Annotator.Plugin function.

// This is now a constructor and needs to be called with `new`.
Annotator.Plugin.MyPlugin = function (element, options) {

  // Call the Annotator.Plugin constructor this sets up the .element and
  // .options properties.
  Annotator.Plugin.apply(this, arguments);

  // Set up the rest of your plugin.
};

// Set the plugin prototype. This gives us all of the Annotator.Plugin methods.
Annotator.Plugin.MyPlugin.prototype = new Annotator.Plugin();

// Now add your own custom methods.
Annotator.Plugin.MyPlugin.prototype.pluginInit = function () {
  // Do something here.
};

If you’re using jQuery you can make this process a lot neater.

Annotator.Plugin.MyPlugin = function (element, options) {
  // Same as before.
};

jQuery.extend(Annotator.Plugin.MyPlugin.prototype, new Annotator.Plugin(), {
  events: {},
  options: {
    // Any default options.
  }
  pluginInit: function () {

  },
  myCustomMethod: function () {

  }
});

Annotator.Plugin API¶

The Annotator.Plugin provides the following methods and properties.

Annotator Events¶

The annotator fires the following events at key points in its operation. You can subscribe to them using the .subscribe() method. This can be called on either the .annotator object or if you’re extending Annotator.Plugin the plugin instance itself. The events are as follows:

beforeAnnotationCreated(annotation)

called immediately before an annotation is created. If you need to modify the annotation before it is saved use this event.

annotationCreated(annotation)

called when the annotation is created use this to store the annotations.

beforeAnnotationUpdated(annotation)

as above, but just before an existing annotation is saved.

annotationUpdated(annotation)

as above, but for an existing annotation which has just been edited.

annotationDeleted(annotation)

called when the user deletes an annotation.

annotationEditorShown(editor, annotation)

called when the annotation editor is presented to the user.

annotationEditorHidden(editor)

called when the annotation editor is hidden, both when submitted and when editing is cancelled.

annotationEditorSubmit(editor, annotation)

called when the annotation editor is submitted.

annotationViewerShown(viewer, annotations)

called when the annotation viewer is shown and provides the annotations being displayed.

annotationViewerTextField(field, annotation)

called when the text field displaying the annotation comment in the viewer is created.

Annotator.Plugin.StoreLogger = function (element) {
  return {
    pluginInit: function () {
      this.annotator
          .subscribe("annotationCreated", function (annotation) {
            console.info("The annotation: %o has just been created!", annotation)
          })
          .subscribe("annotationUpdated", function (annotation) {
            console.info("The annotation: %o has just been updated!", annotation)
          })
          .subscribe("annotationDeleted", function (annotation) {
            console.info("The annotation: %o has just been deleted!", annotation)
          });
    }
  }
};

2.0¶

2.1¶

The main goals for this release, which we aim to ship by May 1, 2015 (with a major feature freeze on Mar 15):

• Support for selections made using the keyboard
• Support in the core for annotation on touch devices
• Support for multiple typed selectors in annotations
• Support for components which resolve (‘reanchor’) an annotation’s selectors into a form suitable for display in the page

2.2¶

The main goals for this release, which we aim to ship by Aug 1, 2015 (with a major feature freeze on Jun 15):

• Support for annotation of additional media types (images, possibly video) in the core

2.3¶

The main goals for this release, which we aim to ship by Nov 1, 2015 (with a major feature freeze on Sep 15):

• Improved highlight rendering (faster, doesn’t modify underlying DOM)
• Replace existing XPath-based selector code with Rangy