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, opt_replace)
• anno.addHandler(type, handler)
• anno.addPlugin(pluginName, opt_config_options)
• anno.getAnnotations(opt_image_src)
• anno.highlightAnnotation(annotation)
• anno.makeAnnotatable(item)
• anno.removeAnnotation(annotation)
• anno.setSelectionEnabled(enabled)

anno.addAnnotation(annotation, opt_replace)

Adds a new annotation, or replaces an existing annotation with a new annotation. (In the latter case, the parameter opt_replace must be the existing annotation.)

Create the new 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 currently uses the first shape in the array only. All other shapes are disregarded. (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.

Using pixel coordinates: 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 }
  }]
}

Making annotations 'ready-only': in most cases, you probably don't want users to be able to delete or edit the annotations you have added via the API. You can easily make them 'read-only' by adding an additional field to the object literal:

editable : false

If this field is set to false, there will be no delete icon in the annotation popup.

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.highlightAnnotation(annotation)

Highlights the specified annotation, just as if the mouse pointer was hovering over it. The annotation will remain highlighted until one of these conditions is met:

• The user moves the mouse into, and out of the annotation
• The user moves the mouse over another annotation
• Another annotation is highlighted via anno.highlightAnnotation

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.

anno.setSelectionEnabled(enabled)

Disables (anno.setSelectionEnabled(false)) or enables (anno.setSelectionEnabled(true) - default state) the creation of new annotations alltogether. The typical use case for this is 'read-only' annotated images. I.e. if you want to add some pre-defined annotations using anno.addAnnotation without the user being able to add or change anything.