Icons
Explanation
The Icon Theme Application lets code ask for a name of the XWiki Icon Set, so an extension never hard-codes an image path and follows the Icon Theme the wiki has selected on its own.
Each way of asking has its own page:
- Display an Icon in a Script renders an icon from Velocity, and Icon Script Service lists everything $services.icon offers.
- Icon JavaScript API loads icons into browser code, over the Icon REST API that also answers requests of its own.
- Add an Icon Picker lets the user of a form choose an icon, and Icon Picker documents the macro and the jQuery plugin that place it.
- Create an Icon Theme adds a mapping of your own to a wiki, and Icon Theme Properties documents every setting its page carries.
What a request for an icon goes through:
How theme values are rendered
Each value of the theme's properties file is a template, turned into a renderer the first time it is met and kept, so the same value is not parsed again for every icon. Three shapes are recognised and substituted directly instead of going through Velocity, which is faster and shows up most in the icon picker, where a whole theme is drawn at once:
- 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 #
A value holding no Velocity at all is used as it stands; any other value is evaluated in full. Open an issue if a shape worth recognising is missing.
FAQ
Which name does a script pass to select a theme?
The name property of the theme page's IconThemesCode.IconThemeClass object, not the page name: the bundled Font Awesome theme lives on IconThemes.FontAwesome and is named Font Awesome.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
