Icon Theme Application

Last modified by Admin on 2024/10/01 02:32

wrenchManage and display icons used all over the wiki
TypeXAR
Category
Developed by

XWiki Development Team

Rating
1 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

Since 6.2M1

Installable with the Extension Manager

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.

To ensure the retro-compatibility, we will try to have a an equivalent to each silk icons in every icon theme.

Some of the Icon Themes available:

 Theme StatusType
 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.

administration.png

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:

image:icon:add

At the moment, this feature only works for the Silk Icon set. The names of the icons used for this syntax are the actual names of the Silk icons (see the Icon sets documentation ), not the XWiki icon name as the other tools use.

For Developers

Displaying in a Script

To display an icon, you just need to use the $services.icon script service. For example:

$services.icon.render('add')

If you are inside the {{html}} macro, you should use the following which will generate HTML directly:

$services.icon.renderHTML('add')

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', 'Silk')
$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)

The icon could be either an image or a font icon. XWiki will automatically generates the good output to display correctly the image.

Since 10.6RC1, you can manually display an icon using its metadata:

## Since 10.6RC1:
## 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:

## Since 10.6RC1:
## 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. 

object.png

Then, edit your page with the wiki editor, and there you should fill the following content:

## General settings
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.typetype of your icon set. Could be "image" or "font".
xwiki.iconset.render.wikienter 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.htmlenter 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.urlenter 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.cssClassenter 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 Since 6.2-M2

Then, you enter all the icons with the following format:

name = value

Example:

add = fa-plus-circle

Script API

The icon module provides some script services:

$services.icon.render('home') ## generate the wiki syntax to display the icon
$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.

icon-picker.png

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

{{iconPicker id="" class="" prefix="" /}}

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

{{html}}
 <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:

## Enable the CSS of the picker:
#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:

# Request the metata of 3 icons (2 known and 1 unknown) in the current theme
$ 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
silkSet.png

Example
silkExample.png

Version Compatibility

XWiki versionSilk version used
6.2M1, 9.101.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:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. 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.8.0):

  • org.xwiki.platform:xwiki-platform-icon-script 16.8.0
  • org.xwiki.platform:xwiki-platform-icon-default 16.8.0
  • org.webjars:requirejs 2.3.7
  • org.webjars:jquery 3.7.1

Get Connected