Design and Test Templates with the Word Add-in

This guide covers the essential workflows for designing robust, dynamic templates directly inside Microsoft Word. The Word Template Syntax guide should be used as a companion when creating templates.

Examples:

An example Word template can be downloaded here.
Example JSON can be found here.

The Authoring Workflow

Creating a template involves three main steps: Structure, Tagging, and Logic.

1. Structure Your Document

Before adding any dynamic tags, build the static layout of your document using standard Word features.

Tables: Create the headers for your invoices or reports
Styles: Apply your headers, formatting, and standard font styles. The generated document will retain all these stylistic choices
Placeholders: It is often helpful to type dummy text (e.g., [Client Name]) where you intend to put dynamic data later

2. Inserting Data Tags

After creating the basic structure of the document, replace your placeholder text with real Build a Doc template syntax that matches your JSON Data structure.

Example JSON Data

[
  {
    "Name": "Invoice",
    "Data": {
      "Customer": {
        "Name": "John Smith"
      },
      "Items": [
        {
          "Description": "Product A",
          "Price": 10.0
        },
        {
          "Description": "Product B",
          "Price": 15.5
        }
      ]
    }
  }
]

Basic Fields

To display a simple field, use the path to that data:

Example: To show the Customer Name (John Smith), type: <<[Invoice.Customer.Name]>>

3. Applying Logic and Formatting

Once your basic tags are in place, use the Add-in’s syntax to add dynamic content to your document.

Formatting Dates and Numbers

Raw data often comes in computer-friendly formats (e.g., 2023-11-30T00:00:00). You can format this directly in the template.

Dates: <<[InvoiceDate]:"dd MMM yyyy">> becomes 30 Nov 2023
Currency: Append symbols manually in the Word text: £<<[Amount]>>

Conditional Text

Use if statements to show or hide sections based on data.

Scenario: Only show “Shipping Address” if it is different from “Billing Address”

<<if [ShippingAddress != BillingAddress]>>
Ship To: <<[ShippingAddress]>>
<</if>>

Dynamic Tables (Loops)

To populate a table with rows from a list:

Create a Table with a single header row and a single data row
Start the Loop: Place <<foreach [item in items]>> in the first cell of the data row
End the Loop: Place <</foreach>> in the last cell of the data row
Fill Cells: Use <<[item.description]>>, <<[item.price]>>, etc., in the columns between the start and end tags

Validating Your Template

As you author, frequent validation saves time.

Use the Preview: The most effective validation is generating a preview
Check Error Logs: Look for “Unexpected end of tag” (usually a missing >>) or “Invalid path” (typos in JSON keys)

Best Practices

Keep Logic Simple: If a calculation is extremely complex, consider performing it in your data source before sending it to the template
Table Layouts: Avoid split cells or complex merged cells in the repeat row, as this can sometimes confuse the loop engine
Variable Scope: Variables declared inside a loop reset or behave differently depending on their placement. Declare global variables (like grand totals) before the loop starts