 |
| PDF Annotation |
| Image Annotation |
| Collaboration |
| Document Management |
| Web Research |
| CMS Annotation |
| Document Viewing |
| E-learning |
 |
Adding annotation to external websites
This document describes how to use A.nnotate to integrate annotation features on external websites. This is needed if you want to enable annotation on your pages in situ without taking a snapshot copy. It also allows you to customize the look and feel of the notes and user interface, or replace them with your own versions.
See also adding snapshot buttons to your site which describes a simple way to add a button to let your readers take a personal annotatable snapshot of your pages, or give you feedback; the A.nnotate Server API reference for interacting with an a.nnotate server from your web application and the document embedding guide to include a PDF / Word a.nnotate iframe panel in your site.
Sample code
Sample code to be used with your own installation of a.nnotate is available from:
Updated: June 2010 to work with v3.1.* installations of A.nnotate. Sample code now needs a link to LANG_xx.js to pick user interface language.
Updated: Sep 2010 for IE problem; a correct DOCTYPE declaration is needed on your web pages to put IE into the right rendering mood, e.g.:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
You should unpack it to a new folder in your web space.
NB - all the samples require editing before use so they point to your own installation of annotate and use your own user accounts.
The basic examples included are sample2.html - a minimal web page with annotation enabled and sample3.html - a more complex example with the available configuration settings. There is also sample1.html which demonstrates how to replace the annotate notebox and note display with your own custom renderings - see the advanced guide for details.
index.html -- list of samples sample1.html -- example which replaces the normal notebox with custom GUI sample2.html -- basic example running annotate on an external web page sample3.html -- as above, but with the configuration settings pdfsample1.html -- PDF sample in iframe with custom GUI sampleCrypt.php -- example which encrypts email and passwords in the page annotation_components.js -- sample javascript for the custom sample style.css -- styles for index.html
Basic integration
Step 1: Set up a user account to store notes
To enable annotation on an external website, you need to specify a user on your annotate server who is authorized to upload documents, and that user needs to add the allowed URLs to their list of authorized sites using the 'advanced' section of their account page. For this example, we will use the demo URLs below:
In this example, we want to enable annotation on pages like: http://site1.example.com/docs/page123.html http://site1.example.com/docs/page456.php Our annotate server is installed on: http://server2.example.com/annotate/index.php To setup: 1. Create a test user 'test@example.com' on the annotate server 2. Visit their account page 3. In the advanced section of the account page, add a URL pattern like "http://site1.example.com/docs" to test@example.com's list of sites with annotation enabled. This will allow any web page URL which starts with the pattern to store annotations to test@example.com's account. To allow any page on the site to use annotate, use a pattern like "http://site1.example.com" instead.
Enabling annotation on a site for all users [added Mar 09]
If you would like any user to be able to annotate a site, you can add the URL to the settings in phpconfig.inc. This save you having to enable URL patterns for individual user accounts manually.
$externalURLs = array("http://yoursite.com", "http://othersite.com/somepath");
Step 2: Include the config settings and javascript on your pages
In order to enable A.nnotate on your web pages, you need to add the following scripts before the end of the </body> tag:
<script>
// Settings for a.nnotate:
var _annotate_settings = {
owner: "test@example.com" // *** replace with your account for storing notes
};
</script>
<!-- replace the paths below with links to your annotate server -->
<script src="http://server2.example.com/annotate/js/LANG_en.js"></script>
<script src="http://server2.example.com/annotate/js/web_annotate.js"></script>
<!-- note that since June 2010 you need to pick a suitable LANG_xx.js -->
This loads the javascript required for running A.nnotate; viewers of your web page will be able to attach notes to highlighted text and reply to existing notes. To ensure web browsers display the page and annotations properly, you need to include a doctype declaration at the top of your html pages, e.g. (the simplest one):
<!doctype html>
If annotation isn't working then check the javascript error log and also:
- (1) the owner account is authorized to upload documents;
- (2) you've added the URL of your page to the owner's list on their account page
- (3) you have the correct path to your web_annotate.js in the script
Note attachment to text and dealing with edits
If the text of the page changes, then it is possible for notes to 'fall off' if they can't find the relevant attachment point. A.nnotate offers a way to prevent this if you assign fixed ids to the paragraphs / divs, e.g.
<p id='para1'>
As long as the id of this paragraph remains as
'para1' then notes will stay attached to the text
within.
</p>
<div id='para2'>
The attachment algorithm can cope with text changing
before / after the highlighted phrase, but if the highlighted
phrase itself is deleted, then the note will 'fall off' and
get attached to the page itself rather than the specific text.
</div>
Restricting annotation to a given part of the page
The default setting allows any text / graphics on the page to be annotated - but in some cases you will only want to allow notes on the content text, and not (e.g.) the menus or banner of your page. To enable this, you can set the id of the surrounding div / p to annotate_target :
<div id='annotate_target'>
... here can go the annotatable text on the page
</div>
You can configure the target ID using the target_ids field of _annotate_settings:
var _annotate_settings = {
// ...
target_ids = "div123,div456"
};
You can also disable annotation on particular divs by including priv in the class name, e.g.:
<div class='priv'>
This paragraph will not be annotatable.
</div>
Integrating user logins
Users need to be logged in to an a.nnotate account to save and sign notes - you can use a.nnotate to manage all user accounts using its standard system which uses email addresses to identify users - or you can integrate with your own website's user authentication system.
Option 1: Letting A.nnotate deal with user accounts
When your web page which includes the web_annotate.js code has loaded, A.nnotate checks to see if you are currently logged in. If not, it will show a login box which prompts the user for their email and password and then logs them in. You can position this login box if you create a div on your page with id 'loginbox', e.g.:
<div id='loginbox' style='width:300px; float:right; text-align:center'/>
Option 2: Controlling logins / user accounts using your own system
If you already manage user accounts on your own website, you might want to auto-login users to let them add annotations without making them go through a separate A.nnotate login process too. You can create / modify A.nnotate accounts corresponding to your existing user accounts using the API; the createAccount and updateAccount calls let you set signatures and passwords. Assuming you have set up a user account for 'user123@example.com', adding the user and password fields to _annotate_settings will log on as user123 on viewing the page. You would typically insert these values in the page as part of your web application.
var _annotate_settings = {
// notes will be stored in the owner's account
owner : "test@example.com",
// (optional) the system will try and logon as this a.nnotate user / password
user : "user123@example.com", // log in to page as this user
password : "sesame"
}
[new in v3.0.14] If you would prefer not to expose emails in the javascript source, you can also supply the owner / user / password encrypted using the API key of the first admin user. A sample is included in sampleCrypt.php using DES encryption code from cryptutil.php. There is also a hideEmailAddresses configuration option in phpconfig.inc, which strips email addresses from notes and page metadata.
// Example using encoded emails / account details.
var _annotate_settings = {
// notes will be stored in the owner's account
owner : "crypt-0xab123456...",
// (optional) the system will try and logon as this a.nnotate user / password
user : "crypt-0xef123456...", // log in to page as this user
password : "crypt-0xcd123456..." // ... with this password
}
Providing a 'logout' button
If you would like your users to be able to logout, you can call the annotateLogout() function from your page. The sample sample3.html includes demonstration code for this, and also shows how to add a callback to your code once the logout has completed so you could hide your logout button.
List of configurable settings
A complete list of user-configurable settings is given below; sample3.html includes a demo implementation (you need to replace the 'owner', 'user' and 'password' values for your own system).
var _annotate_settings = {
// Store notes in this account.
// The owner must add the base URL of this webpage
// e.g. 'http://localhost/' to the auth list at the
// end of their Account page
owner : "test@example.com",
// (optional) Auto-login as this user / password - for signing
// notes. The account must have been already set up.
// You do not need to specify user / password; if
// you don't, then annotate will prompt users to login.
user : "test2@textensor.com", // log in to page as this user
password : "ydwuth", // ... with this password
// (optional) Set the title / desc / tags for the page.
// These will get saved in the document metadata.
title : "This is an overridden title",
desc : "The desc to use",
tags : "tag1, tag2, tag3",
// (optional) Hide the top right Tools controls area.
nocontrols : 1,
// (optional) set the target div IDs for annotation
// target_ids : "div123,div456",
// (optional) Provide a function callback after annotateLogout() finished
logoutCallback : myLoggedOut,
// (optional) Provide a function callback once logged in
loginCallback : myLoggedIn,
// (optional) Specify the ID of the folder to store the
// page / notes in, e.g. "2009-01-01/abc123" It should
// be in a folder in the owner's account.
folderid : "", // id of parent folder in owner's account
// (optional) Specify a version number for the page.
// If this is changed, then a new page will be created on
// a.nnotate (with a new date/code id), for a completely new set of notes
version : "2",
// (optional) specify the url of this page rather than auto-detecting it
// from document.location. This could be useful if your web pages
// include session parameters in their URL.
url : "",
// Specify the path to an empty document on *your* site,
// used for the iframe-based communication to the annotate server.
// This is required if your site is on a different server from
// your annotate server, to work around IE problems.
// A sample can be found at http://a.nnotate.com/beta/empty.html
empty_url : "/empty.html"
}
Advanced integration
The advanced integration guide includes instructions for displaying notes on the page with your own javascript code, and replacing the standard draggable notebox with a component which matches the look and feel of your site.