The syntax of docxtemplater tags is inspired by the language agnostic Mustache specification.
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{%src_url}
will add an image for the "src_url" data part.With this template (input.docx):
And given the following data (data.json):
{
name: "John";
}
docxtemplater will produce (output.docx):
Conditions start with a pound and end with a slash. That is {#hasKitty}
starts a condition and {/hasKitty}
ends it.
and this data:
{
"hasKitty": true,
"kitty": "Minie"
"hasDog": false,
"dog": null
}
renders the following:
For a more detailled explanation about Conditions, have a look at Sections
You can also have "else" blocks with Inverted Sections
In docxtemplater, conditions and loops use the same syntax called Sections
The following template:
Given the following data:
{
"products": [
{ name: "Windows", price: 100 },
{ name: "Mac OSX", price: 200 },
{ name: "Ubuntu", price: 0 }
]
}
will render :
To loop over an array containing primitive data (eg string):
{
"products": [
"Windows",
"Mac OSX",
"Ubuntu"
]
}
Will result in:
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
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 €]
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 |
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:
Data:
{
"repo": []
}
Output:
New lines are kept inside sections, so the template:
Data:
{
"repo": [
{name: "John"},
{name: "Jane"},
]
}
Will actually render
(where NL represents an emptyline)
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 });
An other 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:
It is possible to insert raw (unescaped) XML, for example to render a complex table, an equation, …
With the rawXML
syntax the whole current paragraph (w:p
) is replaced by the XML passed in the value.
with this data:
doc.render({
rawXml: `
<w:p>
<w:pPr>
<w:rPr>
<w:color w:val="FF0000"/>
</w:rPr>
</w:pPr>
<w:r>
<w:rPr>
<w:color w:val="FF0000"/>
</w:rPr>
<w:t>
My custom
</w:t>
</w:r>
<w:r>
<w:rPr>
<w:color w:val="00FF00"/>
</w:rPr>
<w:t>
XML
</w:t>
</w:r>
</w:p>
`,
});
This will loop over the first parent <w:p>
tag
If you want to insert HTML styled input, you can also use the docxtemplater html module
const doc = new Docxtemplater(zip);
doc.render({
userGreeting: (scope) => {
return "How is it going, " + scope.user + " ?";
},
users: [
{
name: "John",
},
{
name: "Mary",
},
],
});
with the following template :
will render :
It will call the function userGreeting twice (one for the user "John", and for the user "Mary"), with the current scope as first argument, and the scopeManager as the second argument.
Set Delimiter tags start and end with an equal sign and change the tag delimiters from { and } to custom strings.
Consider the following contrived example:
Here we have a list with three items. The first item uses the default tag style, the second uses erb style as defined by the Set Delimiter tag, and the third returns to the default style after yet another Set Delimiter declaration.
Custom delimiters may not contain whitespace or the equals sign.
It is also possible to change the delimiters globally by using docxtemplater options object.
When using sections, docxtemplater will try to find on what element to loop over by itself:
If between the two tags {#tag}______{/tag}
<w:tc>
or <a:tc>
) , that means that your loop is inside a table, and it will expand the loop over the table row (<w:tr>
or <a:tr>
).With the Dash syntax you can specify the tag you want to loop on: For example, if you want to loop on paragraphs (w:p
), so that each item in the loop creates a new paragraph, you can write: