Jquery Plugin: dcookorg_annotator

This is a plugin, that builds on JQuery and JQueryUI, to allow selecting parts of an image (or any DOM item) and adding some text for this. It supplies load/save functions that can be used to pass the data to a back-end server (via form or ajax), or saved to a cookie, etc.

Usage Example

To add the annotator to an image use this simple command:


demo1.html shows an image that you can add as many annotation as you wish. You can then save them, and view the next page which shows the static view. (Cookies are used for the sake of a simple demo, but of course you can instead use ajax or embed the data into a form to send to a back-end server.)

demo2.html is similar to demo1.html but a bit more complex; instead of using the comment box under each annotation it displays a form on the right. Only the active annotation has active form elements; the others show static text.

To save the need for csv escaping and parsing demo2.html uses the form-feed escape character as a separator. However see the commented out lines for how to use a comma instead. demo2.html can also show all the callback events: change show_debug from false to true to enable this.


MIT license, meaning you are free to use it in both private and commercial projects, and free to adapt it however you wish.


The plugin comes in a single file, documented fairly well with a comment block at the top of the file: dcookorg_annotator.js. It should reduce to 2-3Kb if minimized. It is alpha-quality (but already fairly well tested on all of FF3 (linux), FF3.5 (win), IE6, IE7, IE8 and Safari(win), and I expect a beta quality release in the next month or two).

Please download and host on your own server.

Other required files: jquery, jqueryUI (at least the draggable and resizable components), and the jquery CSS file. See the demo file source for how to include the first two files from other servers. If you can drag but cannot get any handles to resize with then it means the css file is missing. You can get a css file from http://jqueryui.com/download


Released: 2010-08-18, 13.7Kb. dcookorg_annotator.0.6.js (alpha)

Minor addition: add an option to specify the div name; allows extra annotators on an image, outside the main set of annotators (i.e. quite a rare usage case).


Released: 2010-07-25, 13.1Kb. dcookorg_annotator.0.5.js (alpha)

Add options to control CSS for active and inactive annotations; also the comments box.

Add a "callback" mode, which is like "static" mode, but allows using a callback (mode_callback) to control what appears in the annotation box. An example callback ($.dcookorg_annotator_show_number) is included, which will put a centered number in the annotation box. Partly example usage, but also useful.

Note: This is still marked as alpha, as the API might still expand or even change, but the code is now well-tested in a range of browsers.


Released: 2010-06-15, 12.1Kb. dcookorg_annotator.0.4.js (alpha)

Bug fix in dcookorg_annotator_load() (options were overriding loaded data, instead of the other way round). Also delete function bug fix. Fully backwards-compatible, no new features.


Released: 2010-06-11, 12Kb. dcookorg_annotator.0.3.js (alpha)

All backwards compatible, but adds two new features:

  • A 'movable' mode; this is just like 'editable', but without the comment input box underneath the annotation box.
  • Callbacks to allow connecting to custom functionality (such as the form shown in demo2.html). In dcookorg_annotator_add(): on_create, on_active, on_inactive, on_delete, preprocess_options; and in dcookorg_annotator_toString(): on_data.


Released: 2010-06-06, 9.9Kb. dcookorg_annotator.0.2.js (alpha)

dcookorg_annotator_toString() and dcookorg_annotator_load() now take an optional options parameter, allowing read/writing position in either pixels or as percentage of the parent div. dcookorg_annotator_toString() is backwards-compatible to 0.1, but dcookorg_annotator_load() has changed.


Released: 2010-04-23, 8.3Kb dcookorg_annotator.0.1.js (alpha)

Bug Reports, Future Development And Helping Out

Contact me at darren at dcook.org. Putting "dcookorg_annotator" in the subject should help get you past my spam filters.

If you find a problem please let me know a URL where I can try it out; also let me know your browser and which version of jquery and jqueryUI you are using. If you can let me know if your browser works fine with all the demos on this page, that will also help troubleshooting.

Let me know of any cool sites or demos you make using this plugin! And if you are a designer and want to snaz up the look of this page, or any of the demos, let me know.