🔧 Variables & Helpers

Learn to use dynamic variables and Handlebars helpers to create powerful and flexible documents.

📦 Available Variables

👤 Customer Data

{{customer.name}}          // Full name
{{customer.email}}         // Email
{{customer.phone}}         // Phone
{{customer.document}}      // CPF/SSN
{{customer.birth_date}}    // Date of birth

📍 Address

{{customer.address.street}}      // Street/Avenue
{{customer.address.number}}      // Number
{{customer.address.complement}}  // Complement
{{customer.address.neighborhood}}// Neighborhood
{{customer.address.city}}        // City
{{customer.address.state}}       // State
{{customer.address.zip_code}}    // ZIP Code
{{customer.address.country}}     // Country

📅 System Data

{{date.current_date}}      // Current date (2026-02-24)
{{date.current_time}}      // Current time (14:30:00)
{{organization.name}}      // Organization name
{{user.name}}              // Name of user who generated

🎯 Custom Variables

Create specific variables for your template:

{{custom.variable_name}}   // Custom value

Example:

Contract Amount: $ {{custom.amount}}
Delivery Term: {{custom.term}} days
Discount: {{custom.discount}}%

🛠️ Handlebars Helpers

Helpers are functions that transform data. Use the syntax: {{helper value}}

🔤 Text Transformation

Uppercase

{{uppercase customer.name}}

Result: JOHN SMITH

Lowercase

{{lowercase customer.name}}

Result: john smith

Capitalize (first letter)

{{capitalize customer.name}}

Result: John smith

Title Case (all words)

{{titleCase customer.name}}

Result: John Smith

🔢 Numbers in Words (General)

Portuguese

{{formatInWordsPT custom.quantidade}}

Example: 250 → "duzentos e cinquenta"

English

{{formatInWordsEN custom.quantity}}

Example: 250 → "two hundred and fifty"

Spanish

{{formatInWordsES custom.cantidad}}

Example: 250 → "doscientos cincuenta"

🔢 Mathematical Operations

Apply mathematical operations to numeric variables. Accepts variables or literal numbers in any argument.

{{divide value divisor}}              // value ÷ divisor
{{multiply value factor}}              // value × factor
{{add value addend}}                   // value + addend
{{subtract value subtrahend}}          // value − subtrahend
{{sum v1 v2 v3}}                      // sum multiple values

Examples:

{{divide custom.totalValue 4}}                    // Divide by 4 (e.g. 1000 → 250)
{{divide custom.totalValue custom.numInstallments}}  // Divide variable by another variable
{{multiply custom.quantity 2}}                    // Multiply by 2
{{formatCurrencyBRL (divide custom.totalValue 4)}}   // Value ÷ 4 formatted in R$
{{sum custom.item1 custom.item2 custom.item3}}    // Sum multiple variables

💰 Currencies (Number + Currency Name)

💡 Tip

Currency helpers convert the number and add the currency name in words.

Brazilian Real (BRL)

{{formatInWordsBRL custom.valor}}

Example: 1350.50 → "one thousand three hundred fifty reais and fifty centavos"

US Dollar (USD)

{{formatInWordsUSD custom.value}}

Example: 1350.50 → "one thousand three hundred fifty dollars and fifty cents"

Euro (EUR)

{{formatInWordsEUR custom.value}}

Example: 1350.50 → "one thousand three hundred fifty euros and fifty cents"

Argentine Peso (ARS)

{{formatInWordsARS custom.valor}}

Example: 1350.50 → "mil trescientos cincuenta pesos argentinos"

Paraguayan Guarani (PYG)

{{formatInWordsPYG custom.monto}}

Example: 1350 → "mil trescientos cincuenta guaraníes"

⚠️ Warning

Monetary helpers include both the number AND the currency name. Don't add "reais", "dollars", etc. manually, as it will be duplicated.

💵 Currency Format (Symbol)

Formats numeric value with currency symbol. Use the country helper:

{{formatCurrencyBRL custom.valor}}     // R$ 1,350.50
{{formatCurrencyUSD custom.valor}}     // $1,350.50
{{formatCurrencyEUR custom.valor}}     // 1,350.50 €
{{formatCurrencyARS custom.valor}}     // $ 1,350.50

formatCurrency (no suffix) returns only the formatted number (1,350.50), without symbol.

📅 Dates

Full format (PT, EN, ES)

{{formatDatePT date.current_date}}     // 24 de fevereiro de 2026
{{formatDateEN date.current_date}}     // February 24, 2026
{{formatDateES date.current_date}}     // 24 de febrero de 2026

Short format

{{formatDateShortPT date.current_date}}  // 24/02/2026
{{formatDateShortEN date.current_date}}  // 02/24/2026
{{formatDateShortES date.current_date}}  // 24/02/2026

Day, month and year (separate, accepts GMT)

{{formatDay date.current_date}}        // 24
{{formatMonthPT date.current_date}}    // fevereiro
{{formatMonthEN date.current_date}}    // February
{{formatMonthES date.current_date}}    // febrero
{{formatYear date.current_date}}       // 2026

Date and time (accepts GMT, use "now" for current)

{{formatDateTimePT date.current_date}}           // 24/02/2026 às 14:30
{{formatDateTimePT "now" -3}}                    // Current date/time in GMT-3
{{formatDateTimeEN custom.date_time}}            // Feb 24, 2026 at 14:30
{{formatDateTimeES custom.date_time -4}}         // With GMT-4 offset

Time only (accepts GMT)

{{formatTime custom.time}}             // 14:30
{{formatTimeWithSeconds custom.time}}  // 14:30:00
{{formatTime "now" -3}}                // Current time in GMT-3

Using with custom fields

Due Date: {{formatDateEN custom.due_date}}

💡 Current date and time

Use "today" for current date and "now" for current date/time:

{{formatDateEN "today"}}
{{formatDateTimeEN "now" -3}}

🔗 Combining Helpers

You can combine multiple helpers using parentheses:

Uppercase + In Words

{{uppercase (formatInWordsUSD custom.value)}}

Result: "ONE THOUSAND THREE HUNDRED FIFTY DOLLARS AND FIFTY CENTS"

Date in Uppercase

{{uppercase (formatDateEN date.current_date)}}

Result: "FEBRUARY 24, 2026"

Title Case + Currency

{{titleCase (formatInWordsUSD custom.value)}}

Result: "One Thousand Three Hundred Fifty Dollars And Fifty Cents"

Math Operation + Formatting

{{formatCurrencyUSD (divide custom.totalValue 4)}}

Result: total value ÷ 4 formatted in $ (e.g. $250.00)

💡 Practical Examples

Service Agreement

<h1>SERVICE AGREEMENT</h1>

<p><strong>CLIENT:</strong> {{uppercase customer.name}}</p>
<p><strong>SSN:</strong> {{customer.document}}</p>
<p><strong>Address:</strong> {{customer.address.street}}, {{customer.address.number}} - {{customer.address.city}}/{{customer.address.state}}</p>

<h2>CONTRACT VALUE</h2>
<p>The total value of this contract is <strong>{{formatCurrencyUSD custom.value}}</strong> ({{formatInWordsUSD custom.value}}).</p>

<p>Signed on {{formatDateEN "today"}}.</p>

Multilingual Registration Form

<h2>Customer Information</h2>
<p><strong>Name:</strong> {{titleCase customer.name}}</p>
<p><strong>Email:</strong> {{lowercase customer.email}}</p>
<p><strong>Registration Date:</strong> {{formatDateEN date.current_date}}</p>

Financial Report

<h2>Financial Report</h2>

<table>
  <tr>
    <td>Principal Amount:</td>
    <td>{{formatInWordsUSD custom.principal_amount}}</td>
  </tr>
  <tr>
    <td>Installment Value (÷ {{custom.num_installments}}):</td>
    <td>{{formatCurrencyUSD (divide custom.principal_amount custom.num_installments)}}</td>
  </tr>
  <tr>
    <td>Issue Date:</td>
    <td>{{formatDateShortEN "today"}}</td>
  </tr>
</table>

🎯 Advanced Tips

1. Consistent Formatting

Always use the same helper for similar data types:

{{titleCase customer.name}}     // ✅ Consistent
{{uppercase customer.name}}     // ❌ Different from standard

2. Visual Context

Add context around variables:

SSN: {{customer.document}}                    // ✅ With context
{{customer.document}}                          // ❌ Without context

3. Default Values

For optional variables, consider using conditionals (see Conditionals):

{{#if custom.notes}}
  <p><strong>Notes:</strong> {{custom.notes}}</p>
{{/if}}

🎬 Next Step

Learn to use Conditionals to create even smarter and more dynamic documents!