Demo
Readme
Changelog

Releases RSS Feed
Compatibility : nodejs and browser

Summary (version 3.5.3) Buy subtemplate module

This module adds a tag to include the content of an other docx document (which can be a template itself). This allows you to define subtemplates if your templates share common parts.

This module is available as part of the docxtemplater PRO plan.

The docxtemplater Demo needs Javascript to work Please enable javascript in your webbrowser to be able to test the module with different templates.

README

Subtemplate Module

This module exposes a tag to include subtemplate. The subtemplate is embeded into your document. Only the document content is embedded, footers and headers are not since they are unique for each document, so we use the headers/footers from your base template.

The styles of the resulting template should be the same as the styles from the template, which means that styles that exist in both the template and the included document will use the styles of the template itself. This means that if both your main template and your included document have Heading1, the style that will be applied to all Heading1 will be the style from the main template.

Installation:

You will need docxtemplater v3: npm install docxtemplater

Install this module with npm install --save "$url"

Usage

Your docx should contain the text: {:include subtemplate}.

In your data, the key subtemplate should be another docxtemplater instance.

You can then use the following code

const SubtemplateModule = require("docxtemplater-subtemplate-module");
const subtemplateModule = new SubtemplateModule({});

const headerZip = new PizZip(fs.readFileSync("header.docx"));
const footerZip = new PizZip(fs.readFileSync("footer.docx"));
const headerDoc = new Docxtemplater().loadZip(headerZip);
const footerDoc = new Docxtemplater().loadZip(footerZip);

const zip = new PizZip(fs.readFileSync("template.docx"));
const doc = new Docxtemplater().loadZip(zip);
doc.attachModule(subtemplateModule);
doc.setData({
    subtemplate: headerDoc,
    footer: footerDoc
});

doc.render();

In the browser

<html>
    <script src="node_modules/docxtemplater/build/docxtemplater.js"></script>
    <script src="node_modules/pizzip/dist/pizzip.js"></script>
    <script src="node_modules/pizzip/vendor/FileSaver.js"></script>
    <script src="node_modules/pizzip/dist/pizzip-utils.js"></script>
    <script src="build/subtemplate-module.js"></script>
    <script>
        function loadDocument(file) {
            return new Promise(function(resolve, reject) {
                PizZipUtils.getBinaryContent(file, function(error, content) {
                    if (error) {
                        return reject(errror);
                    }
                    resolve(content);
                });
            });
        }

        Promise.all([
            loadDocument("demo_template.docx"),
            loadDocument("examples/demo_header.docx"),
            loadDocument("examples/demo_footer.docx")
        ])
            .then(function(documents) {
                var doc = new docxtemplater().loadZip(new PizZip(documents[0]));
                doc.attachModule(new DocxtemplaterSubtemplateModule());
                var headerDoc = new docxtemplater().loadZip(
                    new PizZip(documents[1])
                );
                var footerDoc = new docxtemplater().loadZip(
                    new PizZip(documents[2])
                );
                doc.setData({
                    header: headerDoc,
                    footer: footerDoc
                });
                doc.render();
                var out = doc.getZip().generate({
                    type: "blob",
                    mimeType:
                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
                });
                saveAs(out, "generated.docx");
            })
            .catch(function(err) {
                console.log("error while loading documents");
                console.log(err);
            });
    </script>
</html>

After installing the module, you can use a working demo by running node sample.js.

Subtemplate Rendering

You can render the values in your subtemplate by using a custom parser and render the document with the current scope.

For example :

doc.setOptions({
    parser: function recursiveParser(tagString) {
        return {
            get(scope, data) {
                const isIncludeTag =
                    data &&
                    data.meta &&
                    data.meta.part &&
                    data.meta.part.module === "pro-xml-templating/include";
                let value = null;
                if (tagString === ".") {
                    value = scope;
                } else {
                    value = expressions.compile(tagString)(scope);
                }
                if (isIncludeTag && value) {
                    value.setData(scope);
                    value.render();
                }
                return value;
            }
        };
    }
});

Subsections

It is possible to include subsections, however, if you only have access to the subtemplate module, the headers will not be included.

If you have access to the subsection module, you can do the following to also include the headers of the included subsections :

const SubtemplateModule = require("docxtemplater-subtemplate-module");
const SubSectionModule = require("docxtemplater-subsection-module");
doc.attachModule(new SubtemplateModule({ subsection: new SubSectionModule() }));

When using the SubSectionModule with the SubtemplateModule, by default, the section where your tag {:include doc} is kept, meaning that it will create a new page before adding the document, and also at the end of the included document, it will include a pagebreak.

If you would prefer to not have this pagebreak, than the currentsubsection of the document is going to be replaced by the one from the subtemplate. To do this, you have two options :

var includedDoc = new Docxtemplater();
includedDoc.loadZip(new PizZip(includedContent));
includedDoc.replaceFirstSection = true;
includedDoc.replaceLastSection = true;

doc.setData({ included: includedDoc });

CHANGELOG

3.5.3

Bugfix "Cannot read property 'appendChild' of undefined" when including a document where the {:include tag} is followed by a page break

3.5.2

Make it possible to have pagebreaks between two includes, without removing the pagebreak.

3.5.1

Fix issue Cannot read property 'getAttribute' of undefined when having unnamed styles in main document.

3.5.0

Add numId from styles.xml so that numbering values are better copied
Include w:sdt tags in addition of w:p tags

3.4.8

Handle numeric style ids by using name for the comparison if the id exists.

3.4.7

Fix Memory Leak when including document containing many images.

3.4.6

Bugfix : add possibility to include image that is within a table

3.4.5

Update browser build to use XMLSerializer instead of xmldom
Use requiredAPIVersion

3.4.4

Move docxtemplater from devDependencies to dependencies

Explanation : On some versions of npm (notably 5.8.0), when having a package containing docxtemplater-subtemplate-module, the installation will generate a tree of node_modules that puts the module on a level where it has no access to docxtemplater. By explicitly asking it as a dependency, this issue is avoided.

3.4.3

Fix bug when using equations and including templates 2 levels deep (with parent.docx /son.docx and grand-son.docx which contains an equation).

3.4.2

Make module compatible with docxtemplater version 3.5 and below.

Explanation : Recently, the scopemananger API (internal API) has changed, this new version of the footnotes module makes the module work with both versions newer than 3.6 and older than 3.6 of docxtemplater.

3.4.1

Add support for adding arrays of subtemplates with subsections.

When using the SubsectionModule, make it possible to replace the first section of the including document and replace the last section of the included document (this avoids additional pagebreaks).