Quaderno Templates: The Basics

What are templates?

Templates are the word we use for how documents are structured in Quaderno. Every invoice, receipt and credit note is the result of filling a template with your information, making it look beautiful!

How do they work?

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

If you have 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 system, and we have lots of examples to give you a starting point.

To learn about Liquid, we recommend checking out the basics page from Shopify, but here's a quick rundown.

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 }}.

Take an item, for example (and note the tag ({% for item in document.items %} ... {% endfor %} that makes looping through all the items happen!):

<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>

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.

Some Quaderno-specific tips

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

  • Your canvas must be 800x1131 pixels in size
  • Your logo space must be 308x125 pixels in size
  • If you want to get the maximum quality when you print your invoice at 300dpi, your logo image file must be 955x388 pixels.

And apart from that, you'll want to check out the related article on the special variables that Quaderno templates have available to them.

This is awesome, how can I learn more?

Great to see you so enthusiastic!

To reiterate, it's really worth spending a little time getting to grips in more depth with the Liquid syntax. We've got our own look at Liquid/Quaderno Template syntax here for you to check out as a supplement/cliff notes version.

After that (or alongside if you're really in a rush), we've got a sweet in-depth walkthrough tutorial for you to get stuck into that gets you into how Liquid is specifically applied to Quaderno documents and information, and walks you through creating a Quaderno template from scratch.

Keep rocking the free world, intrepid Quadernonaut!

Still need help? Contact Us Contact Us