JavaScript API

JavaScript API

Annotorious provides a JavaScript API you can use to get, add or remove annotations, and hook into the Annotorious event lifecycle. All functionality is exposed via the global anno object. The anno object has the following methods

• anno.addAnnotation(annotation)
• anno.addHandler(type, handler)
• anno.addPlugin(pluginName, opt_config_options)
• anno.getAnnotations(opt_image_src)
• anno.makeAnnotatable(item)
• anno.removeAnnotation(annotation)

anno.addAnnotation(annotation)

Adds an annotation. Create your annotation as an object literal, according to the following example:

var myAnnotation = {
  /** The URL of the image where the annotation should go **/
  src : 'http://www.example.com/myimage.jpg',
 
  /** The annotation text **/
  text : 'My annotation',
 
  /** The annotation shape **/
  shapes : [{
    /** The shape type **/
    type : 'rect',
    
    /** The shape geometry (relative coordinates) **/
    geometry : { x : 0.1, y: 0.1, width : 0.4, height: 0.3 }
  }]
} 

Some notes on annotation shapes:

• Although the shapes field requires an array of shapes, Annotorious will only use the first shape in the array, and disregard all others. (The array is there for future use, and for reasons of compatibility with other annotation systems.)
• Currently, rect (rectangle) is the only supported shape type.
• Per default, Annotorious uses a normalized coordinate system. The example above represents a rectangle that starts at a horizontal (vertical) distance of 10% of the image's width (height); has a width of 40% of the image's width; and a height of 30% of the image's height.

Optionally, you can also express geometry coordinates in pixel units. See below for an example:

var myAnnotation = {
  /** The URL of the image where the annotation should go **/
  src : 'http://www.example.com/myimage.jpg',
 
  /** The annotation text **/
  text : 'My annotation',
 
  /** The annotation shape **/
  shapes : [{
    /** The shape type **/
    type : 'rect',

    /** 'units' is required unless you want to use relative coordinates! **/
    units: 'pixel',
   
    /** The shape geometry (pixel coordinates) **/
    geometry : { x : 10, y: 10, width : 40, height: 60 }
  }]
}

anno.addHandler(type, handler)

Adds an event handler function. Code example:

// Logs newly-created annotations to the console
anno.addHandler('onAnnotationCreated', function(annotation) {
  console.log(annotation.text);
});

Annotorious issues the following events:

• onMouseOverItem(event) - fired when the mouse enters an annotatable item
• onMouseOutOfItem(event) - fired when the mouse leaves an annotatable item
• onMouseOverAnnotation(event) - fired when the mouse enters an annotation
• onMouseOutOfAnnotation(event) - fired when the mouse leaves an annotation
• onSelectionStarted(event) - fired when the user starts a selection
• onSelectionCanceled(event) - fired when the user cancels a selection (not available on all selection tools)
• onSelectionCompleted(event) - fired when the user completes a selection
• onSelectionChanged(event) - fired when the user changed a selection
• beforePopupHide(popup) - fired just before the annotation info popup window hides
• onAnnotationRemoved(annotation) - fired when an annotation is removed from an imgae
• onAnnotationCreated(annotation) - fired when an annotation was created

anno.addPlugin(pluginName, opt_config_options)

Registers a plugin. For more information, see the Plugins Wiki page.

anno.getAnnotations(opt_image_src)

Returns the current annotations. opt_image_src is optional. If omitted, the method call will return all annotations, on all annotatable items on the page. If set to a specific item URL, only the annotations on that item will be returned.

anno.makeAnnotatable(item)

Makes an item on the screen annotatable (if there is a module available supporting the item format). You can use this method as an alternative to CSS-based activation. It works just the same way, and is simply there for convenience, and to prepare for (future) item formats that technically don't support CSS-based activation (such as Web maps).

anno.removeAnnotation(annotation)

Removes an annotation from the page.