Advanced PDF templates: the FreeMarker patterns worth knowing

Advanced PDF templates cover most transaction document requirements once you know a handful of patterns. The trouble is that the patterns are not really documented anywhere as patterns, they are scattered across forum answers, and the rendering engine has behaviour that surprises people who know HTML.

These are the six that come up in almost every template we build.

1. Conditional sections that collapse properly

Showing a block only when it has content is straightforward; the mistake is leaving the container behind when it is empty, so the document has a mysterious gap.

<#if record.shipaddress?has_content>
  <table class="addr">
    <tr><td>${record.shipaddress}</td></tr>
  </table>
</#if>

Use ?has_content rather than testing for an empty string. It handles a missing field, a null and an empty value in one test, which matters because which of those three you get depends on the record type.

2. Grouping a sublist

Line items grouped by category, by location or by any other column is one of the most requested layouts and has no built-in support. The reliable approach is to sort the rows in a saved search, then detect the change in the template.

<#assign lastGroup = "">
<#list record.item as item>
  <#if item.custcol_group != lastGroup>
    <tr><td colspan="4" class="grouphdr">${item.custcol_group}</td></tr>
    <#assign lastGroup = item.custcol_group>
  </#if>
  <tr><td>${item.item}</td><td>${item.quantity}</td></tr>
</#list>

3. Running totals

Subtotals per group, or any total the record does not expose as a field, are accumulated the same way, declare before the loop, add inside it.

<#assign groupTotal = 0>
<#list record.item as item>
  <#assign groupTotal = groupTotal + item.amount?number>
</#list>
<td>${groupTotal?string("#,##0.00")}</td>

4. Page break control

This is the one that catches everybody, because the renderer behind Advanced PDF is not a browser and CSS page-break behaviour is only partly honoured. Two things are worth knowing.

First, a table that spans pages will not repeat its header unless you put the header rows inside <thead>. This is the single most common complaint about long invoices, and the fix is a tag most people leave out because it makes no visible difference on page one.

Second, keeping a block together across a break is best done by making it a table and setting the break behaviour on the table, rather than trying to control the rows. Fighting it at row level tends to produce a template that looks right on your test record and breaks on a longer one.

<table>
  <thead>
    <tr><th>Item</th><th>Qty</th><th>Amount</th></tr>
  </thead>
  <tbody>
    <#list record.item as item>
      <tr><td>${item.item}</td><td>${item.quantity}</td><td>${item.amount}</td></tr>
    </#list>
  </tbody>
</table>

Always test with a transaction that runs to at least three pages. A template validated on a two-line order will ship with page-break bugs nobody sees until a customer receives a forty-line invoice.

5. Logos and branding per subsidiary

In a multi-subsidiary account, one template serving every entity is far easier to maintain than one template per entity. Drive the differences from the subsidiary record rather than duplicating the file.

<#if record.subsidiary?has_content>
  <img src="${subsidiary.logo@url}" style="height: 44px;" />
</#if>

6. Dates, numbers and locale

Formatting is where templates leak inconsistency. A date rendered raw in one place and formatted in another looks careless on a document going to a customer.

The last row is worth adopting as a habit. An unhandled missing field can fail the render outright, and a template that throws on one record in five hundred is a support ticket that arrives months after the project closed and takes a day to reproduce.

Book a free consultation

Tell us what you are running today and where it is breaking down. Most calls run 20 to 30 minutes and end with a clear next step. We reply within one business day.