PDF Rendering v3 Concepts
The template is the model based on which the PDF copy of an invoice, dunning reminder or account statement is rendered. It defines its contents and layout. Produced PDF documents are intended to be distributed via email or postal service to customers, and can be exported and archived.
As of v2.119, JustOn Billing & Invoice Management provides a new PDF rendering engine, v3, for Liquid templates. It produces archivable PDF/A documents and is the required engine for ZUGFeRD/Factur-X e-invoices.
Note
Be aware that creating and modifying Liquid templates requires profound skills in web development techniques, in particular, Liquid template language and Cascading Style Sheets (CSS).
Creating and maintaining Liquid templates constitutes custom development. Related issues are therefore not covered by the general maintenance and support contract for JustOn.
- Related information:
- Configuring v3 Templates
Liquid Template Concepts
Configuring ZUGFeRD E-Invoices
PDF Renderer Versions
JustOn Billing & Invoice Management selects the PDF rendering approach per template, using the PDF Renderer field on the template record:
| PDF Renderer | Mechanism | Engine | Output |
|---|---|---|---|
| empty | Standard template | Salesforce Visualforce PDF rendering | Standard PDF |
v2 |
Liquid template | JustOn PDF service (Chromium) | Standard PDF |
v3 |
Liquid template | JustOn PDF service (OpenHTMLtoPDF) | PDF/A-3B |
v2 and v3 use the same Liquid template files – what changed in v3 is the rendering engine and its output. v2 remains the default engine for Liquid templates; v3 is opt-in per template.
Info
v3 is not a new template language or file format. If you already work with Liquid templates, you keep your Liquid files – but the different engine affects which CSS and fonts render correctly. For details, see Differences From v2.
Why v3 Exists
The v2 engine is a headless Chromium browser. Chromium produces regular PDF files, but it cannot produce PDF/A: it has no concept of PDF/A conformance, PDF/A identification metadata, or a fixed output intent.
PDF/A-3 is the mandatory container for ZUGFeRD/Factur-X hybrid e-invoices. To support ZUGFeRD, JustOn Billing & Invoice Management requires a new rendering engine. The v3 engine (based on OpenHTMLtoPDF and Apache PDFBox, a CSS rendering engine rather than a browser) produces PDF/A output natively.
PDF/A output
Every v3 PDF is a PDF/A-3B document (ISO 19005-3), produced automatically with no extra configuration. This means:
- the document is self-contained – all fonts are embedded,
- it declares an sRGB output intent, and
- it carries PDF/A identification metadata.
PDF/A is an ISO-standardized format for the long-term archiving of electronic documents, which makes v3 output suitable for compliant long-term storage.
Two Roles of v3
It helps to hold two facts about v3 together:
- ZUGFeRD prerequisite
- A ZUGFeRD e-invoice requires a v3 template – this is a hard prerequisite. The v2 and standard renderers do not produce a PDF/A base into which the invoice XML can be embedded. For details, see Configuring ZUGFeRD E-Invoices.
- General upgrade
- v3 is also a general rendering upgrade that is usable without ZUGFeRD. Most v3 templates are ordinary invoices that simply gain archivable PDF/A output.
How v3 relates to ZUGFeRD
For ZUGFeRD e-invoices, JustOn Billing & Invoice Management first renders the PDF/A-3 document using v3, then embeds the EN 16931 invoice XML to form the final ZUGFeRD file.
v3 renders the PDF/A container – it does not itself create the embedded XML. Building and embedding the Cross-Industry-Invoice (CII) XML is handled by the JustOn e-invoice creation, not by the PDF renderer. For details, see Configuring ZUGFeRD E-Invoices.
Structure and Styling Live in Liquid Code
The key mental model for v3 is that structure and styling are defined in the Liquid template file, not on the template record:
- Structure – which tables exist, their columns and rows, sections, subtotals, page layout, and the page counter – is defined by the Liquid file, which iterates over the invoice data and lays everything out itself.
- Styling is defined by the Liquid file (its markup and CSS), plus the optional
Custom CSSfield. - Only text – localized labels and free-text blocks – along with locale/format settings and a few feature gates are mapped from the template record. Most other template fields that used to drive the standard (Visualforce) PDF are ignored by v3.
Practical consequence: to change the invoice layout, tables, columns or look, you edit the Liquid file, not the template record's structure fields.
For a field-by-field overview of which Template fields v3 reads and which it ignores, see Configuring v3 Templates.
Default v3 templates
JustOn Billing & Invoice Management ships three default v3 (Liquid) invoice templates – one each for English (DefaultV3EN), German (DefaultV3DE) and French (DefaultV3FR) with a corresponding Liquid file attached. You can install the package and immediately produce a correct invoice PDF in any of the three languages, and use these templates as a model or reference for your own.
Differences From v2
Because v3 uses a different engine, some CSS and fonts that render under v2 behave differently or are not supported under v3. Templates should always be previewed after switching a template to v3.
| Aspect | v2 (Chromium) | v3 (OpenHTMLtoPDF) |
|---|---|---|
| CSS support | Full modern CSS | CSS 2.1 + print extensions; no Flexbox, Grid, calc(), custom properties (var()), transitions/animations, or @media queries other than @media print |
| Default fonts | Chromium's built-in fonts | Built-in Noto families (Noto Sans, Noto Serif, Noto Sans Mono, with symbol/emoji/math fallback) |
| Font embedding | @font-face with WOFF/WOFF2 |
@font-face with TTF only (static TrueType; variable fonts not supported) |
| Output format | Standard PDF | PDF/A-3B (archival) |
| Page header/footer | Template Page Header/Footer fields |
Defined in the Liquid file via @page margin boxes and page counters |
v3 additionally supports several print-oriented features, including @page rules (size, orientation, margins), page-break-*, page numbering via counter(page)/counter(pages), repeating table headers (<thead>), footnotes (float: footnote), inline SVG, CSS transforms, border-radius, box-sizing, and right-to-left/bidirectional text.
Info
The general Liquid template limitations (no external resources, no scripts, restricted set of HTML tags) apply to v3 as well.