Template Module

Version 8.1 by Thomas Mortagne on 2016/09/26 16:30

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 Enterprise

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");
  • 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
  2. A relative file path in "templates/" folder of the WAR
  3. [since 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.

It's possible to control various behavior of those template with the following properties:

Property nameValuesDescription
source.syntaxA Rendering Input SyntaxThe identifier of the parser to use to interpret the content of the template
raw.syntaxA Rendering Input SyntaxWhen 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 use to use as author or the template content when executing it, only taken into account for file system templates, wiki based template will be given their actual author.
privilegedtrue/falseForce the filesystem template to have Programming Rights. In practice it means its author will be xwiki:XWiki.superadmin

Wiki templates

See How to override a template.

Filesystem templates

TODO

Classloader templates

TODO

Tags:
    

Get Connected