Subsection module | docxtemplater

Summary

This module exposes two tags to import headers of footers from an external Word document, by changing the subsection :

The tag {:subsection doc} will create a new subsection on the location of the tag. It will use the header and footer that are present in the document doc.
The tag {:replacesection doc} will replace the current subsection. It will use the header and footer that are present in the document doc.

The subtemplate module and the subsection module serve distinct purposes. The subtemplate module facilitates the insertion of another document's content into the current one, specifically focusing on the main content (no headers/footers). In contrast, the subsection module specifically handles the inclusion of headers and footers from an external document while excluding its main content (This is what Word calls a "section"). It's important to note that by utilizing both the subtemplate and subsection modules, one can seamlessly integrate the entirety of an external document, encompassing headers, footers, and main content.

Usage

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

If you want to import headers and footers from document "a.docx" into the main document, do the following :

In your main document, use the tag {:subsection subdoc} or {:replacesection subdoc}

For example in document-main.docx :

{:replacesection subdoc}

In your code, you can write the following :

const fs = require("fs");
const SubsectionModule = require("docxtemplater-subsection-module");
const doc = new Docxtemplater(
    new PizZip(fs.readFileSync("document-main.docx")),
    { modules: new SubsectionModule() }
);
const subdoc = new Docxtemplater().loadZip(
    new PizZip(fs.readFileSync("a.docx"))
);
doc.render({
    subdoc,
});

At the place where you put the {:replacesection subdoc} tag, the current section will now use the headers/footers from subdoc (from a.docx in our example).

Subsection Rendering

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

For example :

const SubSectionModule = require("docxtemplater-subsection-module");
const expressionParser = require("docxtemplater/expressions.js");

const doc = new Docxtemplater(zip, {
    modules: [new SubSectionModule({})],
    parser: function recursiveParser(tagString) {
        const parser = expressionParser(tagString);
        return {
            get(scope, context) {
                const module =
                    context &&
                    context.meta &&
                    context.meta.part &&
                    context.meta.part.module;
                const isIncludeTag =
                    [
                        "pro-xml-templating/subsection-module",
                        "pro-xml-templating/replacesection-module",
                    ].indexOf(module) !== -1;
                const value = parser.get(scope, context);
                if (isIncludeTag && value) {
                    value.render(scope);
                }
                return value;
            },
        };
    },
});
doc.render(data);

CHANGELOG

3.5.7

Upgrade module to use NodeNext moduleResolution setting. See explanation here

3.5.6

Set module.priority in order to have no more issues related to module ordering

3.5.5

Add module.clone() internal to make module work well with subsegment module

3.5.4

Bugfix to avoid adding styles that have w:default="1"

3.5.3

Avoid Error when trying to include an image with a cid target

3.5.2

Avoid corruption related to missing style id.

3.5.1

Make module work well in the browser without using xmldom (using window.XMLSerializer)

3.5.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.4.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.3.12

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

3.3.11

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

3.3.10

Add typescript definitions for public API

3.3.9

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

3.3.8

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 {:subsection doc}, the tag would not be replaced correctly.

3.3.7

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

3.3.6

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

3.3.5

Bugfix footer appearing multiple times in output

3.3.4

Bugfix footer not correctly included when the XML of the main document is not formatted the exact way xmldom wants it.

3.3.3

Bugfix when including images that are outside /word/media or have absolute paths

3.3.2

Bugfix when including footer or header with links (URLS). The error message was : Cannot read property 'asBinary' of null

3.3.1

Multiple bugfixes :

Bugfix for including footer in separate documents when the header also contains footers.
Bugfix when rId are not numeric

3.3.0

Add support for including headers/footers from separate documents.

3.2.4

Update browser build to use XMLSerializer instead of xmldom
Use requiredAPIVersion

3.2.3

Move docxtemplater from devDependencies to dependencies

Explanation : On some versions of npm (notably 5.8.0), when having a package containing docxtemplater-subsection-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.2.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 subsection module makes the module work with both versions newer than 3.6 and older than 3.6 of docxtemplater.

3.2.1

Make it possible to include the first section of a document having multiple sections.

3.2.0

Add support for being included by subtemplate module
Fix corruption for replacesection tag