Add annotations to wiki pages

Description

The Annotations Application improves wiki experience by allowing users to annotate text in a 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 for Colibri Skin

• Check "Show annotations"

To see an annotation for a text item click on the yellow icon next to it.

All annotations can also be displayed at the bottom of the page in the Annotations tab. To enable the Annotations tab follow these steps:

• Hover over "Wiki" and click on "Administer Wiki"
• Click on "Page Elements"
• Set the "Show document annotations" to "Yes"

Edit annotations

There are two ways to edit an annotation.

You can edit an annotation straight from the page. Click on the annotation icon to view the annotation and then 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 click on the annotation icon to view the annotation and then 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 clicking on 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 have 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 the 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 (Wiki -> Administer Wiki).

In this section, you can configure:

• If annotations are active on the whole wiki or a subset of locations
• 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).

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

Annotations Shortcuts

Annotations

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

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
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-annotation-ui 16.10.1):

• org.xwiki.platform:xwiki-platform-annotation-scripting 16.10.1
• org.xwiki.platform:xwiki-platform-annotation-io 16.10.1
• org.xwiki.platform:xwiki-platform-annotation-rest 16.10.1
• org.xwiki.rendering:xwiki-rendering-macro-html 16.10.1
• org.xwiki.platform:xwiki-platform-rendering-macro-include 16.10.1
• org.xwiki.platform:xwiki-platform-rendering-macro-velocity 16.10.1
• org.webjars.npm:fast-diff 1.3.0