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

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

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 there as a draft.

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

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

You can 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. In the future, the icon will be displayed using the selected Icon Set.

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.

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

Since XWiki 6.4M2 This application proposes a picker to help user selecting an image inside the list of supported icons.

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

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 9.6):

  • org.xwiki.platform:xwiki-platform-icon-script 9.6
  • org.xwiki.platform:xwiki-platform-icon-default 9.6
  • org.webjars:requirejs 2.2.0
  • org.webjars:jquery 2.2.2
Tags:
Created by Guillaume Delhumeau on 2014/08/04 15:55
    

Get Connected