Add anchors to images

Development
#1

I’m proposing to add anchors to all images that are parsed from XWiki syntax or another Syntax similar to how we do this for headings. It will be possible to override the id by manually setting to id attribute on an image. Further, these anchors will be displayed in the new Lightbox feature such that users can easily find them to use them in links to jump directly to an image or to reference an image using the reference macro.

My current idea would be the following:

  • Add an additional id attribute to the ImageBlock.
  • Add a new version of the onImage-event with an additional id parameter.
  • Add backwards-compatibility by calling the old onImage-method both in the default implementation in the Listener-interface as well as in AbstractChainingListener similar to the listItemRetroCompatibility.
  • Set the id parameter in DefaultXWikiGeneratorListener as well as XWikiGeneratorSink where we also set the heading id.
  • In the XHTML renderer, output the id combined with a class wikigeneratedid unless the id attribute is set in the parameters.
  • In the XHTML parser, remove the id parameter if there is the wikigeneratedid class (and remove that class, too).

Is there anything I have missed? Any other idea how this could be implemented with less changes?

An alternative I considered is to put the id into the generic parameters instead of adding a separate attribute and adding the wikigeneratedid class in the internal XDOM representation. While this (probably) causes less changes, the problem is that this is basically a breaking change for all renderers as when rendering “back” to an input syntax, they would need to ignore the id and the wikigeneratedid class, as otherwise, e.g., the markdown syntax would necessarily need to be adapted to not to render both the class and the automatically generated id into markdown. Also this would be a deviation from the existing approach for heading ids. Therefore, I think this alternative is inferior to the approach described above that should allow renderers to simply ignore the new id.

The Lightbox would also need to be changed to output the id of the image if there is any. I would propose, though, to first check in the code if there is a caption and if yes to prefer any id that is specified in the caption to allow users to easily override the automatically generated id using an id macro in the caption.

Further, the reference macro would need to be changed to take the id attribute of the image into account, too. This will require to bump the required XWiki version to 14.2 (or whatever release contains the proposed changes) unless we use reflection to access the id.

There are some more syntaxes where we might want to add support for the id. In particular, the Markdown syntax will need to be adapted if it shall generate ids for images (otherwise, if the source syntax is Markdown, there won’t be any ids). Further, LaTeX rendering will also require an adaptation to allow using the id in references. Here, ids are useful if the image is nested in a figure. However, to have proper support for references, we need to print the label with the id after the caption, meaning that it needs to find a potentially nested image inside the figure and then print its id at the end of the figure (and not simply while rendering the image syntax).

1 Like