Icon Theme Properties
Reference
The content of an Icon Theme page is a properties file: one key = value per line, the settings below and the icon mappings in any order. Every value is evaluated as Velocity, with $icon holding the name being drawn.
| Property | Description |
|---|---|
| xwiki.iconset.type | image when each icon is a picture, font when each icon is a glyph selected by CSS classes. |
| xwiki.iconset.render.wiki | The XWiki syntax that displays the icon. |
| xwiki.iconset.render.html | The HTML that displays the icon, used when the caller asks for HTML directly. |
| xwiki.iconset.icon.url | The URL of the icon's picture, reported as the url metadata. Set it on an image theme. |
| xwiki.iconset.icon.cssClass | The CSS classes that select the icon's glyph, reported as the cssClass metadata. Set it on a font theme. |
| xwiki.iconset.css | (optional) The URL of a stylesheet the icons need. Several URLs are separated by commas, so a comma inside a URL has to be written %2C. |
| xwiki.iconset.ssx | (optional) The reference of a page holding a Style Sheet Extension the icons need. |
| xwiki.iconset.jsx | (optional) The reference of a page holding a JavaScript Extension the icons need. |
Examples
The bundled Font Awesome theme, a font theme pulling two stylesheets:
xwiki.iconset.type = font
xwiki.iconset.css = $services.webjars.url('org.webjars:font-awesome', 'css/all.min.css'),$services.webjars.url('org.webjars:font-awesome', 'css/v4-shims.min.css')
xwiki.iconset.render.wiki = {{html clean="false"}}<span class="fa fa-$icon" aria-hidden="true"></span>{{/html}}
xwiki.iconset.render.html = <span class="fa fa-$icon" aria-hidden="true"></span>
xwiki.iconset.icon.cssClass = fa fa-$iconThe bundled Silk theme, an image theme:
xwiki.iconset.type = image
xwiki.iconset.render.wiki = [[image:path:$xwiki.getSkinFile("icons/silk/${icon}.png")||alt="" data-xwiki-lightbox="false"]]
xwiki.iconset.render.html = <img src="$xwiki.getSkinFile("icons/silk/${icon}.png")" alt="" data-xwiki-lightbox="false" />
xwiki.iconset.icon.url = $xwiki.getSkinFile("icons/silk/${icon}.png")Icon mappings
Every key that is not one of the settings above is read as a mapping from a name of the XWiki Icon Set to the value the templates substitute for $icon:
accept = check
add = plus
home = houseRendering performance
Three shapes of value are recognised and rendered without going through Velocity, which is faster and shows up most in the icon picker:
- plain text containing $icon or ${icon} once, and no other $ or #
- exactly $services.webjars.url('...'), with one to three single-quoted arguments
- $xwiki.getSkinFile("...${icon}..."), surrounded by text carrying no other $ or #
Any other Velocity is evaluated in full. Open an issue if a shape worth recognising is missing.
FAQ
Does the order of the lines matter?
No. The eight setting names are recognised exactly, and every other key is read as an icon mapping, so settings and mappings can be interleaved.
