Kimai logo Kimai User manual

PDF templates

Kimai supports custom PDF templates in the invoice and export screens

PDF templates are basically the same as Twig templates (which themselves create HTML). The generated HTML is processed by the MPdf library, which will convert the HTML and CSS to PDF.

There are some additional contents (that need special markup), which define e.g. the page header and footer. Please read the MPdf documentation and check the default PDF templates.

Setting options

You can customize many mPDF options and configurations like the page format with the pdfContext.setOption(name, value) syntax:

{%- set option = pdfContext.setOption('name', 'value') -%}

Changing the filename

{%- set customer = query.customers|length == 1 ? query.customers.0 : null -%}
{%- set filename = 'ACME_' ~ (customer is not null ? customer.name|replace({' ': '-'}) ~ '_' : '') ~ query.begin|date_format('Y-m') -%}
{%- set option = pdfContext.setOption('filename', filename) -%}

PDF/A compliance

You can create a PDF/A1-b compliant document by setting these configurations in your template:

{%- set option = pdfContext.setOption('PDFA', true) -%}
{%- set option = pdfContext.setOption('PDFAauto', true) -%}

Available fonts

The PDF engine comes with many fonts that can be used without the need for installing fonts in your computer system.

  • Defaults: times, serif, helvetica, sans, sans, courier, monospace
  • Built-in: dejavusanscondensed, dejavusans, dejavuserif, dejavuserifcondensed, dejavusansmono, freesans, freeserif, freemono, ocrb, abyssinicasil, aboriginalsans, jomolhari, taiheritagepro, aegean, aegyptus, akkadian, quivira, lannaalif, daibannasilbook, garuda, khmeros, dhyana, tharlon, padaukbook, zawgyi-one, ayar, taameydavidclm, mph2bdamase, briyaz, lateef, sun-exta, unbatang

Missing character

The default font used in the PDFs does not support certain character ranges, which will usually result in the ☐ box symbol, that symbolizes any character that is not available in the used font. Unfortunately it is still not out of the box possible to render or display right-to-left, cyrillic and asian languages in PDFs. Please read the relevant MPDF documentation about fonts and them the chapter about all available fonts. As last resort (and only after trying the below hints) read these Adobe docs and try the downloadable font pack for Windows and macOS.

The following font/language combinations were successfully used by the community. Activate them in your template by using e.g. this CSS: body { font-family: sun-exta, unbatang, sans-serif; }

  • Hebrew works with helvetica, sans, dejavusanscondensed, dejavusans, freesans, freeserif, freemono, quivira, mph2bdamase, sun-exta
  • Cyrillic works with times, sans, courier, helvetica, serif, monospace, mono, dejavusanscondensed, dejavusans, dejavuserif, dejavusansmono, freesans, freeserif, freemono, quivira, mph2bdamase, sun-exta, unbatang
  • Japanese works with sun-exta and unbatang, which can be downloaded from here (if missing on your system)

Font debugging

You can use the following template to debug fonts. Replace the sentence The quick brown fox jumps over the lazy dog with the text you want to test.

{%- set defaultFonts = ['times', 'serif', 'helvetica', 'sans', 'sans', 'courier', 'monospace', 'mono'] -%}
{%- set builtInFonts = ["dejavusanscondensed", "dejavusans", "dejavuserif", "dejavuserifcondensed", "dejavusansmono", "freesans", "freeserif", "freemono", "ocrb", "abyssinicasil", "aboriginalsans", "jomolhari", "taiheritagepro", "aegean", "aegyptus", "akkadian", "quivira", "lannaalif", "daibannasilbook", "garuda", "khmeros", "dhyana", "tharlon", "padaukbook", "zawgyi-one", "ayar", "taameydavidclm", "mph2bdamase", "xbriyaz", "lateef", "sun-exta", "unbatang"] -%}
{%- set fontData = pdfContext.setOption('fonts', customFonts) -%}
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Font Demo</title>
</head>
<body>
    <h2>Default PDF fonts</h2>
    {% for fontName in defaultFonts %}
        <p style="font-family: {{ fontName }}">The quick brown fox jumps over the lazy dog ({{ fontName }})</p>
    {% endfor %}
    <pagebreak />
    <h2>Built-In fonts</h2>
    {% for fontName in builtInFonts %}
        <p style="font-family: {{ fontName }}">The quick brown fox jumps over the lazy dog ({{ fontName }})</p>
    {% endfor %}
</body>
</html>

Custom fonts

If you want to use a custom font in your PDF, you can configure it like that:

{%- set fontData = pdfContext.setOption('fonts', {
'demo': {
    'R': 'Demo-Regular.ttf',
    'B': 'Demo-Bold.ttf',
    'I': 'Demo-Italic.ttf',
    'BI': 'Demo-BoldItalic.ttf'
}
}) -%}
<style>
body { 
    font-family: 'demo', sans-serif;
}
</style>

The font files must be stored in the directory var/data/fonts/ within the Kimai directory, in this case it would be:

  • var/data/fonts/Demo-Regular.ttf
  • var/data/fonts/Demo-Bold.ttf
  • var/data/fonts/Demo-Italic.ttf
  • var/data/fonts/Demo-BoldItalic.ttf

Page size

Want to display the PDF in a different size, e.g. because your customer expects US-Letter and not the standard size DIN-A4? Xou can add a CSS rule to your twig template:

<style>
@page { 
    sheet-size: LETTER-L;
}
</style>

You could also try to set the page-size via options:

{%- set option = pdfContext.setOption('format', 'A4-L') -%}

Available sizes are:

  • A4, A3, Letter, Legal, Executive, Folio, Demy, Royal, A, B, Ledger, Tabloid …
  • A4-L, A3-L, Letter-L, Legal-L, Executive-L, Folio-L … for landscape

More information available in the MDPF documentation and the full list of available sizes can be found here (check format).

Top