annotator.storage package

annotator.storage.debug()

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

Use as an extension module:

app.include(annotator.storage.debug);
annotator.storage.noop()

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.

Use as a extension module:

app.include(annotator.storage.noop);
annotator.storage.http([options])

A module which configures an instance of annotator.storage.HttpStorage as the storage component.

Parameters:options (Object) – Configuration options. For available options see options.
class annotator.storage.HttpStorage([options])

HttpStorage is a storage component that talks to a remote JSON + HTTP API that should be relatively easy to implement with any web application framework.

Parameters:options (Object) – See options.
annotator.storage.HttpStorage.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:The request object.
Return type:Promise
annotator.storage.HttpStorage.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:The request object.
Return type:Promise
annotator.storage.HttpStorage.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:The request object.
Return type:Promise
annotator.storage.HttpStorage.prototype.query(queryObj)

Searches for annotations matching the specified query.

Parameters:queryObj (Object) – An object describing the query.
Returns:A promise, resolves to an object containing query results and meta.
Return type:Promise
annotator.storage.HttpStorage.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.HttpStorage.options

Available configuration options for HttpStorage. See below.

annotator.storage.HttpStorage.options.emulateHTTP

Should the storage 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.HttpStorage.options.emulateJSON

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

Default: false

annotator.storage.HttpStorage.options.headers

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

Default: {}

annotator.storage.HttpStorage.options.onError

Callback, called if a remote request throws an error.

annotator.storage.HttpStorage.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.HttpStorage.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:

Default:

{
    create: '/annotations',
    update: '/annotations/{id}',
    destroy: '/annotations/{id}',
    search: '/search'
}
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 modules 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.