Browser requirements

The Dannotate software is designed to work with a range of web browser without installing any trusted plugins. In the current release, Dannotate works best with one of the following open source web browsers:

• Firefox 2 & 3.x.x (Linux, Mac, and Win32)
• Safari 3.2.x & 4.x (Mac and Win32)
• Google Chrome 1.0.x (Win32)
• Opera 9.x (Win32)

Dannotate will also work with Internet Explorer 8, though there are inclined to be interoperability issues; e.g. annotations not displaying in the correct place. Dannotate will also work with IE8 running in IE7 compatibility mode.

Dannotate does not work with IE7 and earlier versions due to poor support of web standards by these browsers. We strongly recommend that you install and use one of the open source browsers listed above. If you cannot do this, you should discuss your options with your local systems administrators.

(Other combinations of web browser and OS platform may also work. We simply have not tried out all of the possible permutations.)

Installing the Dannotate Bookmarklets

Before you can use Dannotate to view and create annotations, you need to add some bookmarklets in your web browser' toolbar.

You start by visiting the "home page" of the Dannotate installation you want to use. (An indicative example may be found here, but it is important that you use the page that corresponds to "your" annotation server.) You should see three links called "Dannotate", "DannoRepeat" and "Dannotate Preferences".

If you are using one of the open source browsers you simply need to "drag and drop" each of the links into your web browser's tool bar. For example:

1. Move your mouse to get the cursor over the link.
2. Click and hold down the left mouse button to "pick up" the link.
3. Move the mouse so that the cursor is over the toolbar.
4. Release the left button to "drop" the link.

If you are using Internet Explorer, the procedure is a bit different:

1. Move your mouse to get the cursor over the link.
2. Click and hold the right mouse button.
3. Select "Add to favorites" from the popup menu and release the mouse button.
4. You will now see a popup warning about installing bookmarklets. Click the "yes" button.
5. Finally, you should see another popup window that allows you to set the name of the bookmarklet. Make any changes you want to, then click "ok".

Depending on your browser, you have now installed the Dannotate bookmarklets in either your browser's toolbar or your Favorites menu. You can use them by either clicking the toolbar entry or selecting from the menu in the normal way.

Using the Page Repeater

The Danno Page Repeater allows you to see any annotations and replies that have been associated with a web page or image.

To use the Page Repeater, you use your web browser to visit the page of interest, and then you click the "DannoRepeat" bookmarklet (or select it from the Favorites menu). This will do the following:

1. The URL of the web page will be sent to the Page Repeater service (co-located with the Dannotate service), together with any cookies that have been set in your browser for the page.
2. The Page Repeater will send a GET request to fetch the page from the server, passing your cookies to establish your security credentials.
3. The Page Repeater will take the HTML returned by the server and insert script tags for the Dannotate client-side libraries, a link to a stylesheet and an 'onload' attribute to trigger Dannotate client-side initialization.
4. When the modified HTML is loaded by your browser, the "onload" triggers a request to the Dannotate server-side to fetch any annotations for the page.
5. If any annotations are found, the Dannotate client-side inserts visible annotation tags into the web page at the relevant points.

This should all takes a second or two. When it is done, you should see the original web page, with little numbered tags indicating places where someone has previously made an annotation. For an example of what this should look like, go the UQ eResearch Group's Dannotate Demo Page. The green tags are annotations, and the pink tags are replies.

To see what an annotation or reply says, simply move the cursor over the tag. As you do this, a "hover" window will be displayed showing the title and text of the annotation, the name of the user who created it, and its date/time stamp. You can "pin" the "hover"

Creating an Annotation

Suppose that you now want to create your own annotation on a web page. Here's how you do it.

1. If you haven't already done so, view the page to be annotated using the Page Repeater as above.
2. Use the mouse to select (highlight) the region of text that you want to attach your annotation to.
3. Click the "Dannotate" bookmarklet in your toolbar (or select it from your "Favorites" menu). You should now see a pop-up window with an annotation creation form.
4. Enter the title and comment text of your annotation.
5. If you want to, use the selector to change the annotation type. The alternatives (for an untailored Dannotate installation) are "Comment", "Question", "Explanation", "Example", "Advice" and "See also".
6. When you are satisfied, click the "Submit" button.
7. The annotation form should be temporarily replaced with a message that telling you that the annotation has been created.
8. When the message window closes, you should see a new annotation tag for your annotation at the appropriate point on the web page, as viewed via the Page Repeater.

Note:

1. If you take a long time (5 minutes with default server settings) to create an annotation or reply, the callback that is used to add the annotation tag will timeout and the tag won't appear. If this happens, you can simply refresh the page.
2. If you don't select any text before starting the process of creating an annotation, the implied "context" of the annotation will be the entire we page. Whole-page annotations are indicated by floating tags that are displayed in the top left hand corner of the page.

Editing an existing Annotation

Once you have created an annotation, you may want to alter the text or title. You can do this as follows:

1. Move the cursor over the tag for the annotation that you want to edit, and left-click to pin the annotation "hover" window.
2. Click the "Edit" button at the bottom of the pinned window. The pinned window will close and will be replaced with another window containing a form for editing the annotation.
3. Edit the title, comment text and/or type as required.
4. When you are satisfied, click the "Submit" button.
5. The form should be temporarily replaced with a message telling you that the annotation has been updated. This should then close.

Notes:

1. Editing and deletion of annotations and replies can be disabled using a configuration property.
2. It is possible to edit or delete anyone's annotations. This will be addressed when fine-grained access control is implemented.

Replying to an Annotation

Danno allows you to create replies to annotations, and to other replies resulting in a tree shaped "dialog" rooted in a single annotation. The procedure for creating a reply is almost identical to the one for editing an annotation:

1. Move the cursor over the tag for the annotation that you want to reply to, and left-click to pin the annotation "hover" window.
2. Click the "Reply to Annotation" button, and you should be presented with a form for creating a new Reply.
3. Fill in the title and comment text, and adjust the reply type as required.
4. When you are satisfied, click the "Submit" button.
5. You should see a "Reply created" message, and a new (pink) tag should be inserted following the tag for the annotation that you replied to.

Note that you can edit a reply in the analogous fashion to editing an annotation, and you can also reply to a reply.

Deleting an Annotation or Reply

To delete an annotation or reply, you simply pin the object's "hover" window, and then click the "Delete" button.

Notes:

1. Deleting an annotation will also delete the tree of replies to the annotation.
2. Editing and deletion of annotations and replies can be disabled by a configuration parameter.
3. It is possible to edit delete someone else's annotations and replies. This will be addressed when fine-grained access control is implemented.
4. Deleting an annotation or reply does not trigger the removal of the corresponding tags from the displayed page. Refreshing the page will do this, and will also cause the remaining tags to be renumbered.

Image Annotations

In addition to annotating text, Dannotate supports the annotation of images embedded in webpages, and even free-standing web-accessible images. Where the context of a text annotation is a sequence of characters, the context for an image annotation is a subregion of the image bounded by a rectangle. Here is how you create one:

1. In a browser window showing the image you want to annotate, move the cursor to the image.
2. Holding down the SHIFT key on your keyboard, use the mouse to left click and hold at the top left corner of the subregion.
3. With the SHIFT key and the mouse button both held down, move the cursor to the bottom right corner of the subregion, and then release the mouse button.
4. You should now see a rectangular pink box drawn over the image. If the designated is incorrect, click outside of the box and start again.
5. If the designated is correct, click inside the box. This will give you a popup form to fill in the annotation details.
6. Complete the annotation details and click "Submit" as for a text annotation (see above).
7. When the process has completed, you should see a red rectangle corresponding to your annotation superimposed on the image, together with an annotation tag. Hovering over the tag will display the actual annotation.

Notes:

1. You can annotate both images embedded in web pages and "bare" images. To annotate a bare image, copy the image URL to your browser's URL type-in, visit the URL, and then use the "DannoRepeat" bookmarklet to view it. You can now see any existing annotations, and create new ones as above.
2. Annotations on an embedded image are actually annotations for the page the image is embedded in. Annotations on a "bare" image, are annotations for the image itself. This may seem an esoteric distinction, but it determines where annotations are visible.

The Live Updates Experimental Feature

We have recently added an experimental live updates feature to Dannotate that shows you new and updated annotations and replies in close to real time. To see this feature in action, do the following:

1. Open two tabs in your browser and use them to view some page that you want to annotate. Use the Page Repeater if necessary.
2. In one tab, select some text and create an annotation.
3. When the annotation has been created, watch what happens in the second tab. Within 30 seconds (assuming default settings) you should see a new annotation marker added corresponding to the annotation that you just created. Note that the new tags have a more intense color than the existing ones.

The current implementation of live updates is not scalable. Each browser tab polls the Dannotate servlet every 30 seconds to see if any annotations or replies for the current page have been created or updated. This in turn generates one or more requests to the Danno server. While Danno and Dannotate are fast, the traffic generated by many browser tabs polling the servers would eventually swamp the server.

We have some ideas about how to make Live Updates more scalable, but these involve major changes to the Danno / Dannotate codebase. In the meantime, the pragmatic solution to increase the polling interval, stop polling after a period of inactivity or (ultimately) turn off polling.

Dannotate User Preferences

Dannotate supports a few user configurable preferences. For example, you can choose the default name used when creating annotations, you can change the way that annotation tags are numbered, and you can adjust the level of messages that are displayed. The following procedure can be used to change your preferences:

1. Start the Dannotate Preference Editor using the "Dannotate Preferences" bookmarklet.
2. Use the editor to make the changes you want.
3. When you are done, click the "Save Preferences" button.

Dannotate user preferences are stored as browser cookies. You must have cookies enabled in your browser to change the settings from their default values. The preferences are tied to your current browser and machine.