Wiki source code of Override a Template
Last modified by superadmin on 2026/08/30 19:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | A template you supply replaces the shipped one for every Block of its kind, which is [[how a template is found>>doc:documentation.extensions.dev.latex.template-mechanism.WebHome]]. Copying the whole default and editing the copy works until the extension ships a new version of that template, at which point your copy quietly keeps the old behaviour and nothing tells you. Load the default at render time instead, change the one part you need, and render that. The override below puts a frame around every standalone image; three worked examples apply the same four steps to [[the preamble>>doc:documentation.extensions.dev.latex.override-template.customize-preamble.WebHome]], to [[every table cell>>doc:documentation.extensions.dev.latex.override-template.italic-table-cells.WebHome]] and to [[one table's layout>>doc:documentation.extensions.dev.latex.override-template.wrap-table-cells.WebHome]]. | ||
| 2 | |||
| 3 | 1. Pick the template to override and read its default. The name is the Block's simple class name, so an image is ##ImageBlock##, and the shipped defaults are in the extension's jar under ##templates/latex/default/##. Find the smallest piece of it you want different: here that is the single line writing the image.((( | ||
| 4 | {{code language="tex"}} | ||
| 5 | \includegraphics{$latex.tool.escape($resourceReference.reference)} | ||
| 6 | {{/code}} | ||
| 7 | ))) | ||
| 8 | 1. Write the override. It is four steps: get the default, compute the new content, set it, render it. The computing is done with the [[##$stringtool## Velocity tool>>doc:extensions:Extension.Velocity Module||anchor="HVelocityTools"]], whose ##replace##, ##replaceAll## and ##replacePattern## cover most of what an override needs.((( | ||
| 9 | {{code language="tex"}} | ||
| 10 | ## Step 1: get the default template being overridden | ||
| 11 | #set ($template = $latex.processor.getTemplate('default/ImageBlock')) | ||
| 12 | ## Step 2: compute the new content | ||
| 13 | #set ($original = '\includegraphics{$latex.tool.escape($resourceReference.reference)}') | ||
| 14 | #set ($framed = '\fbox{\includegraphics{$latex.tool.escape($resourceReference.reference)}}') | ||
| 15 | #set ($newContent = $stringtool.replace($template.content.content, $original, $framed)) | ||
| 16 | ## Step 3: set the new content | ||
| 17 | #set ($discard = $template.content.setContent($newContent)) | ||
| 18 | ## Step 4: render the modified template | ||
| 19 | $latex.processor.render($template)## | ||
| 20 | {{/code}} | ||
| 21 | |||
| 22 | The ##default/## prefix is what asks for the shipped template rather than for yours, and it is what stops the override from calling itself. The single quotes matter too: Velocity interpolates a double-quoted string, and both of these hold ##$## references that have to survive into the template unevaluated. | ||
| 23 | ))) | ||
| 24 | 1. Add the template to your skin. Edit the skin the wiki uses, ##XWiki.DefaultSkin## on a standard installation, in Objects mode; add an object of type ##XWiki.XWikiSkinFileOverrideClass##, set its **Path** to ##latex/ImageBlock## and paste the template into **Content**. A skin is one of [[several places a template can come from>>doc:documentation.extensions.dev.latex.template-mechanism.WebHome]], and the only one needing no access to the server's filesystem.((( | ||
| 25 | {{image reference="override-skin-object.png" size="large" alt="The object editor of the skin page, with a Skin File Override object whose Path field holds latex/ImageBlock and whose Content field holds the override template"/}} | ||
| 26 | ))) | ||
| 27 | 1. Export a page holding a standalone image. The package's page file now writes that image through ##\fbox##.((( | ||
| 28 | {{code language="tex"}} | ||
| 29 | \fbox{\includegraphics{files/attachments/xwiki/Welcome/WebHome/welcome-banner.jpg}} | ||
| 30 | {{/code}} | ||
| 31 | |||
| 32 | Compiled, the frame is there: | ||
| 33 | |||
| 34 | {{image reference="override-framed-image.png" size="large" alt="A page of the exported PDF, showing a frame drawn around the image"/}} | ||
| 35 | ))) |
