template
Audit
- Macro ID
- template
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content and its output is the rendering of the Velocity template whose name is given, so it is classified as a generator.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- include uiextension
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Template" names the Velocity templates the macro renders, the term developers use for them, in a Development macro. It does not lead to page templates, the same way translation does not lead to page translations. |
| D2 summary | KO | "Insert a template." repeats the name and does not say what the macro adds to the page: the output of the Velocity template of the given name, found in the skin or in the files of XWiki, rendered where the macro is. The French and German descriptions repeat the name the same way, "Insérer un template." and "Eine Vorlage einfügen.". To reproduce: open the Insert Macro dialog and select Template. |
| D3 category | OK | Development, the only category of the macro, where a developer who wants to run a template looks for it, like uiextension, the other Development generator of the compared macros. Include is in Content, which fits its user use, while the names of the templates are file names that only developers know. |
| D4 quick-action | OK | Quick Actions finds the macro first for "template", "Template" and the German name "Vorlage". The French name is "Template", the same as English, which is OK since the German name differs and finds it. The synonyms "insert template", "velocity template", "skin template", "render template" and "template file" give no result. The macro is named after the technology of XWiki it runs, so the few synonyms are OK. |
| L1 consistency | OK | compared with include and uiextension. Like them, the macro has no content and one target, the name of the template. Unlike them, the Quick Action inserts it right away, with no dialog, because the name is not declared mandatory; that difference comes from C2 and is counted there. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Template%20Macro, and not in the new documentation: the page Templates, https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/templates/, only quotes the call, with no parameter table. The legacy page says that name is mandatory, which the macro does not declare, and describes output as "Indicate of the result of the execution should be returned by the macro", with a typo and no hint of when to turn it off. |
| L3 doc-example | KO | no documentation example shows the most common use. The only example, {{template name="mytemplate.vm"/}} , uses a placeholder name: it renders without error but renders nothing, since no template of that name exists. The most common call of XWiki Standard loads a macro library, {{template name="extension.vm" output="false"/}} , which no page documents. The audit uses {{template name="pdftoc.vm"/}} , a template of XWiki Standard whose whole output is the heading "Table of Contents": no documented example and no call of XWiki Standard renders something visible. |
| I1 pattern | OK | compared with children, the reference generator, with include and uiextension. From Quick Actions, the "Template" entry inserts {{template/}} right away, like children; include and uiextension open the Edit Macro dialog since their target is mandatory, a difference counted under C2. From the Insert Macro dialog, the Edit Macro dialog opens with the Name and Output fields. |
| I2 zero-config | KO | KO: inserting from Quick Actions, or submitting the Edit Macro dialog with the default values, gives {{template/}} , which renders nothing in view mode, with no message, and shows only the generic "macro:template" in the editor, also after saving and reopening the page. The user cannot tell that a name is missing. Include and uiextension refuse the empty value in the dialog and give "Property mandatory" in view mode. To reproduce: Quick Actions, Template, save and view. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the Name field comes first, visible without scrolling, and has the focus; no field is mandatory, which is counted under C2. |
| E1 wysiwyg | OK | the example {{template name="pdftoc.vm"/}} shows the heading "Table of Contents" in the editor as in view mode. With an unknown name, a missing name or output="false", which is the usual call, the editor only shows the generic "macro:template" placeholder, like include for an empty page, which does not fail the measure on the example. |
| E2 errors | KO | invalid values are accepted silently, and the one message is a raw Java message. {{template name="doesnotexist.vm"/}} , {{template name="123"/}} , {{template name="PDFTOC.VM"/}} and {{template name="pdf toc.vm"/}} render nothing with no message, since the macro returns nothing when no template answers the name, see TemplateMacro.execute. {{template/}} and {{template name=" "/}} do the same. {{template name=""/}} gives "Failed to execute the [template] macro. Cause: [Cannot invoke "org.xwiki.template.TemplateContent.getUnique()" because the return value of "org.xwiki.template.Template.getContent()" is null]", an internal null error that does not name the parameter. {{template name="pdftoc.vm" output="maybe"/}} , output="abc" and output="" are read as false and render nothing. |
| E3 nesting | OK | the example renders with no error in a list item, a table cell and a box. The macro has no content. |
| E4 inline-support | OK | the macro declares inline support. Before {{template name="pdftoc.vm"/}} after. puts the heading of the example inside the sentence, which breaks the line; a template whose output is a single line renders inline. It depends on the chosen template, which is OK as for include. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| name | KO | KO | OK | KO | OK | OK | N/A | OK | OK | N/A | C1, KO: the label "Name" and the description "The name of the template" repeat each other and do not say what a template name is: the file name of a Velocity template, like pdftoc.vm, looked up in the skin, in the templates folder of the WAR and in the JARs, with its extension. The description gives no possible value for a free field. Open the Edit Macro dialog of {{template name="pdftoc.vm"/}} . C2, KO: not mandatory in the descriptor, but nothing works without it: no name renders nothing, with no message, and the legacy documentation says it is mandatory. No default would work for the example, so it should be mandatory; the dialog then refuses an empty value, and Quick Actions opens the dialog as for include and uiextension, which also fixes I2. Reproduce: Quick Actions, Template inserts {{template/}} . C3: no default makes sense, the name picks one template. It comes first in the dialog, so it may open empty. C4, KO: a plain text field, so the developer has to know the exact file name, extension and case included: a typo renders nothing, see E2. A picker of the templates that XWiki can find, skin, filesystem and classloader ones, could be used, like the picker asked for uiextension. C5: one group, Optional parameters, with two fields. C6: the name, the only parameter set by the example, comes first. C8: set by the example, so not advanced. C9: used by every example. C13: N/A, a template name is any text, checked when the macro renders; the missing picker is counted under C4. |
| output | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1: "Specifies whether or not the result of the execution should be returned by the macro." says the effect, with developer terms that are OK for a developer macro. It does not say when to turn it off, to run a template that only defines Velocity macros, which is how XWiki itself uses the parameter. C2: optional, with a default that works: the result is displayed. C3: a checkbox checked by default, the value used by the example. The most frequent call of XWiki Standard sets it to false, to load a macro library, which only the audit of the use shows. C4: a checkbox for a boolean. C5: one group, Optional parameters, with two fields. C6: second, after the name, which the example sets; output is set only to hide the result. C8: used by most of the calls found in XWiki Standard, to load macro libraries, so it stays visible. C9: realistic use, hiding the output of a template that only defines macros. C13: N/A, a boolean. |
Other notes
Other notes: bug outside the criteria, to file in JIRA after the review: {{template name=""/}} throws a null error in TemplateManager instead of being handled like a missing name, which renders nothing. The audit example pdftoc.vm is the template of the PDF export, chosen only because it is harmless and visible.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25477 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| I2 | I2 zero-config | XWIKI-25478 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25501 (partial) | |
| C1:name | C1 clarity, name | XWIKI-25477 | |
| C2:name | C2 mandatory, name | XWIKI-25478 | |
| C4:name | C4 input-assistance, name | XWIKI-23045 (partial) | XWIKI-25501 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25477 | New | C1:name D2 | |
| XWIKI-25478 | New | C2:name I2 | |
| XWIKI-23045 | Existing | C4:name | |
| XWIKI-25501 | New | C4:name | E2 |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
