Annotation Module

{toc:initlevel=2|maxlevel=4|numbered=true}

Building and installing the annotations snapshot.

This requires either on a 2.1(.1) XWiki or a 2.2 snapshot.

• Grab the sources from https://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/xwiki-annotation-parent/##
• Go in and type mvn clean install
• Copy the following jars in the WEB-INF/lib folder of your installation:
  • xwiki-annotation-core/target/xwiki-annotation-core-1.0-SNAPSHOT.jar
  • xwiki-annotation-io/target/xwiki-annotation-io-1.0-SNAPSHOT.jar
  • xwiki-annotation-rest/target/xwiki-annotation-rest-1.0-SNAPSHOT.jar
  • xwiki-annotation-reference/target/xwiki-annotation-reference-1.0-SNAPSHOT.jar
  • xwiki-annotation-velocity/target/xwiki-annotation-velocity-1.0-SNAPSHOT.jar
  • only if on a 2.1(.1) xwiki-annotation-model-backport/target/xwiki-annotation-model-backport-1.0-SNAPSHOT.jar
  • only if you want annotations updated when documents are edited also install the maintainer at xwiki-annotation-maintainer/target/xwiki-annotation-maintainer-1.0-SNAPSHOT.jar along with the java-diff lib from http://maven.xwiki.org/externals/org/incava/java-diff/1.1.0/java-diff-1.1.0.jar
• Import xwiki-annotation-application/target/xwiki-annotation-application-1.0-SNAPSHOT.xar application in your wiki
• Add Panels.AnnotationManager panel to XWiki presentation (in Administer Wiki > Presentation).

Usage

Enabling/Disabling this feature

You can enable/disable annotation feature by changing the boolean activated field of XWiki.AnnotationConfig object in XWiki.AnnotationConfig page (/xwiki/bin/edit/XWiki/AnnotationConfig?editor=object).

Defining your annotation color

To do so please set up annotationColor field of XWiki.XWikiUsers object in XWiki.YOURID page. Valid value is any css predefined color name or hexadecimal code.

Let's annotate

Annotation system works by selecting some 'regular text' while keeping control key pressed down, which will display an annotation add dialog. This will enable you to enter some text you want to associate to the selection. On the right side you can see the annotation management panel that let you see and remove annotation. Just put your pointer on an item to see annotation highlighted. Click on it to keep annotation highlight, click again to disable this behaviour. To delete an annotation click on the delete icon.

For developers

Following is a class diagram of the main annotation application components:

As you can see on the diagram, AnnotationFeature uses AnnotationTarget in order to alter both selection (using SelectionService) and document source (using severals Alterers and IOTargetService).

AnnotationFeature use IOService in order to retrieve/modify/remove stored annotations.

Once location is computed the module use IOService in order to store annotations in XWiki DB.

AnnotationMaintainer is used each time a document is modified. It uses a diff algorithm in order to update annotations location.