Icon Script Service
Reference
The $services.icon script service is how a Velocity script reaches the icons of the wiki's Icon Theme. Every method takes a name of the XWiki Icon Set and, where a second argument is accepted, the name of the theme to take that icon from; Display an Icon in a Script walks through the calls a page usually needs.
| Method | Returns |
|---|---|
| render(name) | A displayIcon macro call in XWiki 2.1 syntax, which draws the icon when the surrounding content is rendered. The call itself renders nothing. |
| render(name, theme) | The same macro call, naming the theme to draw the icon from. |
| render(name, theme, fallback) | The same macro call, carrying the fallback parameter. |
| renderHTML(name) | The HTML that draws the icon, for output that is already HTML. |
| renderHTML(name, theme) | The same, from the named theme. |
| renderHTML(name, theme, fallback) | The same, with the fallback to the built-in icon set switched off when fallback is false. |
| getMetaData(name) | A map describing the icon instead of markup, holding iconSetName, iconSetType (FONT or IMAGE), cssClass on a font theme and url on an image theme. |
| getMetaData(name, theme) | The same, from the named theme. |
| getMetaData(name, theme, fallback) | The same, with the fallback switched off when fallback is false, which gives an empty map for a name the theme does not map. |
| use() | Pulls the stylesheet and the extensions of the icon set built into the distribution into the page, not those of the theme the wiki uses. Returns nothing. |
| use(theme) | The same, for the named theme. |
| iconSetNames | The names of every Icon Theme available in the wiki. |
| iconNames | The names the theme in use maps. |
| getIconNames(theme) | The names the named theme maps. |
| currentIconSetName | The name of the Icon Theme the wiki uses. |
| getLastError() | The exception stored by the last call that failed. |
Failures
Nothing throws. A method that fails stores its exception and returns nothing, so a page renders an empty icon rather than an error box, and getLastError() reports it for the rest of the request. A successful call does not clear it, so read it right after the call it belongs to.
FAQ
How is the icon name escaped in the macro call render returns?
For XWiki 2.1, so a name holding syntax characters cannot break out of the macro call it is placed in.
Is the same API available to Java code?
Yes, and the script service is a thin wrapper over it: the IconManager, IconSetManager and IconRenderer components of xwiki-platform-icon-api expose the same operations, and throw where the script service swallows.
