Wiki source code of Icons
Last modified by Eleni Cojocariu on 2026/08/26 12:25
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The [[Icon Theme Application>>doc:extensions:Extension.Icon Theme Application]] lets code ask for [[a name of the XWiki Icon Set>>doc:documentation.xs.admin.icons.icon-set.WebHome]], so an extension never hard-codes an image path and follows the [[Icon Theme>>doc:documentation.xs.admin.icons.icon-themes.WebHome]] the wiki has selected on its own. | ||
| 2 | |||
| 3 | Each way of asking has its own page: | ||
| 4 | |||
| 5 | * [[Display an Icon in a Script>>doc:documentation.xs.dev.icons.display-icon-script.WebHome]] renders an icon from Velocity, and [[Icon Script Service>>doc:documentation.xs.dev.icons.script-service.WebHome]] lists everything ##$services.icon## offers. | ||
| 6 | * [[Icon JavaScript API>>doc:documentation.xs.dev.icons.javascript-api.WebHome]] loads icons into browser code, over the [[Icon REST API>>doc:documentation.xs.dev.icons.rest-api.WebHome]] that also answers requests of its own. | ||
| 7 | * [[Add an Icon Picker>>doc:documentation.xs.dev.icons.add-icon-picker.WebHome]] lets the user of a form choose an icon, and [[Icon Picker>>doc:documentation.xs.dev.icons.icon-picker.WebHome]] documents the macro and the jQuery plugin that place it. | ||
| 8 | * [[Create an Icon Theme>>doc:documentation.xs.dev.icons.create-icon-theme.WebHome]] adds a mapping of your own to a wiki, and [[Icon Theme Properties>>doc:documentation.xs.dev.icons.create-icon-theme.icon-theme-properties.WebHome]] documents every setting its page carries. | ||
| 9 | |||
| 10 | What a request for an icon goes through: | ||
| 11 | |||
| 12 | {{plantuml}} | ||
| 13 | @startuml | ||
| 14 | !theme bluegray | ||
| 15 | skinparam componentStyle rectangle | ||
| 16 | |||
| 17 | component "**displayIcon**\nrendering macro" as MACRO | ||
| 18 | component "**$services.icon**\nIconManagerScriptService" as SS | ||
| 19 | component "**iconThemes**\nREST resource" as REST | ||
| 20 | component "**xwiki-icon**\nRequireJS loader" as JS | ||
| 21 | component "**IconManager**\nrender, renderHTML, getMetaData" as IM | ||
| 22 | component "**IconSetManager**\nresolves the theme to use" as ISM | ||
| 23 | component "**IconRenderer**\nevaluates the theme's template" as IR | ||
| 24 | database "Icon Theme page\nIconThemeClass object\n+ properties file" as THEME | ||
| 25 | database "default.iconset\nbuilt into the distribution" as DEFAULT | ||
| 26 | |||
| 27 | MACRO --> IM | ||
| 28 | SS --> IM | ||
| 29 | JS --> REST | ||
| 30 | REST --> IM | ||
| 31 | IM --> ISM : which theme? | ||
| 32 | ISM --> THEME : XWikiPreferences.iconTheme | ||
| 33 | ISM ..> DEFAULT : fallback | ||
| 34 | IM --> IR : icon name + template | ||
| 35 | IR --> THEME : css, ssx and jsx pulled in | ||
| 36 | @enduml | ||
| 37 | {{/plantuml}} | ||
| 38 | |||
| 39 | == How theme values are rendered == | ||
| 40 | |||
| 41 | Each value of [[the theme's properties file>>doc:documentation.xs.dev.icons.create-icon-theme.icon-theme-properties.WebHome]] 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: | ||
| 42 | |||
| 43 | * plain text containing ##$icon## or ##${icon}## once, and no other ##$## or ##### | ||
| 44 | * exactly ##$services.webjars.url('...')##, with one to three single-quoted arguments | ||
| 45 | * ##$xwiki.getSkinFile("...${icon}...")##, surrounded by text carrying no other ##$## or ##### | ||
| 46 | |||
| 47 | A value holding no Velocity at all is used as it stands; any other value is evaluated in full. [[Open an issue>>doc:dev:Community.Contributing||anchor="HReportanissue"]] if a shape worth recognising is missing. |
