The docxtemplater object is the core of the library. It handles:
Return Value : returns a new Docxtemplater instance.
zip: a zip instance (docx/pptx/xlsx files are actually zip files), coming from pizzip or jszip version 2.
options
You can use this object to configure docxtemplater : change the delimiters, add modules, template options or a custom parser.
You can pass the list of modules that you'd like to attach.
const options = {
modules: [new HTMLModule()],
};
const doc = new Docxtemplater(zip, options);
doc.render(/* data */);
You can change the delimiters instead of {name}, use <name> :
const options = {
delimiters: {
start: "<",
end: ">",
},
};
const doc = new Docxtemplater(zip, options);
doc.render(/* data */);
This constructor with 2 arguments is preferred over the constructor without any arguments. The constructor without arguments will be removed in docxtemplater version 4. When calling the constructor with a zip file as the first argument, the document will be compiled during instantiation, meaning that this will throw an error if some tag is misplaced in your document.
This function returns a new Docxtemplater instance, it is deprecated, you should now use the constructor with two arguments.
This function replaces all template variables by their values.
tags: Type: Object {tag_name:tag_replacement} Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, your Object should be:
doc.render({ firstName: "David" });
This function replaces all template variables by their values.
The difference between render and renderAsync is that renderAsync will return a Promise and can use values that are promises.
tags: Type: Object {tag_name:tag_replacement} Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, your Object should be:
doc.renderAsync({
firstName: new Promise(function (resolve, reject) {
resolve("David");
// or reject(new Error("An error occured while fetching the data"));
}),
});
Calling doc.renderAsync(tags) is exactly the same as doc.resolveData(tags).then(function() { doc.render() })
This will return you the zip that represents the docx. You can then call .generate on this to generate a buffer, string , ... (see pizzip generate docs)
This function is deprecated, instead use the new constructor with two arguments.
This function parses the template to prepare for the rendering. If your template has some issues in the syntax (for example if your tag is never closed like in : Hello {user), this function will throw an error with extra properties describing the error. This function is called for you in render() if you didn't call it yourself. This function should be called before doing resolveData() if you have some async data.
This function is deprecated, instead use the new constructor with two arguments.
You have to pass a zip instance to that method, coming from pizzip or jszip version 2
This function is deprecated instead use the new constructor with two arguments.
This function is used to configure the docxtemplater instance by changing the parser, delimiters, etc. (See docxtemplater configuration).
This function is deprecated, instead use the new constructor with two arguments.
This will attach a module to the docxtemplater instance, which is usually used to add new generation features (possibility to include images, HTML, ...). Pro modules can be bought on docxtemplater.com
This method can be called multiple times, for example:
doc.loadZip(zip)
.attachModule(new HTMLModule())
.attachModule(new XlsxModule());
This function is deprecated, instead use doc.render(tags)
Tags: Type: Object {tag_name:tag_replacement} Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, your Object should be:
{ "firstName": "David" }
This function is deprecated, instead use doc.renderAsync(tags)
Tags: Type: Object {tag_name:tag_replacement} Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, use :
{ "firstName": "David" }
The function returns a Promise when all data points have been resolved.
We are planning a future major upgrade of docxtemplater (4.0) in the following months.
Since docxtemplater 3.54.0, docxtemplater will now show deprecations messages for methods that should no more be used and that will be dropped in the next docxtemplater v4. All these methods have been deprecated in the docs for at least 3 years.
If you have a "Deprecated method" message, the upgrade time will be approximately 15 minutes.
Many methods are deprecated, and most of them are now directly in the new Docxtemplater(zip, options) parameter.
doc.loadZip(zip) is now inside the constructor (first argument), ie : new Docxtemplater(zip, options);doc.attachModule(module) is now inside the constructor (second argument, key modules inside an Array), ie : new Docxtemplater(zip, { modules: [module] });doc.compile() is now done by the constructor (We check if the number of arguments of the constructor is 1 or more).doc.setOptions(options) is now inside the constructor (second argument), ie new Docxtemplater(zip, options);.doc.setData can now be called from the render function with doc.render(data);await doc.resolveData(data); can now be called with await doc.renderAsync(data); (in this case you don't need to call doc.render() any more)For example, you can migrate the following code :
const fs = require("fs");
const expressionParser = require("docxtemplater/expressions.js");
const content = fs.readFileSync("input.docx").toString();
const zip = new PizZip(content);
const htmlModule = new HTMLModule();
const doc = new Docxtemplater()
.attachModule(htmlModule)
.loadZip(zip)
.setOptions({
parser: expressionParser,
linebreaks: true,
paragraphLoop: true,
});
doc.compile();
await doc.resolveData(/* data */);
doc.render();
const buffer = doc.getZip().generate({ type: "nodebuffer" });
fs.writeFileSync("output.docx", buffer);
to this :
const fs = require("fs");
const expressionParser = require("docxtemplater/expressions.js");
const content = fs.readFileSync("input.docx").toString();
const zip = new PizZip(content);
const htmlModule = new HTMLModule();
const doc = new Docxtemplater(zip, {
parser: expressionParser,
linebreaks: true,
paragraphLoop: true,
modules: [htmlModule],
});
await doc.renderAsync(/* data */);
const buffer = doc.getZip().generate({ type: "nodebuffer" });
fs.writeFileSync("output.docx", buffer);