Annotator Documentation

Annotator is a JavaScript library designed for building browser-based annotation applications. It provides interoperable tools across three main functional areas:

• User Interface: Components for creating, editing, and displaying annotations within a webpage.
• Persistence: Storage components to facilitate saving annotations to a remote server.
• Authorization and Identity: Integration tools to connect Annotator with your application's existing login and permission systems.

Annotator is an open-source JavaScript library designed to add collaborative annotation functionality to web content. It allows developers to implement highlights, notes, metadata, storage, and shared discussions directly on top of web documents.

Key features include:

• Annotation Surface: Turns any web page into an annotatable interface.
• UI Components: Provides tools for creating, viewing, and editing annotations (highlights, comments, and metadata).
• Pluggable Architecture: Uses a modular design that separates browser-side UI and selection logic from identity, authorization, and storage modules.

Annotator is an open-source JavaScript library designed for building web-based annotation systems. It provides tools for:

• Capturing and manipulating DOM selections.
• Storing, persisting, and retrieving annotations.
• Creating user interfaces for annotation.

At its simplest, it allows for textual annotations of any web page with minimal code. It is built as a collection of composable tools, allowing developers to use individual components or the full suite to build custom annotation applications.

Annotator is a browser-side client library designed to be embedded into existing systems. It is not a complete hosted product.

Core Architecture:

• Client Library: Handles text selection, annotation creation (capturing quote and ranges), UI rendering, and lifecycle hooks.
• Storage: Separated from the client. The library uses a StorageAdapter (exposed as app.annotations) to communicate with a backend.
• Identity & Permissions: Pluggable. Default modules include annotator.identity.simple (opaque user identifiers) and annotator.authz.acl (permission-based access control using permissions or user fields).

Annotator is a modular browser library designed for text selection, editing, viewing, and highlighting. The architecture is centered around a composition root and pluggable modules:

• annotator.App: The composition root that includes default modules for authz, identity, and storage.
• ui.main: Handles the user interface, including text selection, editing, and drawing highlights.
• StorageAdapter: Manages the lifecycle of annotations (create, update, delete, load) and dispatches hooks. It is pluggable, allowing for different persistence layers.

When app.start() is called, it binds utilities from the registry and initializes app.annotations as a StorageAdapter.

Annotator uses a plugin-based architecture consisting of modules and hooks:

• Module: An object that extends an application's functionality.
• Hook: A function defined within a module that handles specific tasks delegated to it by the application.

Hooks can be synchronous (returning a value) or asynchronous (returning a Promise). The arguments passed to these hooks vary depending on the specific hook being called. For a list of available hooks, refer to the module-hooks documentation.

An Annotator module is a function that extends the functionality of an ~annotator.App instance. To use a module, pass it to the app.include(moduleFunction, [options]) method. Modules can be simple functions that return an empty object, or more complex functions that return an object containing module hooks or component registrations.

// A simple module
function myModule() {
    return {};
}

// Including the module in an app
app.include(myModule);

// A configurable module using options
function fanfare(options) {
    options = options || {};
    options.url = options.url || 'trumpets.mp3';

    return {
        annotationCreated: function (annotation) {
            var audio = new Audio(options.url);
            audio.play();
        }
    };
}

app.include(fanfare, {
    url: "brass_band.wav"
});

To build the minified package, use the make command:

make pkg/annotator.min.js

When adding a module via app.include(), you can pass an options object as the second argument to customize its behavior. For example, the annotator.storage.http module accepts a prefix option to specify the API endpoint.

app.include(annotator.storage.http, {
    prefix: 'http://example.com/api'
});

In Annotator 1.2, the application was typically initialized via a jQuery integration (e.g., $('body').annotator()). This is removed in 2.0.

In 2.0, you must manually instantiate an annotator.App, include the desired UI modules, and call .start(). To set up a standard application with the default user interface, include annotator.ui.main and specify the target element.

var app = new annotator.App();
app.include(annotator.ui.main, {element: document.body});
app.start();