Override a Template
Steps
A template you supply replaces the shipped one for every Block of its kind, which is how a template is found. 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, to every table cell and to one table's layout.
- 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.
\includegraphics{$latex.tool.escape($resourceReference.reference)} - 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, whose replace, replaceAll and replacePattern cover most of what an override needs.
## Step 1: get the default template being overridden #set ($template = $latex.processor.getTemplate('default/ImageBlock')) ## Step 2: compute the new content #set ($original = '\includegraphics{$latex.tool.escape($resourceReference.reference)}') #set ($framed = '\fbox{\includegraphics{$latex.tool.escape($resourceReference.reference)}}') #set ($newContent = $stringtool.replace($template.content.content, $original, $framed)) ## Step 3: set the new content #set ($discard = $template.content.setContent($newContent)) ## Step 4: render the modified template $latex.processor.render($template)##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.
- 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, and the only one needing no access to the server's filesystem.
- Export a page holding a standalone image. The package's page file now writes that image through \fbox.
\fbox{\includegraphics{files/attachments/xwiki/Welcome/WebHome/welcome-banner.jpg}}Compiled, the frame is there:
FAQ
Why not copy the whole default template?
A copy freezes the behaviour of the release it was taken from. Every later fix and addition the extension makes to that template stops reaching your export, silently, and nothing reports it. Loading the default at render time keeps all of that and leaves only your one change on top.
Why does getTemplate return nothing?
The name it takes is relative and carries no latex/ prefix, so the shipped template is default/ImageBlock, not latex/default/ImageBlock. Dropping the default/ instead finds your own override, and the template then renders itself.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
