Icon JavaScript API
Reference
XWiki 17.10.5+, 18.2.0+ Browser code reaches the icons of the wiki's Icon Theme through the xwiki-icon RequireJS loader plugin, which fetches them over the Icon REST API and hands back one object per icon, each able to draw itself.
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:
// The names to load, in a module of their own.
define('my-module-icons', {
icons: ['home', 'cross']
});
define('my-module', ['xwiki-icon!my-module-icons'], function(icons) {
// Each icon draws itself into a new element.
document.querySelector('.my-icon-wrapper').append(icons.home.render());
// The metadata the REST API reports sits on the same object.
const isFontIconTheme = icons.cross.iconSetType === 'FONT';
});| Property | Description |
|---|---|
| name | The name of the icon in the XWiki Icon Set. |
| iconSetName | The name of the Icon Theme the icon was taken from. |
| iconSetType | FONT when the theme draws the icon with a font glyph, IMAGE when it draws a picture. |
| cssClass | The CSS classes that select the glyph, on a FONT theme. |
| url | The address of the picture, on an IMAGE theme. |
| 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. |
Icons the theme does not map
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.
FAQ
Can the icons be loaded from a theme other than the wiki's?
No. The loader always asks the endpoint of the theme the wiki uses; call the Icon REST API yourself to reach a named theme.
Are the icons of the current wiki or of the main wiki?
Of the current one: the loader builds its address from the wiki the page is served from.
