Wiki source code of Icon Script Service
Last modified by Eleni Cojocariu on 2026/08/25 16:23
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The ##$services.icon## script service is how a Velocity script reaches the icons of the wiki's [[Icon Theme>>doc:documentation.xs.admin.icons.icon-themes.WebHome]]. Every method takes a name of [[the XWiki Icon Set>>doc:documentation.xs.admin.icons.icon-set.WebHome]] and, where a second argument is accepted, the name of the theme to take that icon from; [[Display an Icon in a Script>>doc:documentation.xs.dev.icons.display-icon-script.WebHome]] walks through the calls a page usually needs. | ||
| 2 | |||
| 3 | |=Method|=Returns | ||
| 4 | |##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. | ||
| 5 | |##render(name, theme)##|The same macro call, naming the theme to draw the icon from. | ||
| 6 | |##render(name, theme, fallback)##|The same macro call, carrying the ##fallback## parameter. | ||
| 7 | |##renderHTML(name)##|The HTML that draws the icon, for output that is already HTML. | ||
| 8 | |##renderHTML(name, theme)##|The same, from the named theme. | ||
| 9 | |##renderHTML(name, theme, fallback)##|The same, with the fallback to the built-in icon set switched off when ##fallback## is ##false##. | ||
| 10 | |##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. | ||
| 11 | |##getMetaData(name, theme)##|The same, from the named theme. | ||
| 12 | |##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. | ||
| 13 | |##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. | ||
| 14 | |##use(theme)##|The same, for the named theme. | ||
| 15 | |##iconSetNames##|The names of every Icon Theme available in the wiki. | ||
| 16 | |##iconNames##|The names the theme in use maps. | ||
| 17 | |##getIconNames(theme)##|The names the named theme maps. | ||
| 18 | |##currentIconSetName##|The name of the Icon Theme the wiki uses. | ||
| 19 | |##getLastError()##|The exception stored by the last call that failed. | ||
| 20 | |||
| 21 | == Failures == | ||
| 22 | |||
| 23 | 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. |
