openannotation / annotator

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

Annotator

Annotator is a JavaScript library for building annotation applications in browsers. It provides a set of interoperable tools for annotating content in webpages. For a simple demonstration, visit the Annotator home page or download a tagged release of Annotator from the releases page and open demo.html.

Components within Annotator provide:

• user interface: components to create, edit, and display annotations in a browser.
• persistence: storage components help you save your annotations to a remote server.
• authorization and identity: integrate Annotator with your application's login and permissions systems.

Usage

See Installing and Configuring and using Annotator from the documentation.

Writing a module

See Module development.

Development

See HACKING.rst.

Reporting a bug

Please report bugs using the GitHub issue tracker. Please be sure to use the search facility to see if anyone else has reported the same bug -- don't submit duplicates.

Please endeavour to follow good practice for reporting bugs when you submit an issue.

Lastly, if you need support or have a question about Annotator, please do not use the issue tracker. Instead, you are encouraged to email the mailing list.

Community

The Annotator project has a mailing list, annotator-dev, which you're encouraged to use for any questions and discussions. It is archived for easy browsing and search at gmane.comp.web.annotator. We can also be found in the #annotator channel on Freenode_.

annotator's Issues

Create Annotator.noConflict() method

This will remove the Annotator from the global scope and return it from the function. window.Annotator will be re-set to it's previous value. This is useful for the bookmarklet where we do not know the environment the source is to be loaded into.

Add error handling to store plugin

This should provide useful notification to the user if an error occurs while communicating with the store. Examples being.

• 500 Server error
• 404 Resource not found
• 401 Invalid authentication
• 400 Bad request data

Make package.json for Annotator

List development dependencies in a package.json file. At the moment we're using the README to track development dependencies. With a CommonJS package specification, installing development deps would be as simple as:

$ npm install .

Switch from account-key header to account-id header

As per https://github.com/okfn/annotator/wiki/Authentication the header field for the account has changed from x-annotator-account-key to x-annotator-account-id

Update the Markdown plugin to work with new Viewer class

User Plugin: Add an "Anyone can edit checkbox"

Add a checkbox to the annotation window that when checked flags the annotation as globally editable.

Enable tags on bookmarklet

Don't allow annotating the annotator!

We risk running into rather amusing (but not particularly helpful) issues unless we prevent annotating the annotator UI itself. At the moment it's perfectly possible to select the text in the annotator UI and annotate it.

Commentonit - upload and manage texts to annotate

• How do we do this? Have Couchapp already, would Wordpress work?
• Merge into annotateit.org?
• Deferred for the present.

Filter plugin

A toolbar that would appear at the top of the window and allow annotations to be filtered by metadata such as author, tag & date.

Vote/Rate on annotations (upvote/downvote)

LocalStorage Store plugin

Improve the positioning of the editor/viewer if it opens off screen

The viewer and editor should always appear fully on the screen. i.e flip the editor upside down or to the right if necessary.

Cannot uncheck Allow everyone to read checkbox

If you set up bookmarklet to have a default of allowing everyone to read the checkbox cannot be unchecked in the UI.

Bookmarklet: Annotate any web page using a bookmarklet

Workflow:

• Obtain browser plugin (bookmarklet) from annotateit.
• Load/Click into any page to add annotations.
• Display indicator that annotator has been embedded. Help icon?
• Text is then selected and annotations added.
• Annotations are sent to annotate it.
• Revisit the page annotations are fetched.

Questions:

• Which area of the page to add the annotations to
  • ANS: document.body
  • any way to do this better? See Readability https://www.readability.com/bookmarklets/
• Should annotations be submitted automatically - yes.
• How to handle loading. Embed simple progress bar while
  external files are loaded - yes.
• Generating page identifiers using the url (the uri field).
  • How to handle slight variations and query string paramteters - don't.
• Authentication is embedded when bookmarklet is created.
• How to handle updates to codebase? Ping annotateit for updates…

Create an initialisation method for the annotator-full.js file that loads all plugins

A special method that loads all the plugins into the page with some default configuration. The should still be override able.

Cost: 1.5h

Always display edit/delete buttons on annotation viewer

Move Rakefile tasks into Cakefile

Remove dependency on ruby/rake. Notably there are NPM packages providing Node bindings to the YUI compressor

http://search.npmjs.org/#/yui-cli
http://search.npmjs.org/#/yui-compressor

Cannot edit an annotation twice

I am experiencing a bug whereby, in Firefox4, I cannot edit and save an annotation more than once. To reproduce, do the following:

• Load the annotator using the bookmarklet.
• Create an annotation.
• Edit the annotation and save it a first time.
• Edit the annotation and save it for a second time (this time you should receive an error message "Sorry something went wrong with the annotation store").

This seem to affect the current version of the annotator (v1.0.0rc3) used both through the Open Shakespeare installation and the bookmarklet (user agent: "Mozilla/5.0 (X11; Linux i686; rv:2.0.1) Gecko/20100101 Firefox/4.0.1").

Bring couchdb plugin up to date

https://github.com/rgrp/annotator/blob/master/src/plugins/storecouchdb.js

Move homepage header and footer into base.html

missing annotation

<p><b>foo</b>bar</p>

if i select "bar" with annotator, the note will not appear.

Performance testing

See how annotator performs with 100, 1000 or 10000 annotations on a page.

Also what about having 20 annotations in the same place (this is more of a UI issue).

Sidebar theme

A sidebar theme where annotations are shown next to text in a sidebar rather than on hover.

Also discussed was displaying the annotations alongside the article in the browser. Similar to Docco.

2 main options for how this looks/works:

1. Combo lock model (see aron demo)
2. Align and push down model

Make user attribute into an hash

User object should be a hash of form:

# clients can set any attributes
# username field would be used by our User plugin
# id by convention is a unique identifier (at least per Consumer) for the user
user = {
  'id': 'myid' # 
  'username':  # for display purposes client side ...
  # may be used if no username ... (could just overload username?)
  'ip_address': 
} 

Make v1.0 release of annotator

Tag v1.0 release. If we are concerned this is not v1.0 we could call this v1.0rc.

Reduce annotators footprint in the global scope and on the jQuery object

The annotator currently adds numerous plugins onto the global jQuery object as well as extending both the Array & Date prototypes. Also in the global scope are the Annotator, Delegator and Range objects.

Ideally a plugin that is to be included in an unknown webpage (especially in the context of a bookmarklet) should have little to no impact on the host environment. To resolve this only jQuery.fn.annotator() should be exported. Other plugins & functions can then be converted to local helper functions within application closure or added to a utils object. If Range and Delegator need to be accessible outside of the main closure perhaps an annotator namespace object should be created.

Another alternative for the jQuery plugins could be to use jQuery.sub() to create a local copy of jQuery. However this is only supported in jQuery 1.5+.

Delegator constructor should call #addEvents()

It seems unnecessary to have to call this in every subclass that uses the events object. If no events exist Delegator#addEvents() will simply do nothing.

Tag Plugin: Tag entry field does not appear until first annotation is edited

Step to reproduce.

• Open dev.html.
• Create a new annotation.

There will be no tags field in the edit window.

• Save and close the annotation.
• Create/edit another annotation.

Tags field will now appear.

Document the Annotator

Documentation required

• Inline documentation of classes and method using TomDoc
• Wiki pages for public facing API & plugin settings for plugin developers.
• Basic usage instructions for general users.
• Annotator store installation instructions.
• Document authentication setup - copy from http://lists.okfn.org/pipermail/okfn-help/2010-December/000980.html

Add quote field to all annotations

Quote field should be the text that was highlighted.

(Is this possible? What about invalid HTML? Alternative is to do simple snippet -- e.g. first 190 characters)

Store Plugin: Needs to submit unique identifier for the page when saving

This should likely be the current window location. This will then allow the store to return annotations specific to the requested page.

The other option would be to use the Referrer header rather than submitting this as part of the annotation data.

Write annotator v1.0 announce and blog post

Permissions plugin: Make "anyone can *" fields optional

Normalise use of jQuery wrapper on properties containing elements across all classes

Currently Delegator#element and Tags#tags are DOM elements. Annotator#wrapper and Annotator#dom.* are jQuery instances. These should ideally be consistent.

I'd argue for using jQuery instances in all cases as this is a) a jQuery plugin and b) it's cleaner to get a the DOM element from the jQuery wrapper that to regularly create new instances of jQuery.

Wordpress plugin

Work will be done in this separate repo: https://github.com/okfn/annotator-wordpress

• Settings page: enter Account ID and Auth token (secret) option with instructions as to how to get one on annotateit.org
  • Have a regex for pages on which it is enabled. Give standard examples (boilerplate regexps for different use cases; i.e only for a certain blog category).
• Do you enable per page or per blog entry or ...
  • Answer: have a regex on settings page (see above).
  • Do not show when listing blog entries.
• Add annotator js to relevant pages
  • Attach to Wordpress content area.
  • Do you need to be logged in to annotate?
  • If you are logged in want to record your user id / user name for annotation
  • Look at openshakespeare example: http://openshakespeare.org/work/comedy_of_errors
• Deploy to wordpress plugin repository

Outstanding questions:

• What do we use to identify pages (their url seems simplest)

For the future (?):

• Wordpress widget (for latest annotations at the side)
• Dedicated page for recent annotations

Review documentation and choose a documentation library

Review documentation and choose a documentation library

TomDoc seems like a suitable library for working with CoffeeScript

Create Permissions Plugin

Rename User plugin to Permissions and add support for permissions.

Example Usage

The user object is the current user viewing the page. The permissions object will be assigned to each annotation on creation. Each action takes an array of user IDs. An empty array [] means anyone can perform the action.

annotator.addPlugin('Permissions', {
  user: { id: 'Alice', name: 'Alice' },
  permissions: {
    'read': [], // Anyone can read this.
    'update': ['Alice'], // Array of user IDs 
    'delete': ['Alice'],
    'admin': ['Alice', 'Bob'] // Alice and Bob can change these permissions.
  }
});

More notes:
https://gist.github.com/51ed6f3d812b32723c70#file_annotator_%2322.md

Have a quick way to enable fully-featured (all plugins) annotator

Update annotator CSS and add generic styles for form elements

Current design proposal http://cl.ly/4lXC

• I've added a callout arrow to the bottom of each window to make it clear which text the annotation belongs to.
• The three colours of button are for normal/hover/active states.
• Plugin developers can add fields (for all the default form elements) to the bottom of the editor these be styled using generic CSS in the stylesheet.
• Plugins will be separated with a horizontal line. The example shows the Tag and User plugin.
• Same goes for the annotation view on the left.
• Most of the styling can be done with CSS3 (with the exception of the glyphs) to keep file size down.

Issues:

• Need to accommodate for multiple annotations displayed in the viewer.

The Viewer should disappear immediately after the annotation is deleted

Currently the viewer will remain until the mouse moves away.

Problem with Permissions plugin and access to user object

If you try to define a userID function as per https://github.com/okfn/annotator/wiki/Permissions-Plugin and access user object it won't be defined. Need to fix this or document that one must check that user is defined before attempting to use.

Better error handling in SerializedRange()

Currently if the range provided when creating the instance is not part of the document calling normalize() will log Error deserializing range: ... but continue to try and create a range. This will cause a TypeError to be thrown when it cannot find the node value of the non existent elements.

Instead the SerializedRange#normalize() method should return null (in the same way as document.getElementById()) and should be checked for by the implementor and skipped.

Unsupported browser plugin

Generally for use with Internet Explorer, should display a notification explaining that the plugin is not supported by the browser.

Mouseup on selection should be detected no matter where on the page it happens

Copied over from https://github.com/nickstenning/annotator/issues#issue/9

When making a selection that begins inside and ends outside the element to which the annotator is bound, we currently won't detect the mouseup event. Should listen for mouseup anywhere and then determine whether any of the selection lies inside our element.

Decouple Auth plugin from the Store plugin

Currently the Store plugin knows about the auth plugin.

auth = @element.data('annotator:auth')
if auth
  auth.withToken(getAnnotations)
else
  getAnnotations()

A cleaner way to so this might be for the implementor to set the autoFetch option to false when using the Auth plugin. Then call Store.loadAnnotations() when the token has been received:

annotator
  .addPlugin('Store': {autoFetch: false})
  .addPlugin('Auth', { withToken: function () {
     annotator.plugins['Store'].loadAnnotations();
  }})

Test on IE9

Copied over from https://github.com/nickstenning/annotator/issues#issue/20

IE9 now supports text range: http://blogs.msdn.com/b/ie/archive/2010/05/11/dom-range.aspx

We should therefore test with IE9

Bookmarklet: Fix CSS style bleeding

When the bookmarklet is injected into some sites (such as a http://www.alistapart.com/) the sites styles conflict with the annotator.

Hopefully this can be resolved by thoroughly defining all possible styles on key elements like anchors and form elements and then applying !important elements to the generated bookmarklet CSS.

However a more forceful approach such as Cleanslate might be required

Threaded annotations and reply to an annotation

Print styling

I want to print out in dead tree form the document with annotations.

Primary options for rendering:

1. Sidebar
2. Footnotes