Interfacing Annotea Via JavaScript

Document Status

This document was a WorkInProgress and subject to change (e.g. to add/delete issues, bug reports, etc.). As of early 2002, active development on the JavaScript servlet work described here is no longer taking place at W3C due to lack of resources. Refer to the Annotea home page for information about other client interfaces.

Introduction

The W3C's Annotea annotation system is an open, Web-based shared annotation system based on an RDF infrastructure. The W3C has implemented the user interface aspects of Annotea in its Amaya web browser. The tight integration of Amaya and Annotea provides the user with a single entry point to create, edit and view fine-grained annotations.

This document describes an alternate, experimental interface to Annotea that uses JavaScript (JS) and a servlet. The JS interface is browser-independent but when compared with the Amaya implementation of Annotea, it has several limitations that are documented below.

How to Use

The JS interfaces have been tested with Netscape's Communicator (NC) bookmarklet facility as well as Microsoft's Internet Explorer (IE) and the Mozilla browser.

To use the JS interface to create annotations, add the following bookmarklet to the browser and name it something like "Create Annotations":

  javascript:void(window.open('http://www.w3.org/2001/Annotea/Bookmarklet/create_annot.html?title='+escape(document.title)+'&referrer='+escape(document.URL),"CreateAnnotation","width=600,height=450,scrollbars=yes,resizable=yes",""))

To retrieve annotations for an arbitrary document, add the following bookmarklet and name it something like "Retrieving Annotations":

  javascript:void(window.open('http://www.w3.org/2001/Annotea/Bookmarklet/get_annot.html?referrer='+escape(document.URL),"GetAnnotation","width=600,height=320,scrollbars=yes,resizable=yes",""))

Note that the width and height values may be adjusted for the user's preferences. Other browsers that support JavaScript should provide a mechanism for installing bookmarklets.

To use this service, the address of a running Annotea servlet is required. The W3C runs an experimental Annotea servlet at http://www.w3.org/2001/04/AnnoteaServlet.

Advantages of a JavaScript Interface

Any browser that supports JavaScript can be used to create an annotaion
A resource can be annotated without viewing the resource
New annotation types are easy to add

Limitations

There are limitations to a JS-based interface to Annotea (as opposed to native browser support). Some of the limitations are caused by the JavaScript security model which make some useful information unavailable to a script unless certificates are used. Among the limitations are:

The user's name cannot be determined within the script
A script is not allowed to access a local file system thus local annotations are not possible. This also makes it difficult to store configuration information (e.g. the server to use.
Only document-level annotations are possible with this release

Additional Work To Do

Among the additional work that could be done:

Add support for fine-grained annotations. If you have some ideas about how to do that or would would like to work on it, send email to the author.
Create an interface that provides arbitrary queries to an annotation server
Package the JS interfaces into a folder of bookmarklets
Use certificates to eliminate some of the limitiations described above

Known Problems/Defects/Annoyances

Aside from the additional work described earlier, here is a list of known problems, bugs and general annoyances:

Annoyance: cookies are used to store some user supplied data (e.g. the name of the services). If a browser supports cookies and they are disabled, some data may have to be frequently re-entered.
Enhancement: in the record view, make each of the items in the Property column a link and when the link is selected, post a new window with the property's schema.
Enhancement: in the list view, instead of the document at the top being a window, make it an editable text field.
Defect: with IE the caching of username and password apparently does not work. See reference.
Enhancement: in the list view, make selection of Title column invoke the View button. See reference.
Enhancement: add a W3C icon to all of the windows.

The Annotea Servlet

The servlet's Java sources are available in the W3C CVS Repository.

The servlet uses the following Java packages:

HP Lab's Jean RDF API
David Meggison's RDF Filter
The W3C's Jigsaw library

The JavaScript files used by the servlet and the bookmarklets are also in the W3C CVS Repository.

Defect Reporting

Defect reports should be sent to www-annotation.

$Id: Annotea-JavaScript.html,v 1.6 2002/08/14 13:08:20 swick Exp $