Annotator.Storage.HTTPStorage component¶

This storage component sends annotations (serialised as JSON) to a server that implements the Storage API: manufacturing/widgets.

var content = $('#content').annotator();
    content.annotator('addPlugin', 'Store', {
      // The endpoint of the store on your server.
      prefix: '/store/endpoint',

      // Attach the uri of the current page to all annotations to allow search.
      annotationData: {
        'uri': 'http://this/document/only'
      },

      // This will perform a "search" action when the plugin loads. Will
      // request the last 20 annotations for the current url.
      // eg. /store/endpoint/search?limit=20&uri=http://this/document/only
      loadFromSearch: {
        'limit': 20,
        'uri': 'http://this/document/only'
      }
    });

$('#content').annotator('addPlugin', 'Store', {
  prefix: '/store/endpoint'
});

$('#content').annotator('addPlugin', 'Store', {
  // Attach a uri property to every annotation sent to the server.
  annotationData: {
    'uri': 'http://this/document/only'
  }
});

$('#content').annotator('addPlugin', 'Store', {
  loadFromSearch: {
    'limit': 0,
    'all_fields': 1,
    'uri': 'http://this/document/only'
  }
});

create:  POST
update:  PUT
destroy: DELETE
search:  GET

$('#content').annotator('addPlugin', 'Store', {
  urls: {
    // These are the default URLs.
    create:  '/annotations',
    update:  '/annotations/:id',
    destroy: '/annotations/:id',
    search:  '/search'
  }
}):

Storage API¶

This document details the HTTP API used by the Annotator.Storage.HTTPStorage component. It is targeted at developers interested in developing their own backend servers that integrate with Annotator, or developing tools that integrate with existing instances of the API.

The storage API attempts to follow the principles of REST, and uses JSON as its primary interchange format.

Auth plugin¶

The Auth plugin complements the store by providing authentication for requests. This may be necessary if you are running the Store on a separate domain or using a third party service like annotateit.org.

The plugin works by requesting an authentication token from the local server and then provides this in all requests to the store. For more details see the specification.

var content = $('#content'));
content.annotator('addPlugin', 'Auth', {
  tokenUrl: '/auth/token'
});

Filter plugin¶

This plugin allows the user to navigate and filter the displayed annotations.

var content = $('#content').annotator().annotator('addPlugin', 'Filter');

content.annotator('addPlugin', 'Filter', {
  filters: [
    {
      label: 'Quote',
      property: 'quote'
    }
  ]
});

content.annotator('addPlugin', 'Filter', {
  filters: [
    {
      label: 'Tag',
      property: 'tags',
      isFiltered: function (input, tags) {
        if (input && tags && tags.length) {
          var keywords = input.split(/\s+/g);
          for (var i = 0; i < keywords.length; i += 1) {
            for (var j = 0; j < tags.length; j += 1) {
              if (tags[j].indexOf(keywords[i]) !== -1) {
                return true;
              }
            }
          }
        }
        return false;
    }}
  ]
});

Markdown Plugin¶

The Markdown plugin allows you to use Markdown in your annotation comments. It will then render them in the Viewer.

<script src="javascript/jquery.js"></script>
<script src="javascript/showdown.js"></script>
<script src="javascript/annotator.min.js"></script>
<script src="javascript/annotator.markdown.min.js"></script>

var content = $('#content').annotator();
content.annotator('addPlugin', 'Markdown');

Permissions plugin¶

This plugin handles setting the user and permissions properties on annotations as well as providing some enhancements to the interface.

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

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

// 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

Tags plugin¶

This plugin allows the user to tag their annotations with keywords.

var content = $('#content').annotator().annotator('addPlugin', 'Tags');

Unsupported plugin¶

The Annotator only supports browsers that have the window.getSelection() method (for a table of support please see this Quirksmode article). This plugin provides a notification to users of these unsupported browsers letting them know that the plugin has not loaded.

var content = $('#content').annotator();
content.annotator('addPlugin', 'Unsupported');

var annotator = $('#content').annotator().data('annotator');

annotator.addPlugin('Unsupported', {
  message: "We're sorry the Annotator is not supported by this browser"
});

annotator package¶

class annotator.Annotator(element[, options])¶

Annotator represents a reasonable default annotator configuration, providing a default set of plugins and a user interface.

NOTE: If the Annotator is not supported by the current browser it will not perform any setup and simply return a basic object. This allows plugins to still be loaded but will not function as expected. It is reccomended to call Annotator.supported() before creating the instance or using the Unsupported plugin which will notify users that the Annotator will not work.

Examples:

var app = new annotator.Annotator(document.body);

Parameters:	element (Element) – DOM Element to attach to. options (Object) – Configuration options.

annotator.Annotator.prototype.destroy()¶

Destroy the current Annotator instance, unbinding all events and disposing of all relevant elements.

annotator.supported([details=false, scope=window])¶

Examines scope (by default the global window object) to determine if Annotator can be used in this environment.

Returns Boolean:
	Whether Annotator can be used in scope, if details is false.
Returns Object:	If details is true. Properties: supported: Boolean, whether Annotator can be used in scope. details: Array of String reasons why Annotator cannot be used.

annotator.core package¶

class annotator.core.Annotator¶

Annotator is the coordination point for all annotation functionality. On its own it provides only the necessary code for coordinating the lifecycle of annotation objects. It requires at least a storage plugin to be useful.

annotator.core.Annotator.prototype.addPlugin(plugin)¶

Register a plugin

Examples:

function creationNotifier(registry) {
    return {
        onAnnotationCreated: function (ann) {
            console.log("annotationCreated", ann);
        }
    }
}

annotator
  .addPlugin(annotator.plugin.Tags)
  .addPlugin(creationNotifier)

Parameters:	plugin – A plugin to instantiate. A plugin is a function that accepts a Registry object for the current Annotator and returns a plugin object. A plugin object may define function properties wi
Returns:	The Annotator instance, to allow chained method calls.

annotator.core.Annotator.prototype.destroy()¶

Destroy the current instance

Destroys all remnants of the current AnnotatorBase instance by calling the destroy method, if it exists, on each plugin object.

Returns Promise:
	Resolved when all plugin destroy hooks are completed.

annotator.core.Annotator.prototype.runHook(name[, args])¶

Run the named hook with the provided arguments

Returns Promise:
	Resolved when all over the hook handlers are complete.

annotator.core.Annotator.prototype.setAuthorizer(authorizerFunc)¶

Set the authorizer implementation

Parameters:	authorizerFunc (Function) – A function returning an authorizer component. An authorizer component must implement the Authorizer interface.
Returns:	The Annotator instance, to allow chained method calls.

annotator.core.Annotator.prototype.setIdentifier(identifierFunc)¶

Set the identifier implementation

Parameters:	identifierFunc (Function) – A function returning an identifier component. An identifier component must implement the Identifier interface.
Returns:	The Annotator instance, to allow chained method calls.

annotator.core.Annotator.prototype.setNotifier(notifierFunc)¶

Set the notifier implementation

Parameters:	notifierFunc (Function) – A function returning a notifier component. A notifier component must implement the Notifier interface.
Returns:	The Annotator instance, to allow chained method calls.

annotator.core.Annotator.prototype.setStorage(storageFunc)¶

Set the storage implementation

Parameters:	storageFunc (Function) – A function returning a storage component. A storage component must implement the Storage interface.
Returns:	The Annotator instance, to allow chained method calls.

annotator.core.Annotator.extend(object)¶

Create a new object which inherits from the Annotator class.

annotator.storage package¶

annotator.storage.DebugStorage()¶

DebugStorage is a storage component that can be used to print details of the annotation persistence processes to the console when developing other parts of Annotator.

annotator.storage.NullStorage()¶

NullStorage is a no-op storage component. It swallows all calls and does the bare minimum needed. Needless to say, it does not provide any real persistence.

class annotator.storage.HTTPStorageImpl([options])¶

HTTPStorageImpl is a storage component that talks to a simple remote API that can be implemented with any web framework.

Parameters:	options (Object) – Configuration options.

annotator.storage.HTTPStorageImpl.prototype.create(annotation)¶

Create an annotation.

Examples:

store.create({text: "my new annotation comment"})
// => Results in an HTTP POST request to the server containing the
//    annotation as serialised JSON.

Parameters:	annotation (Object) – An annotation.
Returns jqXHR:	The request object.

annotator.storage.HTTPStorageImpl.prototype.update(annotation)¶

Update an annotation.

Examples:

store.update({id: "blah", text: "updated annotation comment"})
// => Results in an HTTP PUT request to the server containing the
//    annotation as serialised JSON.

Parameters:	annotation (Object) – An annotation. Must contain an id.
Returns jqXHR:	The request object.

annotator.storage.HTTPStorageImpl.prototype.delete(annotation)¶

Delete an annotation.

Examples:

store.delete({id: "blah"})
// => Results in an HTTP DELETE request to the server.

Parameters:	annotation (Object) – An annotation. Must contain an id.
Returns jqXHR:	The request object.

annotator.storage.HTTPStorageImpl.prototype.query(queryObj)¶

Searches for annotations matching the specified query.

Parameters:	queryObj (Object) – An object describing the query.
Returns Promise:
	Resolves to an object containing query results and meta.

annotator.storage.HTTPStorageImpl.prototype.setHeader(name, value)¶

Set a custom HTTP header to be sent with every request.

Examples:

store.setHeader('X-My-Custom-Header', 'MyCustomValue')

Parameters:	name (string) – The header name. value (string) – The header value.

annotator.storage.HTTPStorageImpl.options¶

Available configuration options for HTTPStorageImpl.

annotator.storage.HTTPStorageImpl.options.emulateHTTP¶

Should the plugin emulate HTTP methods like PUT and DELETE for interaction with legacy web servers? Setting this to true will fake HTTP PUT and DELETE requests with an HTTP POST, and will set the request header X-HTTP-Method-Override with the name of the desired method.

Default: false

annotator.storage.HTTPStorageImpl.options.emulateJSON¶

Should the plugin emulate JSON POST/PUT payloads by sending its requests as application/x-www-form-urlencoded with a single key, “json”

Default: false

annotator.storage.HTTPStorageImpl.options.headers¶

A set of custom headers that will be sent with every request. See also the setHeader method.

Default: {}

annotator.storage.HTTPStorageImpl.options.onError¶

Callback, called if a remote request throws an error.

annotator.storage.HTTPStorageImpl.options.prefix¶

This is the API endpoint. If the server supports Cross Origin Resource Sharing (CORS) a full URL can be used here.

Default: '/store'

annotator.storage.HTTPStorageImpl.options.urls¶

The server URLs for each available action. These URLs can be anything but must respond to the appropriate HTTP method. The URLs are Level 1 URI Templates as defined in RFC6570:

http://tools.ietf.org/html/rfc6570#section-1.2

class annotator.storage.StorageAdapter(store, runHook)¶

StorageAdapter wraps a concrete implementation of the Storage interface, and ensures that the appropriate hooks are fired when annotations are created, updated, deleted, etc.

Parameters:	store – The Store implementation which manages persistence runHook (Function) – A function which can be used to run lifecycle hooks

annotator.storage.StorageAdapter.prototype.create(obj)¶

Creates and returns a new annotation object.

Runs the ‘beforeAnnotationCreated’ hook to allow the new annotation to be initialized or its creation prevented.

Runs the ‘annotationCreated’ hook when the new annotation has been created by the store.

Examples:

registry.on('beforeAnnotationCreated', function (annotation) {
    annotation.myProperty = 'This is a custom property';
});
registry.create({}); // Resolves to {myProperty: "This is a…"}

Parameters:	annotation (Object) – An object from which to create an annotation.
Returns Promise:
	Resolves to annotation object when stored.

annotator.storage.StorageAdapter.prototype.update(obj)¶

Updates an annotation.

Runs the ‘beforeAnnotationUpdated’ hook to allow an annotation to be modified before being passed to the store, or for an update to be prevented.

Runs the ‘annotationUpdated’ hook when the annotation has been updated by the store.

Examples:

annotation = {tags: 'apples oranges pears'};
registry.on('beforeAnnotationUpdated', function (annotation) {
    // validate or modify a property.
    annotation.tags = annotation.tags.split(' ')
});
registry.update(annotation)
// => Resolves to {tags: ["apples", "oranges", "pears"]}

Parameters:	annotation (Object) – An annotation object to update.
Returns Promise:
	Resolves to annotation object when stored.

annotator.storage.StorageAdapter.prototype.delete(obj)¶

Deletes the annotation.

Runs the ‘beforeAnnotationDeleted’ hook to allow an annotation to be modified before being passed to the store, or for the a deletion to be prevented.

Runs the ‘annotationDeleted’ hook when the annotation has been deleted by the store.

Parameters:	annotation (Object) – An annotation object to delete.
Returns Promise:
	Resolves to annotation object when deleted.

annotator.storage.StorageAdapter.prototype.query(query)¶

Queries the store

Parameters:	query (Object) – A query. This may be interpreted differently by different stores.
Returns Promise:
	Resolves to the store return value.

annotator.storage.StorageAdapter.prototype.load(query)¶

Load and draw annotations from a given query.

Runs the ‘load’ hook to allow plugins to respond to annotations being loaded.

Parameters:	query (Object) – A query. This may be interpreted differently by different stores.
Returns Promise:
	Resolves when loading is complete.

annotator.authorizer package¶

class annotator.authorizer.DefaultAuthorizer([options])¶

Default authorizer

Parameters:	options (Object) – Configuration options. userId: Custom function mapping an identity to a userId.

annotator.authorizer.DefaultAuthorizer.prototype.permits(action, annotation, identity)¶

Determines whether the user identified by identity is permitted to perform the specified action on the given annotation.

If the annotation has a “permissions” object property, then actions will be permitted if either of the following are true:

1. annotation.permissions[action] is undefined or null,
2. annotation.permissions[action] is an Array containing the userId of the passed identity.

If the annotation has a “user” property, then actions will be permitted only if the userId of identity matches this “user” property.

If the annotation has neither a “permissions” property nor a “user” property, then all actions will be permitted.

Parameters:	action (String) – The action the user wishes to perform annotation (Object) – identity – The identity of the user
Returns Boolean:
	Whether the action is permitted

annotator.authorizer.DefaultAuthorizer.prototype.userId(identity)¶

A function for mapping an identity to a primitive userId. This default implementation simply returns the identity, and can be used with identities that are primitives (strings, integers).

Parameters:	identity – A user identity.
Returns:	The userId of the passed identity.

annotator.identifier package¶

annotator.identifier.Default(identity)¶

Default identifier implementation.

Parameters:	identity – The identity to report as the current user.
Returns:	A function returning an identifier object.

annotator.notifier package¶

class annotator.notifier.BannerNotifier(message[, severity=notifier.INFO])¶

BannerNotifier is simple notifier system that can be used to display information, warnings and errors to the user.

Parameters:	message (String) – The notice message text. severity – The severity of the notice (one of notifier.INFO, notifier.SUCCESS, or notifier.ERROR)

annotator.notifier.BannerNotifier.prototype.close()¶

Close the notifier.

Returns:	The notifier instance.