Deprecate the `image:icon` syntax

Development
#1

Hello!

Currently, multiple ways to insert icons are available in XWiki. One of these ways is to use image:icon from XWiki Syntax 2.1 . However, as talked about in this topic with @MichaelHamann and @Wardenburg, this way to add icons is not the only one and not the most up-to-date.

I propose to deprecate the image:icon syntax.

This deprecation would lead to:

  • update the UI options from editors to insert a displayIcon macro instead of image:icon syntax.
  • Update the XWiki 2.1 Syntax documentation
  • Close issues related to the image:icon syntax as Won't fix. E.g. XWIKI-10758: Bind icons of the wiki syntax to the icon theme.

Do you agree with this deprecation? Is there any additional step to take to make sure the deprecation process is complete?

Lucas C.

1 Like
#2

So the question is whether we want to have a way to insert a macro in the syntax or not.

Personally and from a user POV I think it makes sense, in the same way as we can insert an image using the syntax. I don’t see why we wouldn’t have a way to insert an icon.

If I had to choose I would deprecated the macro instead as this is look unnecessary (again from a user POV). I read the forum post quickly but couldn’t see why a macro was introduced. It says it was to fix a rendering bug but it doesn’t why it was not possible to fix in the rendering itself.

Note that it’s hard or impossible to deprecate a syntax feature. The only thing you can do is create a new syntax (like xwiki/2.2) and make it the default and convert docs to it. You can ofc document that it’s not recommended to use some syntax for XYZ reasons.

Also, it’s possible that this proposal would actually require a VOTE since it’s something quite important to remove a syntax feature.

To sum up, I don’t like that, for some technical reasons, we remove a syntax feature that makes sense to exist. Is there no other way?

Thanks

#3

At least my idea and understanding is that we wouldn’t remove the actual syntax but just the UI for inserting it. The actual syntax wouldn’t be removed but deprecated, i.e., we don’t recommend using it but we still support it.

The problem with the old syntax is that this is a special type of image reference. We have no way to resolve an image reference to something that is not an image but our current default icon theme doesn’t provide any image. This would be a huge hack in the renderer to support inserting an arbitrary blob of HTML if a certain type of image reference is used (currently, we only support resolving the reference to some image URL). Also, when the syntax is displayed in CKEditor, CKEditor displays it with an image widget as this syntax is supposed to produce an image. If this syntax no longer produces an image, the CKEditor UI will break as, e.g., you cannot resize the icon the same way as you can resize an image and also all other features are centered around the idea that an image syntax produces an HTML <img /> element.

1 Like
#4

For completeness, there is another clean option if we want to keep the icon syntax: We deprecate icon themes that don’t provide images and replace the current default icon theme by one that uses SVG images instead of the icon font (this could be the very same icons, just as SVG). The image-based icon syntax could then work for all icon themes that are based on images. However, we would still need the displayIcon macro to support icon themes that aren’t based on images as we can’t simply not support them anymore (icon themes using arbitrary HTML for icons are a well-documented extension API).

We could also introduce a nicer icon theme format that isn’t based on Velocity execution at the same time. To me this sounds like a nice but also limiting solution.

I’m +1 to deprecate the image:icon syntax but if somebody wants to spend the time, I’m also not against switching to SVG-based icons, having icons as true images could make a lot of things easier but we would need a plan at which point we consider it okay to no longer consider non-image icon themes.

#5

My two cent input. A while back I created the following for my users and myself documenting this fact:

XWiki Icons

Currently, you have the following ways to insert XWiki Icons:

  • For Silk Icons - In WYSIWYG editor, use insert "Image” dialogue, choose the “Icon” tab.
    ____________ - In Source mode or Wiki editor, enter [[image:icon:IconName]] where “IconName” is the name, once saved the image will be produce. (XWiki Syntax 2.1 Images).
  • For Silk or Font Awesome Icons - In WYSIWYG editor, use “XWiki Macro” dialogue, find and select “Icon” for “Icon Set” enter “Font Awesome” or “Silk”. (Icon Macro).
    Note: For both you’ll need the icon name, see XWiki Icon Set or famfamfam.com Silk View All

image