Customizing PDF templates

This page applies for Cyclos version 14 onwards. Previous versions used JasperReports to generate PDFs. Starting with 4.14, Cyclos generates an HTML file and uses the excellent openhtmltopdf library to transform it in a PDF file. The HTML is rendered using Thymeleaf, and Cyclos exports some helpers to the template.

Something to note is that the openhtmltopdf library transforms static HTML to PDF. Quoting their page: "Use this library to generated nice looking PDF documents. But be aware that you can not throw modern HTML5+ at this engine and expect a great result. You must special craft the HTML document for this library and use it's extended CSS feature like #31 or #32 to get good results. Avoid floats near page breaks and use table layouts."

The HTML files are in classpath under pdf-templates. You can find the original ones in <cyclos-web>/WEB-INF/lib/cyclos4-impl-<version>.jar, under the pdf-templates folder. To customize them, copy the desired files to the <cyclos-web>/WEB-INF/classes/pdf-templates folder (you need to create that folder).

Starting with Cyclos 4.15, voucher templates are a specially handled case for templates. You can create voucher templates in the content management menu, and then, in the System > Vouchers > Voucher types, select the template to use. Using voucher templates you don't need to tweak with the file system or deployed files. Just customize the template and a custom stylesheet in the template itself.

General tips:

• If you set a font size, always set a consistent line height, or the text will have an undesired offset.
• To do a voucher template without any border in the page, you should set both these in your template style:

@page {
  margin: 0
}

body {
  padding: 0
}

These tips applies when tweaking templates in the filesystem, not for Voucher templates:

• It is always advised to customize these templates in a local installation, not directly in production.
• In production runtime these files are read once and then cached in memory. Only a server restart will take the changes. So, to develop locally, we advise setting the variable cyclos.development = true on cyclos.properties, so the templates are read again every time, avoiding server restarts. Make sure, however, to not run in production with this setting in true, as it will slow down the entire system.

In thymeleaf templates Cyclos provides several helpers:

• #format.object(param): Formats a given object to be displayed
• #format.amount(currency, amount): Formats a given number as a currency amount
• #format.country(code): Returns the display name for a country with the given code (2-letter)
• #format.customValue(customField, value): Formats a custom field value
• #format.date(value): Formats a given date
• #format.number(value, scale): Formats a number with a given number of decimals
• #format.profileField(customOrBasicField, value): Formats a given basic or custom user profile field
• #decimal.isNegative(value): Returns whether the given number less than zero
• #decimal.isNegativeOrZero(value): Returns whether the given number is less than or equals zero
• #decimal.isPositive(value): Returns whether the given number is greater than zero
• #decimal.isPositiveOrZero(value): Returns whether the given number is grater than or equals zero
• #decimal.isZero(value): Returns whether the given number is equals zero

There are also custom URL handlers. That means you can include images or other resources using the custom protocols (schemes):

• image:<id>: Renders a Cyclos image with the given id (the same as in the database in the stored_files table)
• configImage:<type>: Renders a Cyclos configuration image (logo) by name. Available names: SYSTEM_LOGO, SHORTCUT_ICON, REPORTS_LOGO, MOBILE_LOGO, APP_LOGO, PAY_LOGO
• qrCode:<text>: Renders a QR-code image with the given content
• classpath:<resource>: Renders an image in the server classpath
• templateimage:<image_name>: Renders a voucher template image using the filename. Only applicable for voucher templates (Cyclos 4.15 onwards).

For voucher templates (Cyclos 4.15 onwards), the voucher being printed is an instance of VoucherReportEntry which allows access to the voucher itself, plus some other fields. For a reference, you can create a new template and inspect the default template. You'll always be able to preview a template, as long as you have at least one voucher type in your network.