Icon Transformation

The Icon Rendering Transformation transforms a series of characters into icons. The transformation is enabled by default but in case you need to disable it:

  • edit the "WEB-INF/xwiki.properties" file
  • un-comment the line #-#rendering.transformations = macro, icon and make sure it only contains the value "macro", i.e. rendering.transformations = macro
  • restart XWiki

Default Mappings

 Character  Result
:)emoticon_smile
:(emoticon_unhappy
:Pemoticon_tongue
:Demoticon_grin
;)emoticon_wink
(y)thumb_up
(n)thumb_down
(i)information
(/)accept
(x)cancel
(!)error
(+)add
(-)delete
(?)help
(on)lightbulb
(off)lightbulb_off
(*)star

The mappings are available in the "WEB_INF/xwiki.properties" file under the section "Icon Transformation Configuration":

#-# rendering.transformation.icon.mappings = :) = emoticon_smile
#-# rendering.transformation.icon.mappings = :( = emoticon_unhappy
#-# rendering.transformation.icon.mappings = :P = emoticon_tongue
#-# rendering.transformation.icon.mappings = :D = emoticon_grin
#-# rendering.transformation.icon.mappings = ;) = emoticon_wink
#-# rendering.transformation.icon.mappings = (y) = thumb_up
#-# rendering.transformation.icon.mappings = (n) = thumb_down
#-# rendering.transformation.icon.mappings = (i) = information
#-# rendering.transformation.icon.mappings = (/) = accept
#-# rendering.transformation.icon.mappings = (x) = cancel
#-# rendering.transformation.icon.mappings = (!) = error
#-# rendering.transformation.icon.mappings = (+) = add
#-# rendering.transformation.icon.mappings = (-) = delete
#-# rendering.transformation.icon.mappings = (?) = help
#-# rendering.transformation.icon.mappings = (on) = lightbulb
#-# rendering.transformation.icon.mappings = (off) = lightbulb_off
#-# rendering.transformation.icon.mappings = (*) = star

Customization

You can change the icons used to represent the default mappings by modifying the corresponding rendering.transformation.icon.mappings parameter. The parameter value can be any icon name available in the Silk Icon set reference. 

For instance, to use emoticon_happy.png instead of emoticon_grin.png when typing :D, edit the file "WEB-INF/xwiki.properties", replace the line

#-# rendering.transformation.icon.mappings = :D = emoticon_grin

with

rendering.transformation.icon.mappings = :D = emoticon_happy

and restart the server.

To add a new mapping, for instance to display the icon cake.png when typing (^), edit the file "WEB-INF/xwiki.properties", add the line rendering.transformation.icon.mappings = (^) = cake and restart the server.

Examples of Usage

1. 

// Initialize Rendering components and allow getting instances
final EmbeddableComponentManager cm = new EmbeddableComponentManager();
cm.initialize(this.getClass().getClassLoader());

XDOM xdom = new XDOM(Arrays.<Block>asList(new ParagraphBlock(Arrays.asList((Block) new SpecialSymbolBlock(':'),
   new SpecialSymbolBlock(')')))));

Transformation transformation = cm.lookup(Transformation.class, "icon");
TransformationContext txContext = new TransformationContext();
transformation.transform(xdom, txContext);

WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = cm.lookup(BlockRenderer.class, Syntax.XWIKI_2_0.toIdString());
renderer.render(xdom, printer);

String expected = "image:emoticon_smile";

Assert.assertEquals(expected, printer.toString());

2. Configure new emoticons or override the existing ones using the XWikiIconTransformationConfiguration component:

// Initialize Rendering components and allow getting instances
final EmbeddableComponentManager cm = new EmbeddableComponentManager();
cm.initialize(this.getClass().getClassLoader());

XDOM xdom = new XDOM(Arrays.<Block>asList(new ParagraphBlock(Arrays.asList((Block) new SpecialSymbolBlock(':'),
   new SpecialSymbolBlock(':')))));

// Test adding a new Icon Mapping.
cm.lookup(IconTransformationConfiguration.class).addMapping("::", "something");

Transformation transformation = cm.lookup(Transformation.class, "icon");
TransformationContext txContext = new TransformationContext();
transformation.transform(xdom, txContext);

WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = cm.lookup(BlockRenderer.class, Syntax.XWIKI_2_0.toIdString());
renderer.render(xdom, printer);

String expected = "image:box";

Assert.assertEquals(expected, printer.toString());

  

Related Pages

Search this space