The angular-parser makes creating complex templates easier. It allows for example:
To access the nested name property in the following data:
doc.render({
user: {
name: "John",
},
});
You can also use +
, -
, *
, /
, >
, <
, ==
, !=
, <=
, >=
operators.
First install angular-expressions
which is required to make the parser work :
npm install --save angular-expressions
Then use following code :
const expressionParser = require("docxtemplater/expressions.js");
const doc = new Docxtemplater(zip, { parser: expressionParser });
doc.render(/* data */);
If running in IE 11 or if you get the error Proxy is not defined
, you can use the following parser instead :
const expressionParser = require("docxtemplater/expressions-ie11.js");
const doc = new Docxtemplater(zip, { parser: expressionParser });
doc.render(/* data */);
This require call works only with docxtemplater 3.32.3. If you have to use an older version of docxtemplater, copy this code
With the angular expression option set, you can also use conditions:
The first conditional will render the section only if there are 2 users or more.
The second conditional will render the section only if the first user has the name "John".
The angular parser handles the following operators :
a ? b : c
a == 1
, a != 1
a > 1
, a < 1
, a >= 1
, a <= 1
a && b
a || b
a + b
a - b
a * b
a % b
a / b
a = 1
(a && b) || c
12e3
=> returns 12000For example, it is possible to write the following template:
With filters, it is possible to write the following template to have the resulting string be uppercased:
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.upper = function (input) {
// Make sure that if your input is undefined, your
// output will be undefined as well and will not
// throw an error
if (!input) {
return input;
}
return input.toUpperCase();
};
new Docxtemplater(zip, { parser: expressionParser });
More complex filters are possible, for example, if you would like to list the names of all active users. If your data is the following:
doc.render({
users: [
{
name: "John",
age: 15,
},
{
name: "Mary",
age: 26,
},
],
});
You could show the list of users that are older than 18, by writing the following code:
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.olderThan = function (users, minAge) {
// Make sure that if your input is undefined, your
// output will be undefined as well and will not
// throw an error
if (!users) {
return users;
}
return users.filter(function (user) {
return user.age >= minAge;
});
};
new Docxtemplater(zip, { parser: expressionParser });
And in your template,
There are some interesting usecases for filters
You can write some generic data filters using angular expressions inside the filter itself.
doc.render({
users: [
{
name: "John",
age: 10,
},
{
name: "Mary",
age: 20,
},
],
});
The argument inside the where filter can be any other angular expression, with ||, &&, etc
The code for this filter is extremely terse, and gives a lot of possibilities:
const expressionParser = require("docxtemplater/expressions.js");
const angularExpressions = require("angular-expressions");
expressionParser.filters.where = function (input, query) {
return input.filter(function (item) {
return angularExpressions.compile(query)(item);
});
};
new Docxtemplater(zip, { parser: expressionParser });
If your data is the following:
{
"items": [
{
"name": "Acme Computer",
"price": 1000
},
{
"name": "USB storage",
"price": 15
},
{
"name": "Mouse & Keyboard",
"price": 150
}
]
}
You might want to sort the items by price (ascending).
You could do that again with a filter, like this:
The code for this filter is:
const { sortBy } = require("lodash");
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.sortBy = function (input, ...fields) {
// In our example fields is ["price"]
// Make sure that if your input is undefined, your
// output will be undefined as well and will not
// throw an error
if (!input) {
return input;
}
return sortBy(input, fields);
};
It is possible to have multilevel loops (also called nested loops), if your data is the following :
{
"companies": [
{
"name": "EvilCorp",
"users": [
{
"firstName": "John"
},
{
"firstName": "Mary"
}
]
},
{
"name": "HeavenCorp",
"users": [
{
"firstName": "Jack"
},
{
"firstName": "Bonnie"
}
]
}
]
}
You can loop on companies.users directly using following tag and filter :
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.loop = function (input, ...keys) {
const result = input.reduce(function (result, item) {
(item[keys[0]] || []).forEach(function (subitem) {
result.push({ ...item, ...subitem });
});
return result;
}, []);
if (keys.length === 1) {
return result;
}
keys.shift();
return expressionParser.filters.loop(result, ...keys);
};
With this code, you can also have more nesting if needed :
{#companies | loop:"users":"tasks"}{/}
If your data is the following:
{
"items": [
{
"name": "Acme Computer",
"price": 1000
},
{
"name": "Mouse & Keyboard",
"price": 150
}
]
}
And you would like to show the total price, you can write in your template:
The sumby
is a filter that you can write like this:
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.sumby = function (input, field) {
// In our example field is the string "price"
// Make sure that if your input is undefined, your
// output will be undefined as well and will not
// throw an error
if (!input) {
return input;
}
return input.reduce(function (sum, object) {
return sum + object[field];
}, 0);
};
This example is to format numbers in the format: "150.00" (2 digits of precision) If your data is the following:
{
"items": [
{
"name": "Acme Computer",
"price": 1000
},
{
"name": "Mouse & Keyboard",
"price": 150
}
]
}
And you would like to show the price with two digits of precision, you can write in your template:
The toFixed
is an angular filter that you can write like this:
const expressionParser = require("docxtemplater/expressions.js");
expressionParser.filters.toFixed = function (input, precision) {
// In our example precision is the integer 2
// Make sure that if your input is undefined, your
// output will be undefined as well and will not
// throw an error
if (!input) {
return input;
}
return input.toFixed(precision);
};
With the angular expression option, it is possible to assign a value to a variable directly from your template.
For example, in your template, write:
This will show in your output :
To drop the new line, use a raw tag instead, starting with a @ :
Output :
One might need to have a condition on the $index when inside a loop.
For example, if you have two arrays of the same length and you want to loop over both of them at the same time:
doc.render({
names: ["John", "Mary"],
ages: [15, 26],
});
It is possible to preprocess or postprocess :
{name: "John"}
)For example, you could have some specific behavior applied for all HTML tags.
Say you wanted to use the following in your code, and still make this work with the HTML module :
doc.render({
htmlDescription: "Dear Edgar,\nWhat's your plan today ?",
});
In this case, the "\n" will be ignored since in HTML, linebreaks can only be achieved by using a <br>
element, or a HTML block tag such as <p>
or <div>
.
One way to make this work together with the angularParser would be to postprocess your result.
You could do so like this :
const expressionParser = require("docxtemplater/expressions.js");
const htmlModuleNameBlock =
"pro-xml-templating/html-module-block";
const htmlModuleNameInline =
"pro-xml-templating/html-module-inline";
const htmlPptxModuleNameBlock =
"pro-xml-templating/html-pptx-module-block";
const htmlPptxModuleNameShape =
"pro-xml-templating/html-pptx-module-shape";
const htmlPptxModuleNameInline =
"pro-xml-templating/html-pptx-module-inline";
const htmlModuleTags = [
htmlModuleNameBlock,
htmlModuleNameInline,
htmlPptxModuleNameBlock,
htmlPptxModuleNameShape,
htmlPptxModuleNameInline,
];
const doc = new Docxtemplater(zip, {
paragraphLoop: true,
linebreaks: true,
parser(tag) {
const obj = expressionParser(tag);
return {
get(scope, context) {
let result = obj.get(scope, context);
if (
htmlModuleTags.indexOf(
context.meta.part.module
) !== -1 &&
typeof result === "string"
) {
// for all html tags, replace "\n" by `<br>`
result = result.replace(/\n/g, "<br>");
}
return result;
},
};
},
modules: [new HTMLModule(), new HTMLPptxModule()],
});
doc.render({
htmlDescription: "Dear Edgar,\nWhat's your plan today ?",
});
Similarly, it is possible to preprocess or postprocess, you could be inspired by one of these samples :