Template Module

Last modified by Thomas Mortagne on 2023/09/18 13:18

cogProvide APIs to manipulate templates
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

Since 7.0M1

Description

This module provide APIs and tool to execute XWiki templates. What we call templates are generally files or wiki pages responsible for the display of the general UI (everything around the actual document content execution).

Use a template

Template manager

The main entry point of the module is org.xwiki.template.TemplateManager component.

A template is represented by org.xwiki.template.Template interface which provide access to the template content (as a org.xwiki.template.TemplateContent) as well as its path and id.

  • find the template with id mytemplate.vm:
    @Inject
    TemplateManager templateManager;

    ...

    Template template = templateManager.getTemplate("mytemplate.vm");
  • find and execute the template with id mytemplate.vm:
    @Inject
    TemplateManager templateManager;

    ...

    String html = templateManager.render("mytemplate.vm");
  • find and execute the template with id mytemplate.vm and get a XDOM:
    @Inject
    TemplateManager templateManager;

    ...

    XDOM result = templateManager.execute("mytemplate.vm");
  • XWiki 14.0+ 

    find and execute the template with id mytemplate.vm as an inline content:

    @Inject
    TemplateManager templateManager;

    ...

    Block result = templateManager.execute("mytemplate.vm", true);
  • find and parse the template with id mytemplate.vm without executing it:
    @Inject
    TemplateManager templateManager;

    ...

    XDOM xdom = templateManager.getXDOM("mytemplate.vm");

Template macro

A wiki macro is provided to make easier to include template in wiki pages. See Template Macro for more details.

Execute and include the result of template mytemplate.vm template:

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

Scripting

A template Script Service to make easier execute a template from a script.

Execute and render template:

{{velocity}}
{{html}}
$services.template.render('mytemplate.vm')
{{/html}}
{{/velocity}}

Write a template

Location

Template manager is looking for template in the following order:

  1. A resource name in the current skin (or one of its parent skin)
  2. A relative file path in "templates/" folder of the WAR
  3. XWiki 8.3+ A relative file path in the classloader (usually inside a JAR file) in "templates/" folder

Content

By default template are Velocity scripts usually producing html content.

But the content also support a set of properties that can modify the behavior and how it's parsed among other things. These properties are located at the beginning of the content and use the syntax ##!property=value as in:

##!source.syntax=xwiki/2.1
{{info}}
Some info message
{{/info}}

Here is the list of supported properties:

Property nameValuesDefaultDescription
source.syntaxA Rendering Input SyntaxThe identifier of the parser to use to interpret the content of the template
raw.syntaxA Rendering Input Syntaxxhtml/1.0When source.syntax is not set, it's the syntax that will be put in the RawBlock produced with the result of the Velocity execution
authorThe reference of a XWiki userThe user to use as author when executing the template. Only taken into account for filesystem and classloader templates. Wiki templates are always executed with the right of their author so this property is not taken into account.
privilegedtrue/falsetrue
(XWiki <9.0 false)
Force the filesystem or classloader templates to have Programming Rights. In practice it means its author will be xwiki:XWiki.superadmin. Wiki templates are always executed with the right of their author so this property is not taken into account.
cacheAllowedtrue/falsefalseXWiki 11.8+ Indicate if caching the result is allowed
asyncAllowedtrue/falsefalseXWiki 11.8+ Indicate if executing the template asynchronously is allowed
contextEntriescontext entriesXWiki 11.8+ The list of entries from the context the template needs
uniqueREQUESTXWiki 11.8+ Make sure the template is executed only once in the same request
require.actiona Java regexXWiki 14.10.1+, 15.0+ The regex must match the context action before the template is executed. For example require.action=view|edit

Template requirements

XWiki 14.10.1+, 15.0+ 

It's possible to express through the template properties requirement that must be met before the template is executed.

It's always expressed with the following format: requirement.<requirement key>=<requirement value> where the <requirement key> is the hint of a component with role type org.xwiki.template.TemplateRequirement. The value format depends on the requirement, see the table above for standard requirements.

Wiki templates

See How to override a template.

Filesystem templates

That's the templates located on the filesystem usually in two locations:

  • /templates/ folder in the WAR
  • in filesystem skins (usually /skins/<skin>/)

Since 9.0 they have programming right by default. Before that they were executed with the right of the current document content author.

Classloader templates

Those are the templates found in the classloader in templates package (usually in JARS or in /WEB-INF/classes/templates in the WAR).

Templates caching

XWiki 15.8+ 

Wiki and Filesystem are cached and invalidated based on latest modification date. It's also possible to force skipping the templates cache by sending the HTTP header Cache-Control with value "no-cache". Fortunately this is something the browser does when you force refresh (SHIFT+F5 or CTRL+SHIFT+R usually) so using forcing refresh in your browser will not only affect the browser cache but also the server side template cache.

In addition, Velocity templates are compiled and the result of this compilation is cached too to greatly speed up execution.

Tags:
    

Get Connected