Wiki source code of Extension Points
Last modified by Vincent Massol on 2026/08/30 20:43
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.1 | 1 | An extension can add to the LaTeX an export produces without owning the template that produces it. Every template exposes two UI extension points, one before its output and one after it, and what a UI extension contributes there is inserted into the exported document at that point. The shipped template stays in place and keeps whatever a later release changes in it, which is what separates an extension point from an [[override>>doc:documentation.extensions.dev.latex.override-template.WebHome]]. |
| 2 | |||
| 3 | A contribution is an ##XWiki.UIExtensionClass## object on a wiki page, or a ##UIExtension## component, as at [[any other extension point>>doc:Documentation.DevGuide.ExtensionPoint.WebHome]]. | ||
| 4 | |||
| 5 | == The Points Every Template Has == | ||
| 6 | |||
| |
6.1 | 7 | |=Name|=Extension point id|=Content is inserted |
| 8 | |Before any LaTeX Template|##org.xwiki.contrib.latex.*.before##|before the template's output | ||
| 9 | |After any LaTeX Template|##org.xwiki.contrib.latex.*.after##|after the template's output | ||
| |
3.1 | 10 | |
| 11 | The ##*## stands for the name of the template being rendered, which is the simple class name of its Block: ##ParagraphBlock##, ##TableCellBlock##, ##ImageBlock##. It is the [[name the renderer looks the template up by>>doc:documentation.extensions.dev.latex.template-mechanism.WebHome]], so a contribution to ##org.xwiki.contrib.latex.ParagraphBlock.after## lands after every paragraph of the export. | ||
| 12 | |||
| |
6.1 | 13 | [[The shipped templates on GitHub>>https://github.com/xwiki-contrib/latex/tree/master/latex-syntax/src/main/resources/templates/latex/default]] are the complete list of the names in play, release by release. |
| 14 | |||
| |
3.1 | 15 | Content contributed at these points is inserted as plain text. It is not rendered through the LaTeX renderer, so it is neither escaped nor formatted, and a Raw macro block in it produces nothing at all. Only the five document points below render their content as LaTeX. |
| 16 | |||
| 17 | == The Document and Preamble Points == | ||
| 18 | |||
| |
6.1 | 19 | |=Name|=Extension point id|=Content is inserted |
| 20 | |Before LaTeX XDOM Template|##org.xwiki.contrib.latex.XDOM.before##|at the top of the file, before ##\documentclass## | ||
| 21 | |Before LaTeX Preamble Template|##org.xwiki.contrib.latex.Preamble.before##|at the start of the preamble, before the first ##\usepackage## | ||
| 22 | |After LaTeX UsePackage Preamble Template|##org.xwiki.contrib.latex.Preamble.usepackage.after##|after the ##\usepackage## lines the extension writes | ||
| 23 | |After LaTeX Preamble Template|##org.xwiki.contrib.latex.Preamble.after##|at the end of the preamble, before ##\begin{document}## | ||
| 24 | |After LaTeX XDOM Template|##org.xwiki.contrib.latex.XDOM.after##|at the end of the body, before ##\end{document}## | ||
| |
3.1 | 25 | |
| 26 | These five are written into the ##XDOM## and ##Preamble## templates themselves rather than coming from the mechanism above. That is what gives ##Preamble##, a template belonging to no Block, points of its own, and what puts the content of ##org.xwiki.contrib.latex.XDOM.after## inside the document rather than after ##\end{document}##, where LaTeX would ignore it. | ||
| 27 | |||
| 28 | == What the Content Is == | ||
| 29 | |||
| 30 | A contribution is wiki syntax, and at the five document points it is rendered as LaTeX before being inserted. Ordinary text therefore arrives escaped: a per cent sign comes out as ##\%##, a backslash as ##\textbackslash{}##. LaTeX that has to reach the document untouched goes in a Raw macro whose syntax is ##latex/1.0##, which needs the [[Raw Macro>>doc:extensions:Extension.RawMacro.WebHome]] extension installed. | ||
| 31 | |||
| 32 | {{image reference="uix-raw-macro-example.png" size="large" alt="The Executed Content field of a UI extension object, holding a Raw macro block with syntax latex/1.0 and three LaTeX commands in its body"/}} | ||
| 33 | |||
| 34 | The rest of the object is the usual one: **Extension Point ID** is the id from the tables above, and **Extension Scope** decides which wikis the contribution applies to. | ||
| 35 | |||
| 36 | == The order Parameter == | ||
| 37 | |||
| 38 | Several UI extensions can answer the same point. They are rendered in the order of their ##order## parameter, **lowest first**, and one declaring no ##order## at all is rendered last. Values that are whole numbers are compared as numbers, so ##9## comes before ##10##; anything else is compared as text. | ||
| 39 | |||
| 40 | == A Contribution in Full == | ||
| 41 | |||
| 42 | Two contributions add a glossary to every export. The first, at ##org.xwiki.contrib.latex.Preamble.usepackage.after##, loads the package and declares the entries: | ||
| 43 | |||
| 44 | {{code language="none"}} | ||
| 45 | {{raw syntax="latex/1.0"}} | ||
| 46 | \usepackage{glossaries} | ||
| 47 | \makeglossaries | ||
| 48 | \newglossaryentry{xdom}{name=XDOM, description={the tree a wiki page is parsed into}} | ||
| 49 | {{/raw}} | ||
| 50 | {{/code}} | ||
| 51 | |||
| 52 | The second, at ##org.xwiki.contrib.latex.XDOM.after##, prints the glossary where the document ends: | ||
| 53 | |||
| 54 | {{code language="none"}} | ||
| 55 | {{raw syntax="latex/1.0"}} | ||
| 56 | \printglossaries | ||
| 57 | {{/raw}} | ||
| 58 | {{/code}} | ||
| 59 | |||
| 60 | The export then produces: | ||
| 61 | |||
| 62 | {{code language="tex"}} | ||
| 63 | \usepackage{footnote} | ||
| 64 | \makesavenoteenv{tabular} | ||
| 65 | \makesavenoteenv{table} | ||
| 66 | |||
| 67 | \usepackage{glossaries} | ||
| 68 | \makeglossaries | ||
| 69 | \newglossaryentry{xdom}{name=XDOM, description={the tree a wiki page is parsed into}} | ||
| 70 | |||
| 71 | %% the rest of the preamble, then the exported page | ||
| 72 | |||
| 73 | \printglossaries | ||
| 74 | \end{document} | ||
| 75 | {{/code}} |
