Tokens

What are Tokens?

Tokens are visual representations of your data that you can drag and drop directly into your template. They replace the previous Handlebars syntax (e.g., {{ variable_name }}) with intuitive, interactive elements that display your data dynamically when the document is generated.

Old token panel (left) vs new token panel. Notice the text based (handlebars) tokens in the old version vs the new visual tokens.

How Tokens Differ from Handlebars Syntax

Unlike Handlebars syntax which required you to manually type code with specific formatting, tokens provide a visual approach to inserting dynamic content. This offers several advantages:

• No syntax to remember: You don't need to recall specific formatting rules or worry about typos.

• Immediate visual feedback: See exactly what you're adding and where.

• Context awareness: Tokens understand their position in your document structure.

• Built-in formatting options: Customize how your data displays without additional code.

• Error prevention: Eliminates common syntax errors like mismatched brackets or incorrect variable names.

Token Types

Documint supports various data types, each with its own specialized token:

• Text: For names, descriptions, addresses, and other string data.

• Number: For quantities, prices, percentages, and other numerical values.

• Date: For timestamps, due dates, and other calendar information.

• Boolean: For yes/no, true/false values.

• Object: For structured data containing multiple fields.

• Array: For lists of items (like invoice line items or attendees).

Each token type has specific formatting options and behaviors tailored to its data type.

The field editor provides some useful data type for your fields.

How to Insert Tokens

1. Define your fields in the Fields Editor or connect to your Airtable table.

1. Open the Tokens panel in the Template Designer.

1. Find the desired token in the list.

2. Drag and drop it into your template at the desired location.

1. Customize any formatting options if needed.

Smart Context Awareness

One of the most powerful features of tokens is their ability to understand their context within your document structure.

Tokens Inside Repeated Sections

When you place a token inside a repeated section (like an invoice line items table), it automatically displays the correct value for each iteration. For example, in an invoice line items table, placing the "amount" token will display the specific amount for each line item.

Tokens Outside Repeated Sections

When you place a token that belongs to an array or list outside of a repeated section, Documint intelligently offers options for how to display that data:

• First: Display only the first item's value.

• Sum: Calculate and display the total (for number tokens).

• Average: Calculate and display the average (for number tokens).

• Median: Calculate and display the median value (for number tokens).

• Specific: Select a specific item from the array by index.

This allows you to create summaries, totals, and highlights without writing complex formulas.

Formatting Options

Each token type offers specific formatting options that you can customize after placing the token in your template:

Text Formatting

• Plain vs markdown formatting.

• Default value.

• Display rules.

Number Formatting

• Decimal places and thousands seperators.

• Currency and percentage formatting.

• Default value.

• Display rules.

Date Formatting

• Date patterns (MM/DD/YYYY, DD/MM/YYYY, etc.).

• Timezone.

• Display rules.

Token Validation

The Template Designer automatically validates your tokens to ensure they'll work correctly by:

• Showing warning indicators for potential issues.

• Displaying error messages for invalid configurations.

• Suggesting fixes for common problems.

This proactive validation helps prevent errors before you generate documents.

Example of Tokens Used in an Invoice

Invoice Example

• Invoice number

• Customer address

• Customer name

• Customer number

• Line items containing description and price, quantity, and amount (formatted as $0,000.00)

• Subtotal (formatted as $0,000.00)

• Sales tax (formatted as $0,000.00)

• Sales total (formatted as $0,000.00)

• Date (formatted as MM/DD/YYYY)

Invoice example using the tokens.

Best Practices for Using Tokens

• Organize related tokens: Group similar fields together in your Fields Editor.

• Order tokens in the order they appear: Try to place tokens in the order they appear in the template. Prioritze this practive over keeping related tokens together as mentioned above.

• Use descriptive names: Choose clear, meaningful names for your fields.

• Consider token formatting early: Think about how data should be displayed when designing your template.

• Test with sample data: Use the preview feature to ensure tokens display as expected.

• Use conditional logic: Combine tokens with conditions for more dynamic templates.

Some of the best practices only apply if you are building out the fields yourself; however, if you are importing the filed structure from a data source you won't be able to control how they are ordered.