Annotations Prototype Playground

Last modified by Anca Luca on 2010/03/20 23:35

[02-03-2009] An update of the annotations prototype has invalidated all annotations already added, they will not be visible anymore (I also deleted the xwiki objects from the pages).

[19-02-2009] An update of the annotations prototype has invalidated all annotations already added, they will not be visible anymore (I also
deleted the xwiki objects from the pages).

[15-01-2009 later] A new update of the annotations prototype has invalidated all annotations already added, they will not work anymore. See the Known issues section.

Welcome to the annotations test space! The new annotations prototype is enabled in this space so that you are able to play around with it.

Please keep in mind that this is not a final version (nor releasable for that matter), it has a few missing bricks (see below).


A few things you need to know and setup so that your annotation experience is smooth.

  • First of all, make sure you're logged in and you use a local user (on the 'incubator' wiki and not the global user for
  • Second, set the color of your annotations by going here and setting the color (as HTML code or human readable name e.g. yellow, red, green, #ff00ff, etc). Save that, come back to the Annotations space and have fun.
  • Make sure all the documents you're trying to annotate use xwiki/2.0 syntax (or anything rendered with the new rendering model, in a word, anything not xwiki/1.0.


Checkout the "Annotations" menu you see in the action menu (next to the "Watch" menu): click it and it will open the annotation settings panel (kindof empty for the moment, though).

  • to add a new annotation, select the text you want to annotate and hit Ctrl(Meta) + M or Ctrl(Meta) + I and a dialog with a form will appear: fill in and submit.
  • to see the metadata of an annotation, hold the mouse over the annotation icon at the end of the annotated text
  • Should all work fine now on all browers, please report any issues you might find. Please use firefox, chrome or opera if you want to also add annotations (not only visualize). All works fine on IE except for adding please use Firefox browser for the moment, we know for sure it works. On the macs there seems to be an issue with Firefox, please use Safari and/or Chrome. On windows it doesn't seem to work at all.


Before you get bored reading, here's some fun! Following are a few examples of documents that are handled by annotations extension, to show what annotations can do in term of content to annotate (and render annotations on).

  • Shakespeare sonnet 130 is a document with static content, it's all set in the document content in xwiki/2.0 syntax. You can add annotations on any piece of it, edit the formatting of the document add links, put tables, edit the text in the document, add content or delete content (keep in mind the known issues below though).
  • A presentation of myself is a document with a mix of scripted content and static content. All the edits will also work on this document, but the information which depends on the current user will only be visible to those users.
  • "If" poem, by Rudyard Kipling, stored as a collection of stanzas with comments on them, in XWiki objects in the document. The document has no actual content, only the inclusion of a sheet. As usual, you can annotate everything, also edit the document inline and modify existing stanzas or add new ones.
  • A document in russian about wikis (I hope) using Cyrillic alphabet

Known issues

[02-03-2010] Updated annotations prototype: handling annotations that appear multiple times in their context, fixed maintainer to ignore whitespaces on mapping the annotations for update. 

[23-02-2010] Updated annotations prototype: rights checking server side & client side. 

[21-02-2010] Annotations prototype was updated: better UX (edit form does not go away on mouseout), IE UI fixed for all versions. 

[19-02-2010] Annotations prototype was updated: more client fixes, annotation display on icon hover & edit, typed annotations. 

[11-02-2010] Annotations prototype was updated: client updated to a newer version, with more fixes. 

[08-02-2010] Annotations prototype was updated: new UI prototype is now up, any feedback about its look and feel is welcome. Enjoy!

[15-01-2010 later] A new update of the annotations prototype has invalidated all annotations already added, they will not work anymore

[15-01-2010] Annotations prototype was updated: now annotations are updated when the document changes.

[22-12-2009] Annotations prototype was updated so a few known issues were fixed, strikedthrough in the list below.

There are a few things you need to be aware of, so that you're not surprised when they happen:

  • the annotations details display in a bubble when hovering the icon in the annotated document is not implemented yet
  • when selecting text to annotate, selection should be as simple as possible for the moment (not contain formatting or links or other annotations or cross paragraph, etc). It's a client side small issue to be fixed asap.
  • when canceling the add annotation form, the selected text remains highlight
  • the User Interface and usage of the browser client is very far from being perfect, you'll probably experience a lot of issues with it. Please keep you calm, trust us that it will get better, and focus your experiments on the content to annotate and annotations rendering.
  • for the moment the maintainment of the annotations when the document is updated has a few limitations, the basic idea being that as long as the annotated text is visible, the annotation will be displayed in the document. Particularly:
    • if the annotated text of an annotation is modified upon document edit, the annotation is not updated, it is still displayed in the right panel but it's not displayed in the document any longer. Housekeeping in the list of annotations in the panel is left to the user. However if the document is rolled back to the version where the text of the annotation was present, the annotation will be displayed in the document. 
    • the same will happen if the annotated text is deleted. If annotated text is deleted it will not even be displayed in the panel in the right.
    • if a document is edited so that the text of an annotation is duplicated, your annotation might relocate to the first occurrence of the annotated text.
    • if the annotation contains some content generated by a macro, the annotation will only be displayed for the cases when the text is visible (for example, if it's some text that changes with current user, only the user that added the annotation will be able to see it displayed in the doc.)
  • the annotations cannot be edited, the only way to go is delete and then add again
  • there are a few cases when displaying annotations will fail: when the annotated text is generated by a {{html}} macro, and when the annotated content is a link with a generated label (freestanding URI or link with no label set).
  • depending on the content, you might experience issues with rendering the document with annotations on it (see some pieces of uninterpreted script). Just reload the page.
  • if an annotation starts (or ends) in the middle of a word, it will be displayed in the document from its beginning (to its end).
  • IE7, IE8: the 'Add annotation' dialog is wrongly placed at the top of the page. Annotation dialogs are badly positioned on IE6