Steps

This page adds a template to an extension, so that the user interface can include it. Templates explains where XWiki looks for the file and with which rights it runs it.

1. Create the file under the folder that matches the kind of template you need:

   src/main/resources/templates/mytemplate.vm        a classloader template, packaged in the JAR
   src/main/webapp/templates/mytemplate.vm           a filesystem template, packaged in the WAR

   The file name is the template name, so a template added by an extension needs a name specific enough not to collide with a template of the platform.

2. Write the content as a Velocity script producing HTML:

   #set ($message = $services.localization.render('myextension.greeting'))
   <div class="box infomessage">$escapetool.xml($message)</div>

3. Declare the properties the template needs on the leading lines, before any content:

   ##!source.syntax=xwiki/2.1
   {{info}}
   $escapetool.xml($message)
   {{/info}}

   Those lines are removed before the content is executed, so Velocity never sees them. Here source.syntax makes the result be parsed as XWiki syntax instead of being injected as HTML, which is what lets the template use a macro. Template Properties lists the keys.

4. Include the template from a wiki page to run it:

   {{template name="mytemplate.vm"/}}

5. Check the result: the macro is replaced by what the template produced.

   <div class="box infomessage">Hello</div>

FAQ

Does a template have to be a .vm file?

No, but the convention is to name it after the Velocity syntax it contains, and every template shipped with XWiki does.

How does a template get its translated strings?

Through the localization script service, as in the example above: the keys come from the resource bundle of the extension shipping the template.

Related

• Skin
• Customize Skin