Annotations Application

Add annotations to documents

Description

The Annotations Application improves wiki experience by allowing users to annotate text in an XWiki document.

Anca's talk at FOSDEM 2011 demoing XWiki's Annotation and explaining how they work:

Make annotations

To make an annotation to a piece of text all you have to do is select the text, hit Ctrl + M (Meta + M) and a dialog will appear where you may enter the text you want to associate with the selection. Click "Add annotation" and you're done.

Show annotations

By default annotations are not shown within the page.

To see the annotated items highlighted:

• Click on the Annotations link at the top of the page

• Check "Show annotations"

To see an annotation for a text item hover over the yellow icon next to it.

All annotations are also displayed at the bottom of the page in the Annotations tab.

Edit annotations

There are two ways to edit an annotation.

You can edit an annotation straight from the page. Hover over the annotation and click on the yellow pen. Once you are done with the changes click "Update".

The alternative is to edit annotations from the Annotations tab at the bottom of the page. Similarly you need to click the yellow pen, change the text and click "Update" when you are finished modifying the text.

Delete annotations

There are three ways of deleting an annotation.

To delete an annotation from the page hover over the annotation and click the red "X" button.

You have the same option if you're editing the annotation from the page.

You may delete annotations from the Annotations tab at the bottom of the page by clicking the "X" button next to the annotation.

Edit annotated text

Congratulations! You've successfully added annotations to your text. 

Taking into consideration the text is on a wiki there's a high probability it will be modified. As a result you may be confronted with the issue of whether an existing annotation is relevant to the newly changed piece of text. You'll notice the icon next to the annotated piece of text is orange instead of yellow. This helps you easily identify which of the annotated pieces of text have suffered changes, without consulting page history.

When hovering over the orange icon a popup will appear. You have the following options:

• Validating the annotation for the new text by clicking the green button
• Editing the annotation to better describe the modified text
• Deleting the annotation altogether

You may validate the annotation from the Annotations tab as well.

Delete annotated text

When an annotated piece of text is deleted, the annotation for the deleted text can still be seen in the Annotations tab. The annotation will be marked with a red icon and the following message: "This annotation could not be displayed because the annotated text was not found in the document"

Filter annotations by author

By default when you check "Show annotations" all annotations for that page are displayed. To filter annotations by author click on "Refine display criteria" and check those authors for which you would like to see annotations.

Configure annotations

The annotations feature can be configured in the dedicated section in the wiki administration section (global menu -> XWiki -> Administer Wiki).

In this section, you can configure:

• If annotations are active on the whole wiki or a subset of spaces
• If annotations are displayed by default or only when checking "Show annotations" on each page
• If the annotations highlight should be displayed always or only on hovering an annotation or the structure of annotations (through an xwiki class).

Note that after changing the configuration of the annotations in the Admin section you clean your browser's cache, otherwise the new settings will not be taken into account (or force refresh the pages with annotations, if you don't want to clear all the cache).

Threaded Annotations

Starting with version 4.0M2, annotations have been merged by default with comments. More specifically, this means:

• You can now reply to an annotation (threaded annotations)
• The Annotations tab is now replaced by the Comments tab where you can see both annotations and comments
• The default annotation class is now XWiki.XWikiComments instead of AnnotationCode.AnnotationClass

Troubleshooting

After: 

• wiki-farm deployment by XE Manager, 
• default wiki-pages import into empty wiki-farm -
  Annotation application will fail to run. Read more to know how to fix it.

Prerequisites & Installation Instructions

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions