5.9. The qrbill Freemarker directive (for advanced users)
Prev  Chapter 5. Templates guide: How to create and edit templates for Fanurio  Next

5.9. The qrbill Freemarker directive (for advanced users)

The qrbill directive is a custom Freemarker directive implemented in Fanurio that allows you to create Swiss QR-bills as inline PNG images. It works as a wrapper around the Swiss QR Bill for Java library. QR-bills created with this directive can be validated online.

This directive can be used by advanced users who need to create their own invoice templates. Regular users can add a QR-bill to their invoices using the template editor.

Note: Although the qrbill directive can be used in any invoice Freemarker template, it's very likely you will be using it in templates that create HTML documents. One way to include inline images in an HTML document is to add them in the src attribute of an img tag as shown in the following examples.

5.9.1. Parameters

The qrbill directive has the following parameters that allow you to specify how the QR-bill is created.

  • Bill

    The bill parameter is mandatory and it specifies the invoice for which the QR-bill is created. The following example sets bill to invoice, the variable that holds the invoice details in an invoice template. 

    <img src="[@qrbill bill=invoice /]"/>

    The QR-bill fields are populated with invoice data as follows:

    • Account: The IBAN stored at business level in the Other Number field. Go to Business » My Business Details to enter it.

    • Creditor: The name, address, zip, city and country fields of the business are used to configure the QR-bill creditor fields. The country field must contain a two-letter country code to be valid. If it's missing, CH (Switzerland) is used by default.

    • Debtor: The name, address, zip, city and country fields of the invoice client are used to configure the QR-bill debtor fields. The country field must contain a two-letter country code to be valid. If it's missing, CH (Switzerland) is used by default.

    • Currency: The invoice currency. Only EUR and CHF are allowed.

    • Amount: The invoice total.

    • Reference: The Creditor Reference (ISO 11649) generated from the invoice number. For instance, invoice 1 has the reference RF741.

    • Additional information: If the invoice has any notes, they are added to the 'Unstructured message' field. The 'Billing information' field is not added to the QR-bill.

  • Language

    The language parameter is optional and it allows you to specify the language for the QR-bill to German (DE), French (FR), Italian (IT) or English (EN). By default, the language is set to German (DE). 

    <img src="[@qrbill bill=invoice language='EN' /]"/>

  • Resolution

    The resolution parameter is optional and it specifies the resolution for the generated image in DPI (dots per inch). By default, the resolution is set to 600 DPI. 

    <img src="[@qrbill bill=invoice resolution=144 /]"/>

  • Separator

    The separator parameter is optional and it allows you to specify the separator between the payment part and the receipt to SOLID_LINE, SOLID_LINE_WITH_SCISSORS, DASHED_LINE, DASHED_LINE_WITH_SCISSORS, DOTTED_LINE, DOTTED_LINE_WITH_SCISSORS or NONE. By default, the separator is set to DASHED_LINE_WITH_SCISSORS. 

    <img src="[@qrbill bill=invoice separator='DASHED_LINE' /]"/>

  • Font family

    The font_family parameter is optional and it allows you to specify the font for the text to Arial, Frutiger, Helvetica or Liberation Sans. By default, the font is set to Arial. 

    <img src="[@qrbill bill=invoice font_family='Helvetica' /]"/>

5.9.2. Integrating qrbill in HTML

According to the specs (2.1 QR-bill), a QR-bill means:

  1. a bill with a payment part and receipt integrated in the form, and

  2. a bill with a separately enclosed payment part and receipt.

In order to create a bill with a separately enclosed payment part and receipt, you need to define a separate CSS page in the style section or in one of the CSS files: 

@page qrbill {
  size: A4 Portrait;
  padding: 0mm;
  margin: 0mm;
}

and then use the following code with the qrbill directive: 

<div style="page: qrbill;">
  <img src="[@qrbill bill=invoice/]" width="210mm" />
</div>

The width of the image created by the qrbill directive is set to 210mm to span the entire width of the page.

Prev  Up  Next
5.8. Placeholders reference  Home  5.10. The jfreechart Freemarker directive (for advanced users)