Syntax Rules & Backend Fields for Coding Your MS Word Templates
This article describes the syntax rules and backend variables/fields that are used in DraftMate for setting up your contract templates on MS Word.
List of backend fields/variables used in the template
- ud_contractor_entity$name – Name of Creator Entity
- ud_subscriber$name – Name of Counterparty Entity
- ud_contractor$address$inline – Address of Creator Entity
- ud_subscriber$address$inline – Address of Counterparty Entity
Here, word contractor & subscriber can be replaced by the labels we use in the template for the contracting parties.
Backend fields for signatures
{#ud_contractor_sign_fields} – Starting loop of signature block
By: {input_fields.signature} – Signature Fields
Print Name: {input_fields.name} – Signatory’s Name Field
Title: {input_fields.title} – Signatory’s Title Field
Date: {input_fields.date_signed} – Signatory’s Date of Signing Field
{/ud_customer_sign_fields} – Ending loop of signature block
{#ud_subscriber_sign_fields} – Starting loop of signature block
By: {input_fields.signature} – Signature Fields
Print Name: {input_fields.name} – Signatory’s Name Field
Title: {input_fields.title} – Signatory’s Title Field
Date: {input_fields.date_signed} – Signatory’s Date of Signing Field
{/ud_subscriber_sign_fields} – Ending loop of signature block
Here, word contractor & subscriber can be replaced by the labels we use in the template for the contracting parties.
Types of tags/Syntax Rules
Normal tags start with an alphabetical character, and other types of tags start with special prefixes, for example:
- {#loop} and {/loop} to start and close a tag for the data part "loop"
- {@input} to insert raw XML data
- when using the image-module {%src_url} will add an image for the "src_url" data part.
Introduction
With this template (input.docx):
Hello {name} !
And given the following data (data.json):
{
name: "John";
}
docxtemplater will produce (output.docx):
Hello John !
Conditions
Conditions start with a pound and end with a slash. That is {#hasKitty} starts a condition and {/hasKitty} ends it.
{#hasKitty}Cat’s name: {kitty}{/hasKitty}
{#hasDog}Dog’s name: {dog}{/hasDog}
and this data:
{
"hasKitty": true,
"kitty": "Minie"
"hasDog": false,
"dog": null
}
renders the following:
Cat’s name: Minie
You can also have "else" blocks with Inverted Sections
Loops
In docxtemplater, conditions and loops use the same syntax called Sections
The following template:
{#products}
{name}, {price} €
{/products}
Given the following data:
{
"products": [
{ name: "Windows", price: 100 },
{ name: "Mac OSX", price: 200 },
{ name: "Ubuntu", price: 0 }
]
}
will render :
Windows, 100 €
Mac OSX, 200 €
Ubuntu, 0€
To loop over an array containing primitive data (eg string):
{
"products": [
"Windows",
"Mac OSX",
"Ubuntu"
]
}
{#products} {.} {/products}
Will result in:
Windows Mac OSX Ubuntu
Sections
A section begins with a pound and ends with a slash. That is {#person} begins a "person" section while {/person} ends it.
The section behaves in the following way:
Type of the value | the section is shown | scope |
falsy or empty array | never | NA |
non empty array | for each element of array | element of array |
object | once | the object |
other truthy value | once | unchanged |
This table shows for each type of value, what is the condition for the section to be changed and what is the scope of that section.
If the value is of type boolean, the section is shown once if the value is true, and the scope of the section is unchanged.
If we have the section
{#hasProduct}
{price} €
{/hasProduct}
Given the following data:
{
"hasProduct": true,
"price": 10
}
Since hasProduct is a boolean, the section is shown once if hasProduct is true. Since the scope is unchanged, the subsection {price} € will render as [10 €]
Creating multiple table rows
It is possible to create multiple rows in a table
Name | Age | Phone Number |
{#users}{name} | {age} | {phone}{/} |
{
users: [
{ name: "John", age: 22, phone: "+33653454343" },
{ name: "Mary", age: 25, phone: "+33666666666" },
],
}
Will render the following:
Name | Age | Phone Number |
John | 22 | +33653454343 |
Mary | 25 | +33666666666 |
Inverted Sections
An inverted section begins with a caret (hat) and ends with a slash. That is {^person} begins a "person" inverted section while {/person} ends it.
While sections can be used to render text one or more times based on the value of the key, inverted sections may render text once based on the inverse value of the key. That is, they will be rendered if the key doesn't exist, is false, or is an empty list. The scope of an inverted section is unchanged.
Template:
{#repo}
Repo name : {name}
{/repo}
{^repo}
No repos :(
{/repo}
Data:
{
"repo": []
}
Output:
No repos :(
Sections and newlines
New lines are kept inside sections, so the template:
{#repo}
{name}>
{/repo}
{^repo}
No repos :(
{/repo}
Data:
{
"repo": [
{name: "John"},
{name: "Jane"},
]
}
Will actually render
NL
John
NL
NL
Jane
NL
(where NL represents an empty line)
The easiest to make this work is to enable the paragraphLoop option, like this :
// Now, all sections in the form of:
// {#section}
// something
// {/section}
// will keep just the inner paragraphs, and drop the newlines of the outer section
const doc = new Docxtemplater(zip, { paragraphLoop: true });
Another less recommended way if you don't want to set this option, is to remove the new lines after the start of the section and before the end of the section.
For our example, that would be:
{#repo} {name}
{/repo} {^repo} No repos :( {/repo}