Expressions and Formatting

An expression placeholder evaluates a JavaScript expression inline and inserts the result. It is written with an equals sign after the opening braces:

{{=price * quantity}}

The variable names inside the expression — price, quantity — are the machine names of fields on the entity type the template is attached to. Expression placeholders work in all three template formats (DOCX, XLSX, PPTX).

Expression placeholders are evaluated by the template engine during document generation. They are distinct from expression fields, which are computed and stored on the entity type itself and arrive in the template already calculated — a simple {{total}} is enough for those.

When to use expressions

Use an expression placeholder when you need to:

  • calculate a value that is not stored as a field — for example, a line total from unit price and quantity,

  • format a number or date in a specific way — for example, displaying a price as 1,250.00 or a date as 2025-03-15,

  • combine or transform field values — for example, concatenating a first and last name.

Simple field insertion ({{fieldName}}) is enough when the value should appear as stored. Expressions are for cases where the value needs computation or custom formatting.

Expression syntax

The expression between {{= and }} is evaluated as JavaScript. All fields from the current context are available as variables — each variable name is the machine name of a field on the entity type.

The examples below assume the template is attached to an entity type whose fields include price (Decimal), quantity (Integer), and invoiceNumber (String) — all machine names:

Expression Result (given price = 50, quantity = 3)

{{=price * quantity}}

150

{{=price > 100 ? 'Premium' : 'Standard'}}

Standard

{{='Invoice #' + invoiceNumber}}

Invoice #2024-0042

Standard JavaScript operators and built-in functions are available: arithmetic (`, `-`, `*`, `/`, `%`), comparison (`>`, `<`, `===`), ternary (`? :`), string concatenation (`), and Math functions (Math.round, Math.max, and so on).

What an expression can reach

An expression computes a value only from the fields in its context. If an expression contains a syntax error, references an undefined variable, or runs too long, it resolves to an empty string. The troubleshooting page covers how to diagnose this.

Formatting helpers

Three formatting functions are available inside expression placeholders through the fmt object.

fmt.number(value, pattern)

Formats a number using a pattern string. The pattern uses these tokens:

Pattern token Meaning

0

A mandatory digit — always printed, even if zero.

#

An optional digit — printed only if the number has a digit in that position.

,

Grouping separator (thousands).

.

Decimal separator.

Examples (using the field machine names price, rate, quantity, and ratio from the current entity type):

Expression Input value Output

{{=fmt.number(price, '#,##0.00')}}

1250

1,250.00

{{=fmt.number(rate, '0.0##')}}

3.5

3.500

{{=fmt.number(quantity, '#,##0')}}

48000

48,000

{{=fmt.number(ratio, '0.00')}}

0.753

0.75

fmt.date(value, pattern)

Formats a date using a pattern string. The pattern uses these tokens:

Pattern token Meaning

yyyy

Four-digit year.

yy

Two-digit year.

MM

Two-digit month (01—​12).

dd

Two-digit day (01—​31).

HH

Two-digit hour, 24-hour clock (00—​23).

mm

Two-digit minute (00—​59).

ss

Two-digit second (00—​59).

Examples (where startDate, createdAt, and signedOn are Date/time field machine names on the entity type):

Expression Output

{{=fmt.date(startDate, 'dd.MM.yyyy')}}

15.03.2025

{{=fmt.date(startDate, 'yyyy-MM-dd')}}

2025-03-15

{{=fmt.date(createdAt, 'dd.MM.yyyy HH:mm')}}

15.03.2025 14:30

{{=fmt.date(signedOn, 'MM/dd/yyyy')}}

03/15/2025

fmt.currency(value)

A shortcut for fmt.number(value, '#,##0.00'). It formats a number with two decimal places and a thousands grouping separator.

{{=fmt.currency(totalCost)}}

Here totalCost is a Decimal field’s machine name on the entity type. If its value is 48250, the output is 48,250.00.

This helper does not add a currency symbol. If a symbol is needed, concatenate it in the expression:

{{='$' + fmt.currency(totalCost)}}

Auto-formatting

When a value is inserted through a simple placeholder ({{fieldName}}), the system applies automatic formatting to certain data types:

  • Dates are formatted as dd.MM.yyyy — for example, 15.03.2025.

  • Decimal numbers are formatted to two decimal places — for example, 1234.50.

Auto-formatting applies only to simple placeholders. Expression placeholders return the raw result of the JavaScript evaluation — use fmt.number or fmt.date when you need formatted output from an expression.

Expressions in XLSX formulas

In XLSX templates, expression placeholders and Excel formulas serve different purposes:

  • An expression placeholder ({{=price * quantity}}) is evaluated by the template engine during generation and produces a static value in the cell.

  • An Excel formula (=A2*B2) is preserved in the output file and recalculated by Excel when the file is opened.

If you need a cell to contain a live Excel formula in the output, write it as a regular Excel formula in the template cell — not as an expression placeholder.

To build a formula whose range depends on the data, start the cell with the formula prefix {{=}} and write the formula after it — the remainder is still a template, which is the entire point of the prefix. Note the closing braces: {{=}}SUM(D2:{{lastRow}}) is a formula, while {{=price * quantity}} is a JavaScript expression. A formula with a fixed range needs no prefix at all — type it into the cell as =SUM(D2:D100) and the engine leaves it alone.

For the formula prefix and the rest of the XLSX-specific behavior — server-side evaluation, DATEDIF, typed cell values — see Excel templates.

Related pages