Making your website "Danno-friendly"

What does "Danno-friendly" mean?

A Dannotate end user normally needs to use the DannoRepeater bookmarklet to see the annotations for the web page that he or she is viewing. This is inconvenient:

  • The user has to have already installed the bookmarklets.
  • The user has to remember to use the bookmarklet.

In addition, the transformations that the Page Repeater performs on a web page do not always result in a fully functional page. Pages with complicated scripting, use of DHTML techniques, use of plugins and so on are particularly prone to "breaking" when viewed through the Page Repeater.

The idea of "Danno-friendly" pages is that the webpage designer does some up-front work to make the pages work with Dannotate. At its core, this work entails adding the equivalent to the HTML elements that are would be injected by the Page Repeater service. The designer then tests the pages to make sure that Dannotate works as expected on the page, adjusting the content and structure to deal with issues arising from the complexity of the page structure and so on. Finally, the designer may add buttons to the page for creating annotations.

The Basics

To make "Danno-friendly" pages possible, you must start by installing the Dannotate servlet on the same host as your web pages. This is essential to avoid client-side security issues. To be specific, if you try to use a Dannotate servlet installed on a different host to your web pages, a correctly configured web browser will refuse to execute the Dannotate javascript because it violates the "Same Origin" security restriction (also known as the "Same Source" rule).

Once the Dannotate server-side components have been installed, the process of making web pages "Danno-friendly" is simple:

  1. Determine the site-relative base URL for the Dannotate servlet container. For example, if you have installed Dannotate as "http://myhost.com/dannotate", this will be "/dannotate".
  2. For each page to be made "Danno-friendly":
    1. Add the following <script> and <link> elements within the page's <head> element.
      <script type="text/javascript" src="/dannotate/dannoconf.js">
</script>
<script type="text/javascript" src="/dannotate/dannolib.js">
</script>
<link type="text/css" rel="stylesheet" 
    href="/dannotate/stylesheets/dannotate.css" 
    media="screen">
    2. Add an "onload="erl.fn.load();" attribute to the <body> element.
    3. Add the following <script> element as the first element within the page's <body> element.
      <script type="text/javascript" src="/dannotate/wz_tooltip.js">
</script>
    4. If you want users to be able to create annotations easily, add a UI control somewhere on each page to run Dannotate's annotation creation tool. The control should call the javascript method "erl.fn.creat()".
  3. Check that you can add annotations to those parts of your pages that you require, that the annotation markers are correctly displayed, and that you can view and 'pin' the annotations. Also check that image annotations work.

    If you see problems, refer to the troubleshooting section for advice on how to track down the root cause. In some cases, you may need to simplify your web page structure to work around problems.

Advanced Configuration

Add material on configuring dannotate policies.

Troubleshooting

Add material on how to find and resolve Dannotate issues.