Annotation Layer

#What happens when a user clicks the annotation button?

When a user clicks on the "comments icon," they are clicking on a link found in the $.Hud template. When clicked, this fires an event bound to the class .mirador-osd-annotations-layer.

This event in turn looks for the the annoState state machine and calls a function depending on the current state of this state machine.

When the $.Hud object is created it first fires a function called createStateMachine() which creates a new StateMachine assigned to annoState. In the creation of this StateMachine a number of callback events are defined that will trigger depending on the current state of the machine.

The states are:

• none: the initial state
• annoOff: the annotation layer is off
• annoOnCreateOff: the annotation layer is on, and if there is a known annotation endpoint database, the ability to draw new annotations is turned off
• annoOnCreateOn: the annotation layer is on, and if there is a known annotation endpoint database, the ability to draw new annotations is turned on

In the case of turning on annotations, displayOn is triggered, which publishes modeChange for this window to displayAnnotations. It also publishes windowUpdated with the current state.

This modeChange is the key to changing the UI experience. However, the sequence of events to load the annotations was initiated before the user ever clicked the annotations button.

In order to see how these annotations got loaded, we have go back in time to when ImageView was originally loaded. When a single image view is chosen, for example from ThumbnailsView, an ImageView object is initialized. A number of things happen here, but we are going to focus on how the AnnotationLayer gets created. As part of the ImageView creation createOpenSeadragonInstance() is called. This function does a lot of things to allow the image to load. But once this is completed addAnnotationsLayer() is fired.

This function initializes the $.AnnotationsLayer object (widgets/annotationsLayer.js). On initialize this function calls createRenderer(); createRenderer() creates another object called the $.OsdCanvasRenderer (annotations/osd-canvas-renderer.js). This object needs to be passed a number of pieces of information that can be traced back to the original $.ImageView call including the OSD in question, the id of the window to be populated, and most importantly the annotationsList to be used.

This annotationsList is acquired from the parent of the $.ImageViewer object which is the $.Window object.

When the $.Window object is originally initialized, it executed getAnnotations(). getAnnotations() populates annotations in two ways:

1. It uses the URI of annotationsList associated with the current canvas and requests the list using jQuery's get() method. The returned list of annotations gets added as an array of objects to the $.Window.annotationsList property.
2. If an annotation endpoint/database has been configured and Mirador has the necessary information to communicate with it, it will send a search request to that endpoint and populate the resulting JSON (as OA) to $.Window.annotationsList.

This property is what then gets passed from $.ImageView to $.AnnotationsLayer and finally to $.OsdCanvasRenderer, now as just list and no longer as annotationsList.

It is finally here in the $.OsdCanvasRenderer that the blue boxes the user sees outlining an annotation area get created.

But it is not immediately obvious when this is done because $.OsdCanvasRenderer does not actually call any functions on initialization. However, it does have a render() function.

render() takes the list array and, for each annotation within the list, creates a div and places that div on the designated regions of the OpenSeadragon canvas. To do this, it uses parseRegion() to get the coordinates of the annotation and then uses getOsdFrame() to create rectangle bounds on the OSD canvas.

But the question remains, when did render() get fired? For this we have to return to $.AnnotationsLayer.

At the end of createRenderer() which initialized $.OsdCanvasRenderer, a final function named modeSwitch() is called.

modeSwitch() is basically a switch to execute different actions depending on the mode of the annotationsLayer.

Currently there are three possible modes:

• displayAnnotations - display annotations only. This triggers enterDisplayAnnotations() which:
  • Triggers $.OsdRegionRectTool's exitEditMode()
  • Triggers $.OsdCanvasRenderer's render()
• editingAnnotations - display and draw new annotations (only when an annotation endpoint is defined and configured), triggers enterEditAnnotations() which:
  • Creates a $.OsdRegionRectTool for drawing new annotations
  • Triggers $.OsdCanvasRenderer's render()
  • Triggers $.OsdRegionRectTool's enterEditMode()
• default - do not display annotations, triggers enterDefault() which:
  • Triggers $.OsdRegionRectTool's exitEditMode()
  • Triggers $.OsdCanvasRenderer's hideAll()

The the user click of the "show annotation button" occurs, the publish() method triggers an event called modeChange and when the mode changes, the bounding boxes are bound.