Skip to Content

Icons

Version 1.12 by Lucas Charpentier (Sereza7) on 2024/02/09
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Using icons in XWiki

In order to add an icon in XWiki content, use the Icon Macro in your velocity template. This is the recommended way, by default it will fetch the icon from the current icon theme.

In order to add an icon in a Velocity script, you can use the icon manager script service with syntax such as $services.icon.renderHTML('add').

In the codebase, you might still find some other ways to use icons that are deprecated:

  • Use the XWiki Syntax for icons . As of now, these icons do not follow the current icon theme and are always rendered using Silk. See XWIKI-10758: Bind icons of the wiki syntax to the icon theme . Moreover, using this syntax can pose a security threat.ErrorTODO
    Ping Michael to eventually link the security issue relevant to this point.
  • Use icon references as the image background of your HTML node. This method should be avoided to reduce technical debt.

Icon themes

XWiki supports multiple icon themes. On a standard flavor of XWiki, Silk and Font Awesome (FA) are available. As of now, the default on the standard flavor is Font Awesome 4.

 

List of available icon theme extensions

XWiki icon set

This is the set of icons that XWiki wants to support. Naturally, they should be present in every Icon Theme!

The icons are sorted alphabetically.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.FrontendResources.Icons.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Icon strategy

As of now, there's a consensus that the skeuomorph based Silk icons do look out of place in our modern UI.
One of the long term goals of the development team is to migrate the default to a more up to date icon theme.
However, integration of Silk icons in some UIs sometimes pre-dated the icon theme feature. This is why some elements of the XWiki interface use hard coded Silk icons. Replacing those icons with actual icontheme references is not always easy, because the concept they picture is not always mappable in other icon themes, and there's no easy conversion from Silk to the icon theme. This is especially apparent for technical icons: in Font Awesome, there's no icon for all kind of fields we could show in Silk, and there's no icon for the `composite` icons from Silk such as `addfile`, `editfile`, `addcomment`, `adduser`. Technically, most of those icons could be done with Font Awesome icon stacking, but those icons are difficult to find in any icon theme, so it might not make the most sense to add them to the icon set.

As of now, we can see that hard coded Silk references are still present.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected