action.skip

Liquid Template 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.

template
Combining data with a template to produce an output

In addition to the fields that are printed to the PDF, the templates also include texts for the email that JustOn sends to distribute the rendered PDF documents.

An alternate version of JustOn's PDF template mechanism is built around files written in the Liquid template language. To render the files and to produce the corresponding PDF output, JustOn uses a dedicated service based on the Chromium PDF engine. Use this approach if your business requires sophisticated PDF customizations that are difficult or impossible to implement with standard templates and Visualforce PDF rendering, like, for example, custom fonts or QR codes for Swiss 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.

General Concepts

Template Variation

Usually, you have multiple templates that each serve a specific target. There are, basically, two ways to diversify templates:

  • Creating multiple templates for different targets, for example, different locales or specific customer groups,
  • Using both dedicated Liquid files (attachments to the template record) to customize specific parts of the resulting PDF files for different purposes, for example, invoice, credit, cancellation, and dedicated template detail records to customize email texts or counters for specific purposes (see Common Approach).

Info

You can combine the two approaches.

JustOn provides default Liquid templates for invoices, dunning reminders and account statements (in English) as well as for Swiss QR-code invoices (in English and German). Based on these files, you can define your own templates.

Example Liquid templates

Invoice Template (English)
Dunning Template (English)
Account Statement Template (English)

Swiss QR Code Invoice Template (English)
Swiss QR Code Invoice Template (German)

Template Assignment

This is how JustOn Billing & Invoice Management looks for a template:

ON_Template field on the invoice source records
ON_Template field on the account
     ↳ Template field on the business entity
          ↳ Default template

(1) To predefine a specific template for your standard use cases, you usually set it via the ON field ON_Template on your source records for the invoice generation.

Generally, ON_Template is a formula field. In the simplest use case, you just name the template to use. If necessary, however, you use a formula that returns a dedicated template according to your specific criteria – target region, business entity, product group, etc.

(2) As a more general setting, you can define a dedicated template per customer – using an ON_Template field on the account. If the source record does not specify a template, JustOn uses the one set on the account.

(3) In addition, you can set a template per business entity. If there is no template defined on the source record or the account, it is retrieved from the Template field on the business entity that is related to the target record (invoice or statement).

(4) If neither the source record, the account nor the business entity specify a template to use, JustOn Billing & Invoice Management falls back to the Default template. Note that you can leave the Default template shipped with the package untouched and use this as your fallback, or create a custom template according to your needs and name it Default.

Info

As long as an invoice has the status Draft, you can assign another template to the invoice.

Common Approach

JustOn provides default Liquid template files for invoices, dunning reminders and account statements:

Liquid Template Title Used for
Invoice Template invoices, credits, cancellations, pro forma, deposit
Dunning Template all dunning levels
Account Statement Template account statements

In the simplest approach (no locale-specific variation, etc.), you have one template record to which are attached the Liquid template files, as well as are associated the template detail records to cover your use cases. Now depending on the use case, JustOn uses the template record, the Liquid file attachment or the associated template detail to produce the PDF file and the email.

template_v2_process
Example use cases

Your business may, however, need to cover more complex scenarios, like multiple locales, different customer groups, etc. In this case, you double this structure: You create a second (third, etc.) template record intended for the specific purpose, and attach the corresponding specific Liquid template files and associate the relevant template detail records.

Use Case Data Category Data Origin
Invoice PDF layout and standard texts Invoice Liquid template
Email standard texts Template record
Counter Template record
Credit PDF layout and standard texts Invoice Liquid template
Email standard texts Credit template detail record
Counter
Optionally, if different from invoice counter
Credit template detail record
Cancellation PDF layout and standard texts Invoice Liquid template
Email standard texts Cancellation template detail record
Counter
Optionally, if different from invoice counter
Cancellation template detail record
Dunning reminder PDF layout and standard texts Dunning Liquid template
Email standard texts Dunning template detail record
Counter Dunning template detail record
Account statement PDF layout and standard texts Account statement Liquid template
Email standard texts Account statement template detail record
Counter Account statement template detail record

Configuring Templates
Configuring Template Details

Limitations

Be aware of the following restrictions:

  • No external resources will be loaded (like image URLs).
  • To embed assets (images, fonts etc.), you have to use data URIs. The assets must be encoded as base64 strings. For details, see Embedding Assets.
  • By default, backgrounds are not rendered. To control this behavior, use specific CSS styles per element:

    -webkit-print-color-adjust: exact;
    
  • No scripts can be run.

  • The following tags are allowed: a, abbr, acronym, address, area, article, aside, b, base, basefont, bdi, bdo, big, blockquote, body, br, button, canvas, caption, center, cite, code, col, colgroup, data, datalist, dd, del, details, dfn, dialog, dir, div, dl, dt, em, fieldset, figcaption, figure, font, footer, form, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, img, input, ins, kbd, label, legend, li, link, main, map, mark, meta, meter, nav, noframes, noscript, ol, optgroup, option, output, p, param, picture, pre, progress, q, rp, rt, ruby, s, samp, section, select, small, source, span, strike, strong, style, sub, summary, sup, svg, table, tbody, td, template, textarea, tfoot, th, thead, time, title, tr, track, tt, u, ul, var, wbr.
  • Consequently, the following tags are not allowed: applet, audio, embed, frame, frameset, iframe, object, script, video.