Subtemplate module | docxtemplater

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.

Usage

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

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

Usage (nodejs)

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(zip, {
    modules: [subtemplateModule],
});
doc.render({
    subtemplate: headerDoc,
    footer: footerDoc,
});

Usage (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(
                    new PizZip(documents[0]),
                    {
                        modules: [
                            new DocxtemplaterSubtemplateModule(),
                        ],
                    }
                );
                var headerDoc = new docxtemplater(
                    new PizZip(documents[1])
                );
                var footerDoc = new docxtemplater(
                    new PizZip(documents[2])
                );
                doc.render({
                    header: headerDoc,
                    footer: footerDoc,
                });
                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 :

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

const headerDoc = new Docxtemplater(new PizZip(documents[1]));
const footerDoc = new Docxtemplater(new PizZip(documents[2]));

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.render(scope);
            }
            return value;
        },
    };
}

const doc = new Docxtemplater(zip, {
    modules: [subtemplateModule],
    parser: recursiveParser,
});

doc.render({
    header: headerDoc,
    footer: footerDoc,
});

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");
const doc = new Docxtemplater(zip, {
    modules: [new SubtemplateModule(), 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.render({ included: includedDoc });

Segments

The SegmentModule is part of the same package, and allow you to define a "segment" in the document that can be then included multiple times in the document.

You can use it like this in your template :

{:segment test1}
This is the segment 1
It can contain all {tags}.
{:segment/}

{#users}
{:includesegment test1}
{/}

In your code, write like this :

const SegmentModule =
    require("docxtemplater-subtemplate-module").Segment;
const doc = new Docxtemplater(zip, {
    modules: [new SegmentModule()],
});

CHANGELOG

3.9.0

Make module compatible with docxtemplater@3.28.0. Please make sure to update docxtemplater to 3.28.0 at the same time you update this module. The internal change made is the use of the new matchers API which fixes bugs that were triggered depending on the order of the modules that are attached to the instance. Now the order of the modules should not matter as expected.

3.8.0

Make module compatible with docxtemplater@3.27.0. Please make sure to update docxtemplater to 3.27.0 at the same time you update this module

3.7.1

Bugfix to have the subtemplate work with Office 365 files (files which use word/document2.xml instead of word/document.xml).

The module works in all possible cases now :

when the including file is an Office 365 file
when the included file is an Office 365 file
when using an Office 365 file with the self-including module

3.7.0

Add Subtemplate.Segment module, to allow to define a segment in a document and include it (in the same document).

3.6.7

Use @xmldom/xmldom instead of xmldom, see this github issue

3.6.6

When including a document that has subsections, the header / footer of the main document should be preserved in all cases.

3.6.5

Generate files in built with correct filename In previous versions, the filename was always build/docxtemplater.js. Now the filename is error-location-module.js The .min.js file is also created now.

3.6.4

Add typescript definitions for public API

3.6.3

Move webpack from dependency to devDependency (which triggered an error during installation on node version 10)

3.6.2

Internal change to allow to match tags with non-breaking space.

When entering Ctrl+Shift+Space, a "non-breaking" space is created.

When using a non-breaking space in the tag {:subtemplate doc}, the tag would not be replaced correctly.

3.6.1

Calculate maxDocPrId lazily (only at the time when we need the value), to avoid overhead when attaching the module.

3.6.0

To better match with the general behavior of docxtemplater, if some subtemplate is null or undefined, nothing will be rendered instead of getting the error : "The subtemplate for the tag 'foobar' does not exist".

This is now the same as with the loop module and the image module for example.

If you give a value that is not null or undefined but is not a valid Docxtemplater document, an error will still be shown.

3.5.6

Continuation of 3.5.5. There was still one case that would throw Cannot read property 'asArrayBuffer' of undefined when using inline images (ones present within a paragraph, inside the content).

The error should no more occur now.

3.5.5

Do not fail with error Cannot read property 'asArrayBuffer' of undefined when having a docx with image (containing absolute Target for images, which might have been generated by some other docxtemplater module or some other program).

Also import correct xmlns attributes from imported document.

3.5.4

Declare supportedFileTypes, which allows to use this module with the new docxtemplater constructor which was introduced in docxtemplater 3.17.

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.

Try the demos