Formulas

Overview

Formulas allow you to execute JavaScript expressions within your templates to perform calculations, transformations, and complex logic.

Formula Syntax

Formulas are enclosed in {{% %}} and must start with return:

{{% return expression %}}

All formula expressions must begin with the return keyword.

Basic Calculations

Perform arithmetic operations on your data:

{{% return value1 + value2 %}}
{{% return amount * 1.1 %}}
{{% return total - discount %}}

Example: Simple Calculation

{
  "$class": "[email protected]",
  "name": "John Doe"
}

Financial Calculations

Formulas are perfect for computing taxes, totals, and other financial values:

VAT and Total Calculation

{
  "$class": "[email protected]",
  "amount": 250.00,
  "currency": "USD",
  "vatPercent": 10
}

String Operations

Manipulate strings using JavaScript string methods:

Length
Uppercase
Lowercase
Substring
Replace

{{% return text.length %}}

{{% return name.toUpperCase() %}}

{{% return email.toLowerCase() %}}

{{% return description.substring(0, 100) %}}

{{% return text.replace('old', 'new') %}}

Date and Time

The `now` Variable

Access the current date and time using the implicit now variable:

{{% return now.toISOString() %}}

Today is **{{% return now.toISOString() %}}**.

Date Methods

ISO String
Date String
Year
Month

{{% return now.toISOString() %}}

Output: 2024-06-15T10:30:00.000Z

{{% return now.toDateString() %}}

Output: Sat Jun 15 2024

{{% return now.getFullYear() %}}

Output: 2024

{{% return now.getMonth() + 1 %}}

Output: 6 (January is 0)

Number Formatting

Use JavaScript number methods for precise formatting:

Common Number Methods

Fixed Decimals
Precision
Exponential

{{% return value.toFixed(2) %}}

Formats to 2 decimal places: 123.46

{{% return value.toPrecision(4) %}}

Formats to 4 significant digits: 123.5

{{% return value.toExponential(2) %}}

Scientific notation: 1.23e+2

Array Operations

Work with arrays using JavaScript array methods:

Length
Join
First Item
Last Item

{{% return items.length %}}

{{% return items.join(', ') %}}

{{% return items[0] %}}

{{% return items[items.length - 1] %}}

Conditional Expressions

Use ternary operators for inline conditionals:

{{% return condition ? 'value if true' : 'value if false' %}}

Examples

Status Display
Discount Badge
Quantity Label

Status: {{% return active ? '✓ Active' : '✗ Inactive' %}}

{{% return discount > 0 ? '🎉 Discount Applied!' : '' %}}

{{% return quantity === 1 ? 'item' : 'items' %}}

Complex Calculations

Combine multiple operations for sophisticated logic:

Multi-tier Discount Calculation

{{% return amount > 1000 ? amount * 0.85 : amount > 500 ? amount * 0.90 : amount * 0.95 %}}

Percentage Calculation

Progress: {{% return Math.round((completed / total) * 100) %}}}%

Duration Calculation

{{% return Math.floor(durationInMonths / 12) %}}} years and {{% return durationInMonths % 12 %}}} months

Mathematical Operations

Use the Math object for advanced calculations:

Rounding
Min/Max
Power/Root
Absolute

{{% return Math.round(value) %}}
{{% return Math.floor(value) %}}
{{% return Math.ceil(value) %}}

{{% return Math.max(a, b, c) %}}
{{% return Math.min(a, b, c) %}}

{{% return Math.pow(base, exponent) %}}
{{% return Math.sqrt(value) %}}

{{% return Math.abs(value) %}}

Best Practices

Always use return keyword

Formula expressions must start with return:

Good: {{% return amount * 1.1 %}}
Bad: {{% amount * 1.1 %}}

Format calculated numbers

Use .toFixed() for consistent decimal places:

{{% return (price * quantity).toFixed(2) %}}

Handle undefined values

Check for undefined before calculations:

{{% return discount ? (amount * discount / 100).toFixed(2) : '0.00' %}}

Keep formulas readable

Break complex calculations into multiple formulas:

Good:
- Subtotal: {{% return amount.toFixed(2) %}}
- VAT: {{% return (amount * 0.1).toFixed(2) %}}
- Total: {{% return (amount * 1.1).toFixed(2) %}}

Avoid:
- Total: {{% return (amount + (amount * vatRate / 100) + (amount * serviceFee / 100) - discount).toFixed(2) %}}

Division by zeroAlways check for zero before division:

{{% return total > 0 ? (completed / total * 100).toFixed(1) : 0 %}}%

Reuse variable formattingFor simple variable output, use the as formatter instead of formulas:

Preferred: {{amount as "0,0.00"}}
Also works: {{% return amount.toFixed(2) %}}

Variables

Learn about variable syntax and formatting

Conditionals

Use formulas in conditional expressions

Lists

Apply formulas within list iterations

TemplateMark Syntax

Sample Templates

API Integration

Overview

Formula Syntax

Basic Calculations

Example: Simple Calculation

Financial Calculations

VAT and Total Calculation

String Operations

Date and Time

The `now` Variable

Date Methods

Number Formatting

Common Number Methods

Array Operations

Conditional Expressions

Examples

Complex Calculations

Multi-tier Discount Calculation

Percentage Calculation

Duration Calculation

Mathematical Operations

Best Practices

Variables

Conditionals

Lists

Build docs developers (and LLMs) love

TemplateMark Syntax

Sample Templates

API Integration

​Overview

​Formula Syntax

​Basic Calculations

​Example: Simple Calculation

​Financial Calculations

​VAT and Total Calculation

​String Operations

​Date and Time

​The now Variable

​Date Methods

​Number Formatting

​Common Number Methods

​Array Operations

​Conditional Expressions

​Examples

​Complex Calculations

​Multi-tier Discount Calculation

​Percentage Calculation

​Duration Calculation

​Mathematical Operations

​Best Practices

​Related Topics

Variables

Conditionals

Lists

Build docs developers (and LLMs) love

Overview

Formula Syntax

Basic Calculations

Example: Simple Calculation

Financial Calculations

VAT and Total Calculation

String Operations

Date and Time

The `now` Variable

Date Methods

Number Formatting

Common Number Methods

Array Operations

Conditional Expressions

Examples

Complex Calculations

Multi-tier Discount Calculation

Percentage Calculation

Duration Calculation

Mathematical Operations

Best Practices

Related Topics