Tutorial

Every .tex file a LaTeX export produces opens with a preamble: the \usepackage lines and the macro definitions the rest of the document depends on. It is written by the Preamble template, so a latex/Preamble template of your own takes its place — Template Mechanism explains that lookup. In this tutorial you add a package the default preamble does not load, widen one of the lines it does load, and read both changes back out of a real export.

1. Read the preamble you are starting from. Export any page to LaTeX and open index.tex in the package: everything before \begin{document} is the preamble, and the line the last step widens is in there.

   %% For the TOC macro, to have local tocs
   \usepackage{etoc}
   %% For the Formula macro
   \usepackage{amsmath}
   %% For links to attachments (we embed the attachments and link to them)
   \usepackage{attachfile}

2. Add a package. Render the default template first, then write your own lines after it: everything the default writes is kept, and only your addition is new. This one adds tabu, for tables. Put it in a latex/Preamble template and install it on the skin.

   #set ($template = $latex.processor.getTemplate('default/Preamble'))
   $latex.processor.render($template)
   %% For nice tables!
   \usepackage{tabu}##

3. Widen a line the default writes. The default loads amsmath for formulas, and the whole AMS set is wanted instead. Appending cannot do that, so edit the default's content before rendering it, with the four-step override strategy. Both changes belong in the same template, since a wiki has one latex/Preamble.

   ## Step 1: get the default template being overridden
   #set ($template = $latex.processor.getTemplate('default/Preamble'))
   ## Step 2: compute the new content
   #set ($newContent = $stringtool.replace($template.content.content, '\usepackage{amsmath}', '\usepackage{amsmath, amsthm, amssymb, amsfonts}'))
   ## Step 3: set the new content
   #set ($discard = $template.content.setContent($newContent))
   ## Step 4: render the modified template
   $latex.processor.render($template)
   %% For nice tables!
   \usepackage{tabu}##

4. Export the page again and open index.tex. The AMS line is wider and still sits where the default put it, which is what makes replacing the way to place a package among the others.

   %% For the Formula macro
   \usepackage{amsmath, amsthm, amssymb, amsfonts}

   The appended package comes after everything the default wrote, at the very end of the preamble.

   %% Use LaTeX quotes by default
   \MakeOuterQuote{"}
   
   %% For nice tables!
   \usepackage{tabu}
   
   \begin{document}

   Every .tex file of the package carries the preamble, so both changes are in the page files as well as in index.tex.

FAQ

Do I have to override the template just to add a package?

No. The default Preamble template offers extension points, and a UI extension contributing to org.xwiki.contrib.latex.Preamble.usepackage.after adds its packages without taking the template over. That is the route for an extension that ships packages of its own; overriding is for changing what the default itself writes.

Why is my package loaded after every other one?

Because anything written after $latex.processor.render($template) lands at the end of the preamble, after every package the default loads, hyperref included. A package that has to load before one of those goes in by replacing the default's line, as in step 3.

Related

• Override a Template
• Render Table Cells in Italic
• Wrap Long Table Cells
• Template Script Bindings
• Extension Points