Contents

Overview

Writing templates

Contents

An understanding of HTML and CSS is required before you can start writing templates for gen-invoice.

Overview

Templates are the core mechanism by which users can customise the generation of invoices or quotes. After processing all other input data and calculating subtotals and totals, the invoice generator passes all data to the user’s selected template for formatting. Templates control how this information is presented and acted upon, using powerful features of the Jinja template engine including loops and conditional statements.

Although line item data must follow a predetermined information schema, all other input data adheres to whatever schema is prescribed by the selected template. This provides users with the flexibility to incorporate any arbitrary information of their choosing when generating invoices and quotes.

Templates can opt to allow visual customisation via stylesheets by including the {{ css }} template tag. This allows users to create any number of different visual themes that are compatible with a single template, or with a set of conventions that one or more templates adhere to. If users do not want to make use of this functionality then they can simply omit the {{ css }} template tag and embed CSS code directly in templates.

Getting started

It is recommended that you start by familiarising yourself with the default template that ships with the command-line interface for gen-invoice, which demonstrates key Jinja template features, including filters, loops and conditional statements. The default template is also designed to work with stylesheets, which is a feature you may or may not wish to adopt in your own templates. Once you are familiar with the default template then it may also be helpful to familiarise yourself with more advanced features of the Jinja template engine that you can incorporate in your own templates.

To begin your template, you can duplicate the default.html file in the templates subdirectory of the gen-invoice data directory and name the new HTML file as you see fit. You can then start modifying the template HTML to suit your requirements, such as reorganising the structure of the document or localising field labels related to company identifiers, bank branch identifiers, tax, etc.

One very important consideration when writing templates is determining the information schema that they will impose on payee and payer data, since the content and structure of these data files is dictated completely by the fields and loops used in the template. You might opt to add to or modify the fields used in the default template, or you might define a completely new information schema of your own design. If you are working with multiple templates then it is strongly recommended that you establish a consistent schema that all of your templates adhere to, in order to ensure your payee and payer data files are compatible with all of your templates.

Custom filters provided by gen-invoice

In addition to the built-in filters provided by Jinja itself, the invoice generator adds the following filters for use in templates:

  • currency: formats a numeric value as a currency string using the system’s locale settings.

Compatibility with stylesheets

The invoice generator is designed to pass stylesheet CSS data to templates via the css key in the context dictionary. Whether you choose to utilise this mechanism is entirely up to you:

  • If you want to embed all of your CSS styles in each template and remove any possibility of customisation or theming, simply remove the {{ css }} template tag from your template. This will ensure the stylesheet data provided by the invoice generator is discarded.

  • If you want to design your templates to allow customisation or theming, be sure to retain the {{ css }} template tag. It is recommended that you place this tag immediately after any CSS declarations that are embedded in the template, which will allow the stylesheet CSS to override any conflicting declarations that precede it.

Embedding resources

Ideally, the HTML files generated by your template should be entirely standalone and devoid of references to external resources such images, fonts, stylesheets, etc. If it is necessary to reference external resources then these should either be publicly-available on the internet (e.g. Google Fonts) or should be embedded using Data URIs (which are particularly well-suited to embedding images.) This ensures the resulting HTML files will be displayed consistently irrespective of where they are located within a device’s filesystem.

Debugging templates