In the context of XWIKI-20699, the following issue has been identified.
When a page is moved, the target field of the class used to store annotations (by default XWiki.XWikiComments) is not updated. Consequently, the annotations are not displayed after move since their target does not match the current page (see).
On the other hand, only the XObjects of the current page a retrieved when loading the annotations (here).
From my current understanding, this makes the target property useless because it does not allow to define annotations on a separate document (which could be useful for scalability).
Also, the only way to set the target field to another page is by using the object editor (unless an extension provides such feature)
Option 1
Just remove all the target properties, and stop using it to filter annotations. This would match the current behavior.
Cons: Existing annotations might start showing up on pages that has been moved.
Option 2
Keep the filtering on the target property (for old XObjects), and always initialize it empty for new XObjects.
That way old annotations on moved page won’t show up unexpectedly.
Option 3
make the target field optional
write a data migration to remove target field pointing to the current doc
document the limitation for annotations pointing to other docs (which should never happen in practice, at least not without an extension or manual manipulation of xobjects)
An as a separate improvement:
Fix the fact that “external” annotations are not found (meaning that I’ll replace the current way annotations are retrieved with a query looking on all the pages of the wiki - unless we want to annotate cross-wikis on a farm, which looks like over-engineering)
Here is my +1 for option 1 as I don’t think many annotation will appear in practice, and I’m not aware of scalability issue reported on the annotations.
I’m worried that by removing the target property we will stop supporting some use cases that we’re not aware of. Sure, on XWiki Standard we store annotations as comments and comments are always stored on the target page, making the target property useless, but maybe some extensions or custom flavors of XWiki are using a different xclass and the xobjects are stored on a separate page. Maybe @lucaa knows such a use case since she worked on the Annotation Application when it was fist developed, I think.
the target field of the annotation object is supposed to store the unit of content of a page to which the annotation applies: it can be the content of the page (when the target is the document reference) or a textarea field of an object of that page - in which case the target is a reference to that content.
The annotation API will also allow you to store in XWiki annotation objects that apply to an external content (with a different target reference).
The XWiki standard annotation UI will assume that all annotations that you add from the UI and that you request from the UI are on the content of the page the annotations UI is loaded for.
A custom UI or custom usage / implementation of the annotation API would allow one to store annotations differently.
The target is relevant mainly for the resolution of the annotation context (which is used to place annotations in the given content):
the “contract” is that the annotation context (selection left + annotated text + right context) is unique within the annotation’s target;
the automatic update of the annotation is supposed to update an annotation’s context when its target is updated (which restricts the number of annotations ‘checked’ on an update event, because the target is supposed to restrict them).
In terms of API, Annotations kinda need to have a target.
In terms of the implementation of that API for the storage of annotations of XWiki pages as XWiki objects, indeed the handling of the target can be improved for more flexibility:
we could decide to add a semantic to an empty target field in objects, which would be “current page content”
stop storing in the target field for new annotations, if they match the semantic above (their target is a page content and they get stored as an object of that page)
normally all annotations manipulation should go through the IOService implementation, so updating the save & retrieval functions of the service to implement this should be enough.
Regarding migration, I think there should be one, which should empty targets only of they match the semantic above.
This looks a bit like your option 3 above, with a wiser “cleanup”, and I think it should not cause any regression if you don’t remove all targets wrecklessly.
So +1 for option 3 from me, with modifications.
I’m not sure I understand the first option: it’s about dropping the field altogether? It’s not a great idea, à priori, even if I don’t know of many cases of annotations stored with a specific target to a textarea field of an object, it’s possible, in theory (part of the current API).
Thanks for the explanations. This makes it clear that option 1 is not the way to go (hence, updating my vote to -1 for this option).
Then, we might want to discuss how powerful and modular we want to keep this API. So if somebody knows some use of the annotation outside of XS, that would be interesting.
There is this Scribo - XWiki SAS (the initial project during which annotations were added to XWiki), but as far as I know it was not updated to run on a newer version of XWiki.