Touch Annotator Plugin

A plugin for the OKFN Annotator that improves the usability of the tool on touch devices. It has been tested on the following devices.

iPhone running iOS 5
iPad running iOS 5
Samsung Galaxy Tab running Android 3.2
Android Emulator running Android 4

There is a demo available online.

Usage

The plugin requires the annotator.js and annotator.css to be included on the page. See the annotator Getting Started guide for instructions then simply include the annotator.touch.js and annotator.touch.css file in your page. These can be downloaded from the GitHub download page.

<link rel="stylesheet" href="./annotator.css" />
<link rel="stylesheet" href="./annotator.touch.css" />
<script src="./jquery.js"></script>
<script src="./annotator.js"></script>
<script src="./annotator.touch.js"></script>

Then set up the annotator as usual calling "addPlugin".

jQuery('#content').annotator().annotator("addPlugin", "Touch");

Options

There are a few options that can be provided to the "addPlugin" call.

jQuery('#content').annotator().annotator("addPlugin", "Touch", {
  force: true,
  useHighlighter: true
});

force: Forces the touch controls to be loaded into the page. This is useful for testing or if the annotator will always be used in a touch device (say when bundled into an application).
useHighlighter: Some touch devices do not allow the browser access to the selected text using window.getSelection(). highlighter.js is provided in the /vendor/ directory to try and address this issue. If you wish to use this feature it needs to be manually enabled (as it can't be feature detected). Include the script in your page and set this option to true.

Example

The example.html file provided gives a demo of the plugin in action. The various options can be toggled by adding query string parameters.

For example http://localhost:8000/example.html?force&highlighter:

force: Enable the plugin on desktop browsers.
highlighter: Use the highlighter.js fallback.

Development

If you're interested in developing the plugin. You can install the developer dependancies by running the following command in the base directory:

$ npm install .

Development requires node and npm binaries to be intalled on your system. It was developed with node --version 0.6.6 and npm --version 1.1.0 -beta-4. Details on installation can be found on the node website.

Then visit http://localhost:8000 in your browser.

There is a Cakefile containing useful commands included.

$ cake serve # serves the directory at http://localhost:8000 (requires python)
$ cake test  # opens the test suite in your browser
$ cake watch # compiles .coffee files into lib/*.js when they change
$ cake build # creates a production pkg/annotator.offline.js file
$ cake pkg   # creates a zip file of production files

Repositories

The development branch should always contain the latest version of the plugin but it is not guaranteed to be in working order. The master branch should always have the latest stable code and each release can be found under an appropriately versioned tag.

Testing

Unit tests are located in the test/ directory and can be run by visiting http://localhost:8000/test/index.html in your browser.

Frameworks

The plugin uses the following libraries for development:

Mocha: As a BDD unit testing framework.
Sinon: Provides spies, stubs and mocks for methods and functions.
Chai: Provides all common assertions.

License

This plugin was commissioned and open sourced by Compendio.

Released under the [MIT license][#license]

wootfox / annotator.touch.js