Introducing Dynamic Loops for DOCX / Word Templates
We are excited to announce a powerful new feature for our DOCX generation engine: Dynamic Loops. This feature allows you to iterate over lists of data—such as invoice items, product lists, or team members—directly within your Word document templates.
Why Loops?
Until now, replacing simple placeholders like {{ name }} was easy. But what if you needed to
generate a table with an unknown number of rows? Or a list of items that changes for every document?
With Dynamic Loops, you can now define a section of your document to repeat for each item in a list. This is perfect for:
- Invoices: Listing line items, quantities, and prices.
- Reports: Displaying lists of transactions or activity logs.
- Directories: Generating profiles for multiple employees or contacts.
The Syntax
We've designed the syntax to be simple, robust, and familiar. To create a loop, you wrap the content you want to repeat with a Start Marker and an End Marker.
- Start Loop:
{> variableName }} - End Loop:
{< variableName }}
Everything between these two markers will be duplicated for every item in your data list.
Example: Creating an Invoice
Imagine you have a list of products you want to include in an invoice.
1. Prepare Your Data
Your data structure should include an array of items. For example:
{
"invoice_number": "INV-2024-001",
"customer": "Acme Corp",
"products": [
{ "name": "Widget A", "qty": 2, "price": "$10.00" },
{ "name": "Widget B", "qty": 1, "price": "$25.00" },
{ "name": "Service Fee", "qty": 1, "price": "$5.00" }
],
"total": "$50.00"
}2. Design Your Template
In your Word document, you can set up a table or a list. Here is how you apply the loop:
Invoice #{{ invoice_number }}
Customer: {{ customer }}
| Item | Quantity | Price |
|---|---|---|
{> products }}{{ name }} |
{{ qty }} |
{{ price }}{< products }} |
(Note: In a Word table, you typically place the Start Marker in the first cell of the row and the End Marker in the last cell. The engine ensures the entire row repeats.)
3. The Result
When the document is generated, the engine iterates through the products array. For each
product, it creates a new row with the specific name, qty, and price.
| Item | Quantity | Price |
|---|---|---|
| Widget A | 2 | $10.00 |
| Widget B | 1 | $25.00 |
| Service Fee | 1 | $5.00 |
Advanced Reliability
One of the biggest challenges with Word templates is that Word often splits text into multiple XML tags
(formatting runs) behind the scenes, especially if you edit the text frequently or spell-check runs. Use of
distinct start ({>) and end ({<) tags makes our engine incredibly robust.
Our parser can identify your loop markers even if:
- Word inserts hidden formatting tags in the middle of your variable name.
- There are extra spaces or non-breaking spaces.
- You use mixed formatting.
Getting Started
This feature is available immediately in the latest version of the API. Simply upload a template with the new loop syntax and pass an array of data in your JSON payload.
Happy generating!