Wiki source code of Icon JavaScript API
Last modified by Eleni Cojocariu on 2026/08/25 16:23
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{version since="17.10.5, 18.2.0"}} | ||
| 2 | Browser code reaches the icons of the wiki's [[Icon Theme>>doc:documentation.xs.admin.icons.icon-themes.WebHome]] through the ##xwiki-icon## RequireJS loader plugin, which fetches them over the [[Icon REST API>>doc:documentation.xs.dev.icons.rest-api.WebHome]] and hands back one object per icon, each able to draw itself. | ||
| 3 | {{/version}} | ||
| 4 | |||
| 5 | The names are declared in a module of their own, and the module that uses the icons depends on it through the loader, so that one request fetches them all: | ||
| 6 | |||
| 7 | {{code language="js"}} | ||
| 8 | // The names to load, in a module of their own. | ||
| 9 | define('my-module-icons', { | ||
| 10 | icons: ['home', 'cross'] | ||
| 11 | }); | ||
| 12 | |||
| 13 | define('my-module', ['xwiki-icon!my-module-icons'], function(icons) { | ||
| 14 | // Each icon draws itself into a new element. | ||
| 15 | document.querySelector('.my-icon-wrapper').append(icons.home.render()); | ||
| 16 | |||
| 17 | // The metadata the REST API reports sits on the same object. | ||
| 18 | const isFontIconTheme = icons.cross.iconSetType === 'FONT'; | ||
| 19 | }); | ||
| 20 | {{/code}} | ||
| 21 | |||
| 22 | |=Property|=Description | ||
| 23 | |##name##|The name of the icon in [[the XWiki Icon Set>>doc:documentation.xs.admin.icons.icon-set.WebHome]]. | ||
| 24 | |##iconSetName##|The name of the Icon Theme the icon was taken from. | ||
| 25 | |##iconSetType##|##FONT## when the theme draws the icon with a font glyph, ##IMAGE## when it draws a picture. | ||
| 26 | |##cssClass##|The CSS classes that select the glyph, on a ##FONT## theme. | ||
| 27 | |##url##|The address of the picture, on an ##IMAGE## theme. | ||
| 28 | |##render()##|A new, detached element drawing the icon: a ##span## carrying ##cssClass## on a ##FONT## theme, an ##img## pointing at ##url## on an ##IMAGE## one. Both also carry the ##icon## class, and the caller decides where the element goes. | ||
| 29 | |||
| 30 | == Icons the theme does not map == | ||
| 31 | |||
| 32 | A name the theme has no mapping for is simply absent from the object the loader hands back, so check for it before drawing it. When the request itself fails, the loader logs the reason on the console and hands back no icons at all, which leaves the page short of its icons rather than broken. |
