Getting started with Quaderno templates

Template is the word we use for how documents are structured in Quaderno.

Every receipt, invoice, estimate, and credit note is the result of filling that template with your information, making it look beautiful ✨ The good news is, you can customize them too!

With some HTML know-how and a rough idea of how coding works then you’re well up to the challenge of creating your own templates using the quaderno-templates system.

How do templates work?

Quaderno templates are based on the Liquid templating engine created by the clever people over at Shopify.

To learn about Liquid, we recommend checking out the basics page from Shopify, but we’ll do a quick rundown on this article.

Templates use a combination of tags, objects and filters to put your details (dynamic content) into the templates that structure your financial documents behind the scenes.

Tags

Tags are the brains of your document, denoted by curly braces and percentage signs: {% and %}. They let you make decisions in a document, like to create a temporary variable in your document, loop over a series of objects, or even whether to show a logo or not:

{% if account.logo_url != "" %}
 <img src="{{account.logo_url}}" width="150" />
{% endif %}

If the account object property logo_url is not equal (!=) to “” (meaning that it’s not empty), then you put an image in with the logo_url as the src (source). Boom! Your lovely logo in pride of place on your document.

Note that the tag itself does not show in the document at all – only the img between the tags will show, if that account.logo_url isn’t an empty string!

Objects

Objects (like the above account object) have attributes that you can access (like logo_url) to display information in your document. They basically tell Quaderno where to show content on a document, so, unlike tags, objects accessed in this manner are visible (unless hidden by surrounding tag conditions). They are always wrapped by double curly braces: {{ and }}, for instance you could show an item description on your invoice with {{ item.description }}.

Combining this with looping tags like {% for %} , you can show all your items in a table easily:

<table>
 {% for item in document.items %}
 <tr>
 <td>{{item.description}}</td>
 <td>{{item.quantity}}</td>
 <td class="right">{{item.unit_price}}</td>
 <td class="right">{{item.subtotal}}</td>
 </tr>
 {% endfor %}
</table>

Just like that, you’ve enumerated every item in the document (like a list of products on an invoice), displaying their description, quantity, unit price and subtotal!

Filters

Filters are useful tools to modify the output of object properties, making them a little better looking, easier to read or otherwise useful. They are used within an object and are separated from the object’s target (item.unit_price, for example), by a single pipe character: | (though usually you put a space in either side of the pipe for clarity as well).

For example, financial amounts are stored in the background as numbers of cents (or pence) so that no decimal rounding errors can impact your bottom line. That’s great, except when you want to display those numbers on your documents – people aren’t used to seeing €10 written as 1000 cents! With filters, you can handle this, like so:

<strong>{{ document.total | money }}</strong><br>

The money filter converts that document.total number in cents to a string (like 1000 -> “1000” as characters instead of numbers) based on the currency of the document.

You should check the official list of Liquid filters, they're really useful. Here are a few Quaderno custom filters you can use:

Design tips for your custom documents

Here are a couple of design tips to help you get the most buttery-smooth results from your Quaderno templates:

• Your canvas must be 800×1131 pixels in size
• Your logo space must be 308×125 pixels in size
• If you want to get the maximum quality when you print your invoice at 300dpi, your logo image file must be 945×380 pixels.