You are currently offline, serving cached version

API

The docxtemplater object is the core of the library. It handles:

  • Document rendering with your data
  • DOCX/PPTX/XLSX manipulation
  • Additional utility methods
  • This page covers how to create a docxtemplater instance and details its available methods.

Constructor

new Docxtemplater(zip[, options])

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.

new Docxtemplater() - deprecated

This function returns a new Docxtemplater instance, it is deprecated, you should now use the constructor with two arguments.

Methods

render(tags)

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" });
    

renderAsync(tags)

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() })

getZip()

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)

compile() - deprecated

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.

loadZip(zip) - deprecated

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

setOptions() - deprecated

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).

attachModule(module) - deprecated

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());

setData(tags) - deprecated

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" }
    

resolveData(tags) - deprecated

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.

Talk with sales Contact us