Skip to content
This repository

Annotation tools for the web. Select text, images, or (nearly) anything else, and add your notes.

README: Show build status for master only

Only show build status for the master branch in README. Switch to SVG badge while we're at it.
latest commit f19aac8527
Nick Stenning nickstenning authored
Octocat-spinner-32 .tx Add transifex-client configuration (see http://help.transifex.net/fea… March 16, 2012
Octocat-spinner-32 contrib [WIP] Reincorporate bookmarklet build March 02, 2014
Octocat-spinner-32 css css: fix button gradients June 08, 2013
Octocat-spinner-32 doc Clean up .gitignore March 02, 2014
Octocat-spinner-32 example Remove unneeded script tags from dev files November 03, 2013
Octocat-spinner-32 img Add permalink detection and display to Viewer. March 20, 2012
Octocat-spinner-32 lib Embed jQuery in the built annotator March 30, 2014
Octocat-spinner-32 locale Fixed the broken building of the i18n template. (Which did not make t… July 08, 2013
Octocat-spinner-32 src Merge pull request #357 from openannotation/318-no-custom-delegator-e… April 13, 2014
Octocat-spinner-32 test Merge pull request #357 from openannotation/318-no-custom-delegator-e… April 13, 2014
Octocat-spinner-32 tools Remove references to the AnnotateItPermissions plugin April 12, 2014
Octocat-spinner-32 .ackrc Add .ackrc to ignore files in lib/ and pkg/ May 29, 2013
Octocat-spinner-32 .gitignore Add packaging directories to .gitignore March 30, 2014
Octocat-spinner-32 .travis.yml enable node v0.10 in travis February 25, 2014
Octocat-spinner-32 AUTHORS Add @sa2ajj to AUTHORS January 31, 2014
Octocat-spinner-32 HACKING.markdown Update test dependency documentation January 31, 2014
Octocat-spinner-32 LICENSE Add licenses February 16, 2011
Octocat-spinner-32 LICENSE-GPL Add licenses February 16, 2011
Octocat-spinner-32 LICENSE-MIT Add licenses February 16, 2011
Octocat-spinner-32 Makefile Make dist should make a tarball April 11, 2014
Octocat-spinner-32 README.markdown README: Show build status for master only April 16, 2014
Octocat-spinner-32 coffeelint.json Enable coffeelint on source files: fixes #302 April 04, 2014
Octocat-spinner-32 demo.html de-jquery-ify demo.html April 04, 2014
Octocat-spinner-32 dev.html Wean Auth off Annotator.Plugin April 11, 2014
Octocat-spinner-32 dev.xhtml Refactor dev.xhtml for browserify November 02, 2013
Octocat-spinner-32 index.js Restore standalone pattern and browserify plugin April 04, 2014
Octocat-spinner-32 main.js Use the UMD bundle for AMD loaders as well April 10, 2014
Octocat-spinner-32 manifest.json first pass at chrome April 06, 2012
Octocat-spinner-32 markup.html Embed jQuery in the built annotator March 30, 2014
Octocat-spinner-32 package.json Bump version to 2.0.0-dev.2 April 11, 2014
README.markdown

Annotator

Build Status Stories in Ready

Annotator is a web annotation system. Loaded into a webpage, it provides the user with tools to annotate text (and other elements) in the page. For a simple demonstration, visit the demo page or download a tagged release of Annotator and open demo.html.

The Annotator project also has a simple but powerful plugin architecture. While the core annotator code does the bare minimum, it is easily extended with plugins that perform such tasks as:

  • serialization: the Store plugin saves all your annotations to a REST API backend (see Storage wiki page for more and a link to a reference implementation)
  • authentication and authorization: the Auth and Permissions plugins allow you to decouple the storage of your annotations from the website on which the annotation happens. In practice, this means that users could edit pages across the web, with all their annotations being saved to one server.
  • prettification: the Markdown plugin renders all annotation text as Markdown
  • tagging: the Tags plugin allows you to tag individual annotations

Usage

To use Annotator, it's easiest to download a packaged release. The most important files in these packages are annotator.min.js (or annotator-full.min.js), which contains the core Annotator code, and annotator.min.css, which contains all the CSS and embedded images for the annotator.

Annotator requires jQuery. As of Annotator v1.2.7, jQuery v1.9 is assumed. If you require an older version of jQuery, or are using an older version of Annotator and require the new jQuery, you can use the jQuery Migrate Plugin. The quickest way to get going with Annotator is to include the following in the <head> of your document (paths relative to the root of the unzipped download):

<script src='http://ajax.googleapis.com/ajax/libs/jquery/1.9/jquery.min.js'></script>
<script src='annotator.min.js'></script>
<link rel='stylesheet' href='annotator.min.css'>

Or, with migrate:

<script src='http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js'></script>
<script src= "http://code.jquery.com/jquery-migrate-1.2.1.js"></script>
<script src='annotator.min.js'></script>
<link rel='stylesheet' href='annotator.min.css'>

You can then initialize Annotator for the whole document by including the following at the end of the <body> tag:

<script>
  $(document.body).annotator()
</script>

See demo.html for an example how to load and interact with plugins.

Writing Plugins

As mentioned, Annotator has a simple but powerful plugin architecture. In order to write your own plugin, you need only add your plugin to the Annotator.Plugin object, ensuring that the first argument to the constructor is a DOM Element, and the second is an "options" object. Below is a simple Hello World plugin:

Annotator.Plugin.HelloWorld = (function() {

  function HelloWorld(element, options) {
    this.element = element;
    this.options = options;
    console.log("Hello World!");
  }

  HelloWorld.prototype.pluginInit = function() {
    console.log("Initialized with annotator: ", this.annotator);
  };

  return HelloWorld;
})();

Other than the constructor, the only "special" method is pluginInit, which is called after the Annotator has constructed the plugin, and set pluginInstance.annotator to itself. In order to load this plugin into an existing annotator, you would call addPlugin("HelloWorld"). For example:

$(document.body).annotator()
                .annotator('addPlugin', 'HelloWorld')

Look at the existing plugins to get a feel for how they work. The Markdown plugin is a good place to start.

Useful events are triggered on the Annotator element (passed to the constructor of the plugin):

Callback name Description
annotationsLoaded(annotations) called when annotations are loaded into the DOM. Provides an array of all annotations.
beforeAnnotationCreated(annotation) called immediately before an annotation is created. If you need to modify the annotation before it is saved to the server by the Store plugin, use this event.
annotationCreated(annotation) called when the annotation is created. Used by the Store plugin to save new 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. Allows a plugin to add extra form fields. See the Tags plugin for an example of its use.
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 displayed provides the annotations being displayed
annotationViewerTextField(field, annotation) called when the text field displaying the annotation in the viewer is created

Development

See HACKING.markdown

Community

The Annotator project has a mailing list for developer discussion and community members can sometimes be found in the #annotator channel on Freenode IRC.

Something went wrong with that request. Please try again.