Configuring v3 Templates

The v3 PDF renderer produces archivable PDF/A output for Liquid templates and is the required engine for ZUGFeRD/Factur-X e-invoices. This article describes the basic setup of a v3 template.

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 and the PDF Renderer field already set to v3. You can use them as a model or reference when defining your own template according to your use case and corporate identity.

Configuring v3 Template Rendering

Preparing a template to use the v3 PDF renderer involves the following steps:

1. Create a new template, clone an existing template, or open an existing template.

   If you clone one of the default v3 templates, the PDF Renderer field is already set to v3 and the v3 Liquid file is already attached. In this case, you can skip steps 2 and 3.

2. In the Layout & Design section, click next to the PDF Renderer field and specify the value v3.

3. Attach the required Liquid template files.

   In the Notes & Attachments area, click to open the action menu, select Upload Files, then proceed as prompted.

   This operation requires the custom Type field (ONB2__Type__c) to be available on the page layout of the Content Version object. For details about adding fields to page layouts, see Modifying Page Layouts or Search Layouts.

   Make sure to set the Type of the uploaded files to Liquid Template.

4. Optionally, adjust PDF rendering options.

   In the Layout & Design section, click next to the PDF Options field and specify options for the PDF output as required. The field value is in JSON notation, like

   {
       "locale": "de-DE",
       "currency": "EUR",
       "currencyDisplay": "code"
   }
   

   For the available properties, see PDF Options.

5. Click Save to apply your template customization.

PDF Options

The PDF Options field controls locale, currency and number formatting for the v3 render, as well as rendering behavior. The field value is in JSON notation.

The field value is in JSON notation, like

{
    "locale": "de-DE",
    "currency": "EUR",
    "currencyDisplay": "symbol",
    "useDigitGrouping": true,
    "minimumFractionDigits": 2,
    "maximumFractionDigits": 5
}

JustOn recommends to set at least the locale property.

The formatting properties are applied in the Liquid file through the corresponding filters: {{ value | decimal }}, {{ value | currency }} (requires locale and currency), {{ value | percent }} (requires locale), and {{ value | money }} (for objects with amount and currency properties). For details, see Using Custom Liquid Filters.

Defining Headers, Footers and the Page Counter

Unlike v2, the v3 renderer does not use the template Page Header and Footer record fields through the engine. In v3, page headers, footers and page counters are defined in the Liquid file using print CSS – @page margin boxes together with the counter(page) and counter(pages) functions.

For example, to render a running footer like Invoice Page 1 of 2, add the following to the <style> block of the Liquid file:

@page {
    size: A4;
    margin: 2cm 1.5cm 3cm 2.5cm;

    @bottom-center {
        content: "Invoice Page " counter(page) " of " counter(pages);
    }
}

The shipped default v3 templates already define a page counter this way. Adjust the content string to localize it, for example, content: "Seite " counter(page) " von " counter(pages);.

For details on working with Liquid files, see Working With Liquid Code.

Document Metadata

The v3 renderer writes PDF document metadata from the Liquid file:

• the PDF title from the <title> element (or <meta name="title">),
• author, subject and keywords from the corresponding <meta> tags.

Template Field Usage in v3

Because structure and styling live in the Liquid file, most Template record fields are ignored by v3. The record still controls localized text, text blocks, locale/format settings, and a few feature gates:

Related Tasks

Configuring a v3 template can involve the same additional tasks as any other Liquid template – specifying a counter, default payment due, payment reference text, and the invoice email. For details, see Configuring Liquid Templates.

For the ZUGFeRD-specific setup, see Configuring ZUGFeRD E-Invoices.