Document templates

Templates change how your invoices, quotes, statements, reports, certificates and emails look and read. Make them in Admin > Templates. You need the permission to manage templates (owners have it).

If you never make a template, nothing changes. Your documents use the layout and wording from Admin > Documents, and your theme from Admin > Branding.

Make a template

1. Open Templates and choose a document type: Invoices, Quotes, Statements, Reports, Certificates or Emails.
2. Choose New template, give it a name, and pick where to start:
   • The standard layout: what the document looks like now.
   • The theme's starting point: if your theme ships one.
   • A copy of another template you made.
3. Edit it, check the Preview tab, and save.

You can have up to 25 templates for each document type. Duplicate copies one.

Layout

The layout is a list of blocks: details, charges, totals, and so on. Move a block up or down, hide it, remove it, or add one. Add a Text or Note block for your own words, or a Divider. Each block has a heading and options, such as whether to show the item code.

Pick a style: Classic (ruled tables), Modern (a colour band), or Compact (smaller type).

Wording

Set the title, the footer and how to pay. A field you leave empty uses the wording from Admin > Documents.

Styling

A little CSS, if you want to change colours or spacing. See CSS limits.

Twig

For layouts blocks cannot do, switch to Twig. See Edit as Twig.

The default, rules and pinning

You can mark one template for each document type as the default. Documents with no other rule use it.

A rule assigns a template to some documents. For invoices you can choose the invoice type (standard or deposit), the job type, the status or a customer. A rule matches when every condition you filled in matches. Rules are checked in order and the first match wins; use the arrows to reorder them.

You can also pin a template to one invoice or quote in its sheet, under Template. "Automatic" follows your rules and default. A PDF that was already made does not change.

How Rangefront chooses

For each document, from the top:

1. The template pinned on the record.
2. The first rule that matches.
3. Your default template for that kind of document.
4. Your theme (and its parent theme, if it has one).
5. The standard layout.

The Which template is used panel on the Templates page shows this for a sample. Pick the values (or paste an invoice or quote id) and choose Check. It tells you which template wins, why, and which theme files were looked at.

A document keeps the template it was made with. Changing a template later does not change documents already sent.

Merge fields

Put these in headings and text blocks. They are filled in when the document is made and always shown as plain text.

Document	Fields
Invoice	{{ customer }} {{ address }} {{ number }} {{ date }} {{ due_date }} {{ total }} {{ job }} {{ business }} {{ phone }} {{ email }}
Quote	{{ customer }} {{ address }} {{ number }} {{ title }} {{ date }} {{ valid_until }} {{ business }} {{ phone }} {{ email }}
Statement	{{ customer }} {{ number }} {{ period_from }} {{ period_to }} {{ balance }} {{ business }} {{ phone }} {{ email }}
Service report, certificate	{{ customer }} {{ address }} {{ technician }} {{ date }} {{ number }} {{ system }} {{ business }} {{ phone }} {{ email }}
Email	{{ subject }} {{ business }} {{ phone }} {{ email }}

{{ number }} is the invoice, quote, customer or report number, depending on the document. The Insert buttons in the editor add them for you. A field that does not exist is left as you typed it.

CSS limits

Custom CSS is cleaned when you save. What is kept:

• Rules for the elements and classes the documents use: body, h1, h2, table, th, td, p, .letterhead, .lead, .total, .note, .meta and a few more.
• Colours, fonts and sizes, spacing, borders, widths, alignment, and page breaks.

What is removed: links and images (url()), @import and every other @ rule, scripts, var(), attr(), expressions, selectors on anything else, and values that are not plain CSS. After you save, the editor lists what was removed. CSS can be up to 4,000 characters and 60 rules.

PDFs never download anything, so a font or image from a web address cannot be used. Add your logo in Admin > Documents.

Edit as Twig

Twig is a small template language. Most people never need it. It lets you change one part of a document, or lay a page out your own way.

Choose Start from my blocks on the Twig tab. You get something like this:

{% extends "@document" %}

{% block content %}
    {{ part('addresses', {heading: 'Invoice'}, 'invoice') }}
    {{ part('line-items', {heading: 'Charges'}, 'invoice') }}
    {{ part('totals', {heading: 'Totals'}, 'invoice') }}
{% endblock %}

{% extends "@document" %} means your template sits on top of your theme's template. You only write what you change. Every other block stays as the theme made it.

Override one block

To change only the totals on an invoice, leave everything else out:

{% extends "@document" %}

{% block totals %}
    <h2>Amount due</h2>
    <p class="lead">{{ money(snapshot.invoice.total_cents) }} by {{ day(snapshot.invoice.due_on) }}</p>
{% endblock %}

To add to a block rather than replace it, use {{ parent() }}:

{% extends "@document" %}

{% block details %}
    <p class="lead"><strong>Deposit.</strong> This is taken off your final invoice.</p>
    {{ parent() }}
{% endblock %}

The blocks you can override:

Document	Blocks
Invoice	details, lines, totals, payment, footer_text, content
Quote	details, options, terms, accepted, content
Statement	details, activity, ageing, unpaid, payment, content
Service report	owner_summary, content
Certificate	content
Email	header_row, message_row, footer_row, extra_rows
All documents	title, style, banner, header, plugin_blocks

Values you can print

snapshot holds the document's data, for example snapshot.invoice.total_cents, snapshot.customer.display_name, snapshot.lines, snapshot.quote.terms, snapshot.statement.closing_balance_cents. words holds the merge fields: {{ words.customer }}. Use {{ money(cents) }} for dollars and {{ day(date) }} for dates. Everything you print is escaped.

What is allowed

Tags	if, for, block, extends (only "@document")
Filters	escape, e, upper, lower, capitalize, title, trim, length, default, join, nl2br, number_format, first, last, slice, abs, round
Functions	part, money, day, block, parent
Parts for part()	header, footer, addresses, line-items, totals, payment-details, open-items, signature, free-block, banner, style, email-header, email-footer

A loop can sit inside another loop, but not three deep. A template can be 20,000 characters.

Templates cannot include other files, read files, call methods, make web requests or run code. If you try, Rangefront refuses to save and shows the problem with its line number. Check tests it without saving.

If a template fails when a document is made, the document is made from your blocks instead, so a customer never gets a broken document.

Go back to blocks only removes your Twig and uses the block list again.

Questions

Can I use my own fonts? Choose a font in Admin > Branding. PDFs and emails use the font you chose there when your theme sets one; otherwise they use the usual document fonts.

Why did a document not change? It keeps the template it was made with. Make a new PDF, or send the invoice again.

Who can change templates? People with the template permission. Everyone else can still pin a template if they can edit the invoice or quote.