Wiki source code of Templates
Last modified by superadmin on 2026/10/14 18:26
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
2.1 | 1 | The [[Template Module>>doc:extensions:Extension.Template Module]] executes the files and wiki pages that render the XWiki user interface around the content of the page being viewed. Such a file is called a template, it is written in Velocity, and it is named by its file name, as in ##mytemplate.vm##. |
| 2 | |||
| 3 | == Where XWiki looks for a template == | ||
| 4 | |||
| 5 | ##org.xwiki.template.TemplateManager## resolves a template name against three sources and stops at the first one that answers: | ||
| 6 | |||
| 7 | {{plantuml}} | ||
| 8 | @startuml | ||
| 9 | !theme bluegray | ||
| 10 | skinparam nodesep 25 | ||
| 11 | skinparam ranksep 30 | ||
| 12 | |||
| 13 | start | ||
| 14 | :getTemplate("mytemplate.vm"); | ||
| 15 | if (a resource of the current skin\nor one of its parent skins?) then (found) | ||
| 16 | :skin template; | ||
| 17 | stop | ||
| 18 | endif | ||
| 19 | if (a file under templates/ in the WAR\nor in a filesystem skin?) then (found) | ||
| 20 | :filesystem template; | ||
| 21 | stop | ||
| 22 | endif | ||
| 23 | if (a resource under templates/\nin the classloader?) then (found) | ||
| 24 | :classloader template; | ||
| 25 | stop | ||
| 26 | endif | ||
| 27 | :no template; | ||
| 28 | stop | ||
| 29 | @enduml | ||
| 30 | {{/plantuml}} | ||
| 31 | |||
| 32 | * **Skin templates** are resources of the current skin or of one of its parent skins. A skin can be a wiki page, which is how an administrator replaces a template without touching the filesystem, as described in [[Customize Skin>>doc:documentation.xs.admin.skins.customize.WebHome]]. | ||
| 33 | * **Filesystem templates** are files in the ##templates/## folder of the WAR, or in a filesystem skin under ##skins/##. | ||
| 34 | * **Classloader templates** are resources in the ##templates## package of a JAR, or in ##WEB-INF/classes/templates## in the WAR. | ||
| 35 | |||
| 36 | == Rights and caching == | ||
| 37 | |||
| 38 | Filesystem and classloader templates have programming right by default: they are executed as ##xwiki:XWiki.superadmin##, which the ##privileged## property turns off. A wiki template is always executed with the right of its own author, so neither ##privileged## nor ##author## has any effect on it. | ||
| 39 | |||
| 40 | Wiki and filesystem templates are cached, and an entry is dropped when the template is modified. Velocity also compiles each template once and caches the compiled form. A request carrying the following header skips the template cache, which is what a browser sends when the reader forces a refresh: | ||
| 41 | |||
| 42 | {{code language="none"}} | ||
| 43 | Cache-Control: no-cache | ||
| 44 | {{/code}} | ||
| 45 | |||
| 46 | == Running a template == | ||
| 47 | |||
| 48 | [[Execute a Template>>doc:documentation.xs.dev.templates.execute-template.WebHome]] calls ##TemplateManager## from a component. A wiki page runs the same template with the ##template## macro, and a script with the ##template## script service: | ||
| 49 | |||
| 50 | {{code language="none"}} | ||
| 51 | {{template name="mytemplate.vm"/}} | ||
| 52 | |||
| 53 | $services.template.render('mytemplate.vm') | ||
| 54 | {{/code}} | ||
| 55 | |||
| 56 | [[Write a Template>>doc:documentation.xs.dev.templates.write-template.WebHome]] adds one to a JAR or to the WAR, and [[Template Properties>>doc:documentation.xs.dev.templates.template-properties.WebHome]] documents the header that controls how it is parsed and executed. |
