Customising Documents and Emails

Tokens in a nutshell

A token is a placeholder that Sodium swaps for real data when it generates a document. You write it between double curly braces, and you don't have to memorise the names - the Insert Template Token picker lists every field you can use (client, contact, practice, key dates, and more) and drops the token in for you.

You'll use the same tokens everywhere you write client-facing content - your Document Templates, Content Blocks, and the emails you send from workflows.

Dear {{ PrimaryContact.FirstName }},

That much you can already discover in the app. What isn't obvious is that a token is more than a straight swap - you can reshape its value with filters, wrap content in conditions, and use a handful of special tokens (like your logo) that never appear in the picker. That is what the rest of this guide is about.

Fill in the blanks

If a token has no value - a contact with no first name, say - it renders as nothing, which can leave you with an awkward "Hi ,". The default filter supplies a fallback for exactly those cases. Add a pipe (|) after the token, then default: and the text to fall back to.

Hi {{ PrimaryContact.FirstName | default: "there" }},

This is the single most useful thing you can add to a template - it means a missing value never leaves a visible gap.

Change how text looks

Filters can also transform text. Chain as many as you like, left to right. The most common ones:

{{ Client.Name | upcase }}
{{ Proposal.RecipientFirstName | capitalize }}
{{ Business.PostalAddress | truncate: 40 }}

• upcase - makes everything UPPERCASE.
• downcase - makes everything lowercase.
• capitalize - capitalises the first letter.
• truncate: 40 - shortens long text to 40 characters and adds an ellipsis.

Format dates

Date tokens - year ends, VAT deadlines, today's date - look best when you control their format. Use the formatDate filter and pass the pattern you want in quotes.

Generated on {{ Today | formatDate: "dd MMMM yyyy" }}

The pattern is built from these pieces (they are case-sensitive):

Format money

The formatCurrency filter turns a number into neat pounds and pence, with a £ sign, thousands separators and two decimal places.

Monthly fee: {{ Proposal.MonthlyTotal | formatCurrency }}

If the value is missing it shows £0.00 rather than a blank, so a total is never left empty.

Show or hide content

Sometimes a paragraph should only appear when it's relevant - a VAT section for VAT-registered clients, say. Wrap it in {% if %} and {% endif %}. Everything between the two tags is included only when the condition is met.

{% if Business.Vat.Number != blank %}
Your VAT registration number is {{ Business.Vat.Number }}.
{% endif %}

You can add an {% else %} for the opposite case:

{% if Manager.DisplayName != blank %}
Your account manager is {{ Manager.DisplayName }}.
{% else %}
Please call the office and we'll point you to the right person.
{% endif %}

Add your logo and images

Your practice logo has its own special token. Just write {{Logo}} and Sodium drops in the logo image wherever you put it - a letterhead, an email header, or a proposal cover.

{{Logo}}

To control its size, pass a width (and optionally a height) in pixels through the width filter:

{{ Logo | width: 200 }}
{{ Logo | width: 200, height: 100 }}

For any other picture, upload it under Design & Templates → Images, then drop it into your template with the editor's image button. Sodium places the image for you - there's no image token to type by hand.

Add a button

For emails and interactive documents you can add a styled button with the [Button ...] token. It picks up your brand colours from the document's Design Theme automatically.

[Button text="Accept proposal", url="https://portal.example.com/accept", align="center", variant="primary"]

The options:

• text - the button label (required).
• url - where it links to. Optional if the template already has a link to use (for example, a portal action link).
• align - left, center or right (defaults to centre).
• variant - primary or secondary (defaults to primary).
• size - add size="sm" for a compact button.

Reuse content with content blocks

If you have wording you use again and again - a standard set of terms, a footer, a disclaimer - save it once as a Content Block and pull it into any template by its code with the contentBlock filter. Update the block once and every template that references it stays in step.

{{ "standard-terms" | contentBlock }}

Reference and gotchas

The filters covered in this guide, in one place:

And the special tokens:

• {{Logo}} - your practice logo (add | width: 200 to size it). Other images go in from the editor's image button.
• [Button text="…" url="…"] - a styled button.

Good to know

• Field names ignore capitalisation. {{ client.name }} and {{ Client.Name }} both work.
• Empty is not the same as missing. To show something only when a field is filled in, test != blank rather than relying on the token being "empty".
• Stick to what's here. Sodium supports the tokens, filters and tags in this guide. Filters you may have seen elsewhere online (Shopify's money, date and similar) aren't available - use formatCurrency and formatDate instead.