Permalink
Fetching contributors…
Cannot retrieve contributors at this time
272 lines (155 sloc) 8.01 KB

annotator.storage package

..  function:: 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);


..  function:: 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);


..  function:: annotator.storage.http([options])

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

    :param Object options:
      Configuration options. For available options see
      :attr:`~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.

param Object options:See :attr:`~annotator.storage.HttpStorage.options`.
..  function:: 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.

    :param Object annotation: An annotation.
    :returns: The request object.
    :rtype: Promise


..  function:: 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.

    :param Object annotation: An annotation. Must contain an `id`.
    :returns: The request object.
    :rtype: Promise


..  function:: annotator.storage.HttpStorage.prototype.delete(annotation)

    Delete an annotation.

    **Examples**::

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

    :param Object annotation: An annotation. Must contain an `id`.
    :returns: The request object.
    :rtype: Promise


..  function:: annotator.storage.HttpStorage.prototype.query(queryObj)

    Searches for annotations matching the specified query.

    :param Object queryObj: An object describing the query.
    :returns:
      A promise, resolves to an object containing query `results` and `meta`.
    :rtype: Promise


..  function:: 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')

    :param string name: The header name.
    :param string value: The header value.


..  attribute:: annotator.storage.HttpStorage.options

    Available configuration options for HttpStorage. See below.


..  attribute:: 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``


..  attribute:: 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``


..  attribute:: annotator.storage.HttpStorage.options.headers

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

    **Default**: ``{}``


..  attribute:: annotator.storage.HttpStorage.options.onError

    Callback, called if a remote request throws an error.


..  attribute:: 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'``


..  attribute:: 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:

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

     **Default**::

         {
             create: '/annotations',
             update: '/annotations/{id}',
             destroy: '/annotations/{id}',
             search: '/search'
         }


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

param store:The Store implementation which manages persistence
param Function runHook:A function which can be used to run lifecycle hooks
..  function:: 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…"}


    :param Object annotation: An object from which to create an annotation.
    :returns Promise: Resolves to annotation object when stored.


..  function:: 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"]}

    :param Object annotation: An annotation object to update.
    :returns Promise: Resolves to annotation object when stored.


..  function:: 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.

    :param Object annotation: An annotation object to delete.
    :returns Promise: Resolves to annotation object when deleted.


..  function:: annotator.storage.StorageAdapter.prototype.query(query)

    Queries the store

    :param Object query:
      A query. This may be interpreted differently by different stores.

    :returns Promise: Resolves to the store return value.


..  function:: 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.

    :param Object query:
      A query. This may be interpreted differently by different stores.

    :returns Promise: Resolves when loading is complete.