Icon Theme Application
 | Manage and display icons used all over the wiki |
| Type | XAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 6.2M1 |
Table of contents
Description
Features:
- Have a set of icon names that will render differently depending on the selected Icon Theme.
- Select your Icon Theme just like you select your Color Theme.
- Handle both icons made with images and icons made with fonts.
Icon List
The current list of available icons in Icon Themes is available at the Icons documentation page.
Some of the Icon Themes available:
| Theme | Status | Type | |
|---|---|---|---|
| Silk | (Bundled) | PNG | |
| Font Awesome | (Default) (Bundled | Font | |
| Glyphicons | (Contrib) | Font | |
| Material | (Contrib) | Font | |
| Font Awesome 5 | (Contrib) (Experimental) | Font, SVG | |
For Users
Selecting the Icon Set
Go to the "presentation" section of the administration of your wiki.
Select the icon set you want to use.
Displaying using Wiki Syntax
XWiki 14.10.6+, 15.2+ You should use the icon macro to display an icon of the current or a chosen icon theme. Using XWiki syntax starting from this version is not recommended.
XWiki 14.10.6+, 15.2+ You should use the icon macro to display an icon of the current or a chosen icon theme. Starting from this version, it's not recommended to use XWiki Syntax to display icons.
You can also display an icon using XWiki Syntax 2.1+ by using the format: image:icon:<icon name>
For example:
For Developers
Displaying in a Script
To display an icon, you just need to use the $services.icon script service. For example:
If you are inside the {{html}} macro, you should use the following which will generate HTML directly:
Since 6.3RC1, you can render an icon from any specific icon theme present on the wiki, referenced by its name:
$services.icon.render('add', 'Font Awesome')
## The last argument is used to disable the fallback to the default
## icon theme if the icon 'add' does not exist in the 'Font Awesome' theme.
$services.icon.render('add', 'Font Awesome', false)
Since 10.6RC1, you can manually display an icon using its metadata:
## Metadata of 'add' icon with current icon theme.
$services.icon.getMetaData('add')
## Metadata of 'add' icon using Silk theme.
$services.icon.getMetaData('add', 'Silk')
## Metadata of 'add' icon using Silk theme, without fallback.
$services.icon.getMetaData('add', 'Silk', false)
## Output example:
$services.icon.getMetaData('add', 'Silk') ## {iconSetName=Silk, cssClass=, iconSetType=IMAGE, url=/xwiki/resources/icons/silk/add.png}
$services.icon.getMetaData('add', 'Font Awesome') ## {iconSetName=Font Awesome, cssClass=fa fa-plus, iconSetType=FONT, url=}
$services.icon.getMetaData('add', 'Invalid', false) ## {}
## Usage:
#set ($metadata = $services.icon.getMetaData('add'))
#if ($metadata.iconSetType == 'IMAGE')
{{html}}<img src="$metadata.url" alt="Icon" />{{/html}}
#elseif ($metadata.iconSetType == 'FONT')
{{html}}<span class="$metadata.cssClass"></span>{{/html}}
#end
The previous methods automatically pull the necessary resources to display the icon but you can also do it manually in case you are retrieving the icon from a REST API:
## Pull the resources of the current icon theme
$services.icon.use()
## Pull the resources of the Silk icon theme
$services.icon.use('Silk')
Creating a new Icon Set
To create a new Icon Set, you should create a page inside the IconThemes space. Then, go to the objects edit mode, and add an IconThemesCode.IconThemeClass object into your page.
Then, edit your page with the wiki editor, and there you should fill the following content:
xwiki.iconset.type =
xwiki.iconset.render.wiki =
xwiki.iconset.render.html =
xwiki.iconset.icon.url =
xwiki.iconset.icon.cssClass =
xwiki.iconset.css =
xwiki.iconset.ssx =
xwiki.iconset.jsx =
## Icons
accept =
add =
...
| xwiki.iconset.type | type of your icon set. Could be "image" or "font". |
|---|---|
| xwiki.iconset.render.wiki | enter here the wiki syntax that will display the icon. This line will be parsed by Velocity, and the $icon variable will correspond to the icon to display. Example: xwiki.iconset.render.wiki = image:path:$xwiki.getSkinFile("icons/silk/${icon}.png") |
| xwiki.iconset.render.html | enter here the HTML code that will display the icon. This line will be parsed by Velocity, and the $icon variable will correspond to the icon to display. Example: xwiki.iconset.render.html = <img src="$xwiki.getSkinFile("icons/silk/${icon}.png")" alt="Icon" /> |
| xwiki.iconset.icon.url | enter here the Velocity code that will render the css classes of the icon. The $icon variable will correspond to the icon to display. Example: xwiki.iconset.icon.url = $xwiki.getSkinFile("icons/silk/${icon}.png") |
| xwiki.iconset.icon.cssClass | enter here the Velocity code that will render the URL of the icon. The $icon variable will correspond to the icon to display. Example: xwiki.iconset.icon.cssClass = fa fa-${icon} |
| xwiki.iconset.css | (optional) URL of a CSS file to enable to display the icon correctly. Will be parsed by Velocity. Example: xwiki.iconset.css = $services.webjars.url('font-awesome/4.1.0/css/font-awesome.min.css') |
| xwiki.iconset.ssx | (optional) Name of a page containing a Style Sheet Extension to enable to display the icon correctly. Example: xwiki.iconset.ssx = IconThemes.FontAwesome |
| xwiki.iconset.jsx | (optional) Name of a page containing a JavaScript Extension to enable to display the icon correctly. Example: xwiki.iconset.jsx = IconThemes.FontAwesome |
Then, you enter all the icons with the following format:
Example:
Script API
The icon module provides some script services:
$services.icon.render('home', 'Font Awesome') ## same, but also sets the icon theme to use
$services.icon.render('home', 'Font Awesome', true) ## same, but enable or not the fallback, ie if the default icon theme is used if the icon theme specified does not exist or does not contain the specified icon.
$services.icon.renderHTML('home') ## generate the HTML code to display the icon
$services.icon.renderHTML('home', 'Font Awesome') ## see previously
$services.icon.renderHTML('home', 'Font Awesome', true) ## see previously
$services.icon.iconSetNames ## returns the list of all icon theme available in the wiki
$services.icon.iconNames ## returns the list of all icons that contains the current icon theme
$services.icon.getIconNames('Font Awesome') ## returns the list of all icons that contains the specified icon theme
$services.icon.currentIconSetName ## returns the name of the current icon theme (which is setted in the preferences)
Icon Picker
XWiki 6.4M2+ This application proposes a picker to help user selecting an image inside the list of supported icons.
XWiki 16.8.0+ The picker now proposes a smart range of icons, ordered alphabetically, instead of the hard coded list that was proposed before.
There is 2 ways for enabling it in your scripts: via a wiki macro or directly in javascript.
Icon Picker Macro
Using this macro is the easiest way to enable the icon picker.
Usage
Where:
| id (optional) | DOM id of the input field where the picker will apply |
|---|---|
| class (optional) | CSS class of inputs where the picker will apply |
| prefix (optional) | Prefix to add before the name of the icon in the input field (default: "image:icon:") |
Example
<p>Field 1: <input type="text" id="myPicker" /></p>
<p>Field 2: <input type="text" class="fieldWithPicker" /></p>
{{/html}}
{{iconPicker id="myPicker" class="fieldWithPicker" prefix="icon:" /}}
Icon Picker Widget
The Icon Picker is a jQuery plugin that you can use through requirejs. It is far more easier to use the User Picker Macro, but in case you need it, we describe here an example of use.
Example
With Velocity and HTML:
#set($discard = $xwiki.ssx.use('IconThemesCode.IconPicker'))
## JavaScript code:
<script language="javascript">
// Configure requirejs to load the picker code
require.config({
paths: {
'xwiki-icon-picker': '$xwiki.getURL($services.model.createDocumentReference('', 'IconThemesCode', 'IconPicker'), 'jsx', "minify=$!{escapetool.url($request.minify)}")'
}
});
// Require jquery and the icon picker
require(['jquery', 'xwiki-icon-picker'], function($) {
// Here you can bind the picker to some elements.
// Examples:
$('#someElement').xwikiIconPicker(); // apply the picker to the field #someElement
$('#someElement').xwikiIconPicker({prefix: 'image:icon:'}); // change the prefix inserted before the icon name
});
</script>
## The icons themes may need some SSX, so we ask for a rendering of an icon of each icon theme, to be able to display
## all icon themes in the picker
## ToDo: since it is a bit hacky, a better system would be to dynamically load the needed SSX on demand
#foreach($iconSetName in $services.icon.iconSetNames)
#set($discard = $services.icon.render('wiki', $iconSetName))
#end
REST API
XWiki 13.4+
The icons of a theme can be accessed using the REST API. Two endpoints are available, one to access the information about the icons of the default theme, and the other to access the information about the icons of a given theme.
/wikis/{wikiName}/iconThemes/icons[?[name=n]*]
- HTTP Method: GET
- Media Types: application/xml or application/json
- Description: Provides the metadata of the icons of the current icon theme in a given {wikiName} wiki
- Query Parameters:
- name: (multiple) the name of the requested icons
- Status Code:
- 200: if the request was successful
- Response:
- An object with two attributes: icon is a list of the requested icons metadata, and missingIcons an array of names of requested icons that couldn't be found in the current theme.
/wikis/{wikiName}/iconThemes/{iconTheme}/icons[?[name=n]*]
- HTTP Method: GET
- Media Types: application/xml or application/json
- Description: Provides the metadata of the icons of the {iconTheme} icon theme in a given {wikiName} wiki
- Query Parameters:
- name: (multiple) the name of the requested icons
- Status Code:
- 200: if the request was successful
- Response:
- An object with two attributes: icon is a list of the requested icons metadata, and missingIcons an array of names of requested icons that couldn't be found in the requested theme.
Examples:
$ curl -H 'Accept: application/json' http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/icons?name=add&name=home&name=unknown
# {"icons":[{"name":"add","iconSetType":"FONT","iconSetName":"Font Awesome","cssClass":"fa fa-plus","url":null},{"name":"home","iconSetType":"FONT","iconSetName":"Font Awesome","cssClass":"fa fa-home","url":null}],"missingIcons":["unknown"]}
# Same request as above but with the Silk theme
$ curl -H 'Accept: application/json' http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/Silk/icons?name=add&name=home&name=unknown
# {"icons":[{"name":"add","iconSetType":"IMAGE","iconSetName":"Silk","cssClass":null,"url":"http://localhost:8080/xwiki/resources/icons/silk/add.png?cache-version=1621078386000"},{"name":"home","iconSetType":"IMAGE","iconSetName":"Silk","cssClass":null,"url":"http://localhost:8080/xwiki/resources/icons/silk/house.png?cache-version=1621078386000"}],"missingIcons":["unknown"]}
# Same two requests as above but with the default xml media type
$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/icons?name=add&name=home&name=unknown
?prefix=administration.section.users&locale=fr&key=.deleteUser.newAuthor.error&key=.enableUser.inProgress
# <icons xmlns="http://www.xwiki.org/icon"><icon><name>add</name><iconSetType>FONT</iconSetType><iconSetName>Font Awesome</iconSetName><cssClass>fa fa-plus</cssClass></icon><icon><name>home</name><iconSetType>FONT</iconSetType><iconSetName>Font Awesome</iconSetName><cssClass>fa fa-home</cssClass></icon><missingIcons>unknown</missingIcons></icons>
$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/Silk/icons?name=add&name=home&name=unknown
# <icons xmlns="http://www.xwiki.org/icon"><icon><name>add</name><iconSetType>IMAGE</iconSetType><iconSetName>Silk</iconSetName><url>http://localhost:8080/xwiki/resources/icons/silk/add.png?cache-version=1621078386000</url></icon><icon><name>home</name><iconSetType>IMAGE</iconSetType><iconSetName>Silk</iconSetName><url>http://localhost:8080/xwiki/resources/icons/silk/house.png?cache-version=1621078386000</url></icon><missingIcons>unknown</missingIcons></icons>
Silk Icon Theme
The Silk Icon Theme uses the Silk icons set to be mapped as an Icon Theme. This is an icon library launched in 2005 that contains over 1000 png images at 16px resolution.
The Silk Icon Theme is the default theme and the one used for fallbacks.
Preview
Example
Here is a table summing up the mapping between the XWiki icon set and the Silk iconTheme:
Version Compatibility
| XWiki version | Silk version used |
|---|---|
| 6.2M1, 9.10 | 1.3 |
Links
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-icon-ui 16.10.1):
- org.xwiki.platform:xwiki-platform-icon-script 16.10.1
- org.xwiki.platform:xwiki-platform-icon-default 16.10.1
- org.webjars:requirejs 2.3.7
- org.webjars:jquery 3.7.1
