Form Based Annotations

In Kaukolu, you can annotate arbitrary character sequences of a wiki page's body with an RDF class of your choice (the annotation's concept class). That way, not only the page itself gets enriched with semantics, but also arbitrary contents down to the granularity of a single character.

Annotations are not only represented by their concept class, but also using additional information such as their author, their time of creation and an optional comment or description. This information can be Literal, i.e. contain string that is entered in an input field, or referential, i.e. contain a reference to another annotation. Currently only one annotation can be assigned as such a reference, although RDFS allows to model arbitrary cardinalities.

Usage Information

While annotations can be created programmatically, we have also created a dynamic HTML form that can be used to create annotations manually on a wiki page. Besides selecting the desired class from a tree containing all loaded ontologies, the process has been extended to restrict the selection complexity depending on previously created annotations.

Basic Usage

In order to create an annotation, select the text you want to annotate, press the right mouse button and select 'Create Annotation', as depicted here:

This will bring up the dialog which allows you to select the concept for the annotation and enter additional information such as the parameters used to instantiate the concept class as well as the optional comment. For demonstrating purposes, a license ontology used to describe software licenses has been loaded into the repository; these classes serve as possible annotation concepts here. However, any RDFS class in the underlying repository is a possible target for being used with an annotation. Click 'Create' to submit the form and create the annotation.

Create Annotation

After the page has reloaded, you will see the list of annotations for the currently active page on the left hand side. Each box corresponds to one annotation, and selecting it will make the web browser scroll smoothly to the annotated part of the wiki page and highlight the respective character sequence. The selected concept has been automatically instantiated with the arguments you provided in the form, and appears as statements in the 'Relations' box.

Creating Drawings

The presented concept tree contains the class Drawing which is supposed to be the super class for drawing related annotation classes. The ability to create an SVG drawing is an inherent part of Kaukolu and considered throughout all annotation related aspects.

After selecting the class SVGDrawing form the concept tree, the right-hand side usually showing all properties of the selected class in order to be completed is replaced with a drawing pane. The user can create a free-hand drawing within this pane which is then stored as a standard conform SVG string in the backend along with automatically created properties such as author or creation date. When such an annotation is visualized at some place, a downsized version of the created drawing will be displayed along with before mentioned properties.

Create Drawing

Restrict Selection

The annotation panel contains further tabs restricting the selection of possible classes by considering existing annotations within the current page.

The tab labeled Recent presents all recently used annotation classes that are expendable in a tree view. Whenever a new annotation is created for the current page its class will be added to this pane.

The mechanism behind Overlapping follows the basic idea of having references between classes, implying the referenced annotation is contained in the textual scope of the referencing one. Thus, the logic behind compiling eligible classes for this view is a little bit more complex. In the first step all annotations overlapping with the currently selected text are identified, i.e. annotations that are contained in, start within or end within the selected text area. After determining the set of their corresponding classes, all referential attributes (i.e. non Literal) are collected. Finally, the set of all classes that are qualified to be referenced by the overlapping annotations are presented, again, in a tree view.

Search classes

The Search tab pays tribute to arbitrarily complex ontologies where the exact name or only a part of a class name is known. Instead of clicking through possibly large hierarchies attempting to find the desired class, the user can enter a regular expression in a search field which is evaluated against all known annotation classes. The result is presented in a tree view on order to allow browsing for existing subclasses as well.

Search Annotation

Define References

The definition of references between annotations on the same page offers a powerful mechanism to organize information extracted from the document. Nevertheless, defining and managing them can become quite cumbersome. In the following let us assume we want a Legal Statement annotation reference a Condition annotation.

One way is to connect them ex post. This means we first create the Condition annotation followed by the Legal Statement. The right-hand side then offers a combo box for the property "condition" containing all eligible annotations on the current page, i.e. those of the class Condition and its subclasses, represented by their class name and the comment line allowing to distinguish multiple annotations of the same type.

Another possibility is their nested creation. When we create the Legal Statement right away, the condition cannot be selected as a property since it does not exist yet, but clicking on the button Create Now performs all necessary steps. The Legal Statement is instantly stored in the back end along with all information that has been entered so far, i.e. literals as well as other associations, and the panel is closed immediately without reloading the page. Now, we select the text that represents the condition we want to reference and choose to create a new annotation. This step is performed as usual, except for the limited availability of classes. Right after having clicked on "Create", the annotation panel will reopen with the Legal Statement in a different view revealing two differences. The left-hand side shows the static descendant tree of the current class which is not selectable, because the annotation already exists. Most importantly, the just created condition is already assigned to the according property, such that no further action is necessary. We can click cancel now to keep everything as it is currently displayed, or we can edit literal properties and even define further references as before.

Define Reference (Nested)

The described process can be arbitrarily nested. The section "Outer Annotation" on the left-hand side keeps track of the current hierarchy.

Edit / Delete Annotation

Annotatios can be deleted in several ways. One option is to click on the "Delete" link within an annotation box located in the side bar, but its functionality is obsolete and is expected to vanish with future versions of Kaukolu. Another option is to hover over the desired annotation, right click and select "Delete Annotation" yielding a sub menu containing all annotations at the current position. Hovering over a menu item allows to identify the desired annotation, because this immediately highlights the corresponding text. A right click on the paragraph icon offers the same functionality. A more detailed description of these elements in can be found at AnnotationDisplay.

The necessary steps to edit an annotation are similar, they just differ in the first menu item. When the annotation panel is opened in edit mode, only the static descendant tree is presented on the right-hand side, but all properties can be changed is if this was a new annotation - even nested annotation can be created without any restriction. Currently, SVG Drawings can not be edited but must be redrawn.

Design Thoughts

  • Exploit referential properties of cardinality > 1
  • Offer geometric primitives for SVG drawings. The code is prepared to support this.
  • Functionality to edit drawings, like extending or removing segments.

Technical Aspects

Some words on the technical aspects: The annotation form is realized using the DOJO JavaScript toolkit. The concept tree is not hard coded, but is built dynamically (and incrementally when expanding tree nodes), and served to the DOJO panel as a JSON object. The right hand side of the form is also being built dynamically. Whenever the user selects a concept from the tree, the repository is queried for the corresponding RDF class and its properties. This information is then used to create HTML form objects that take the input arguments. Requests are posed asynchronously, i.e. using AJAX-style interaction and are backed by Java servlets.


All JavaScript / DOJO / AJAX related aspects are contained in the JavaScript and JSP file. AJAX request are handled by the servlets and delegated to the Annotation Manager which in turn communicates with the Annotation Store.

Typical Use Case

The user selects a text passage with the mouse, performs a right-click and selects "Create Annotation". The annotation panel appears showing a class hierarchy on the left-hand side (served by AnnotationContentServlet.getChildren()). He expands various tree nodes before the desired class is found and clicks on it. The corresponding properties are presented on the right-handside (served by AnnotationContentServlet.getAnnotationFormHtml()). He enters some information and clicks on "Create". This triggers AnnotationActionServlet.createAnnotation(), followed by AnnotationManager.createAnnotation()) and AnnotationStore.storeAnnotation().

The page reloads. The user hovers the annotated text, does a right-click, expands "Edit Annotation" and selects the underlying annotations. The annotation panel opens showing the descent tree on the right-hand side (served by AnnotationContentServlet.getDescentTree()) and the currently stored properties on the right hand side, generated by the usual method. The click on "Update" goes a similar way to trunk/kaukolu/src/de/opendfki/kaukoluwiki/storage/

A click on "Delete Annotation" in the context menu results in a call to trunk/kaukolu/src/de/opendfki/kaukoluwiki/storage/ in the end.

Key functions in annotation.js:

  • initAnnotationFormCallback() -- initializes the form and handles submission
  • fillAnnotationSearchTree() -- performs the class search
  • editAnnotation() -- edit an annotation
  • jsonFromInstanceParams() -- creates the property string for an annotation

References to the source code

Last modified 9 years ago Last modified on 02/13/08 13:47:08

Attachments (7)

Download all attachments as: .zip