You are currently offline, serving cached version

This module doesn't expose tags, but it makes it possible to do some operations on the docx itself.

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

The META module currently can :

  • Make a document readonly
  • Add a text watermark
  • Update the margins
  • Change the hyperlink base for the whole document
  • Restrict edition of document using a password
  • Search and replace some text in a paragraph
  • Search for some text and place a comment
  • Add a comment together with some tag

Usage

To use this module, do your operations before the call to the render method.

Readonly

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
metaModule.readonly();
doc.render(data);

Watermark

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
metaModule.addTextWatermark("DRAFT", {
    diagonal: true,
});
doc.render(data);

Restrict Edition using a password

Word has a "restrict edition" mode that one can setup so that the document will be readonly unless you have a specific password.

The meta module can protect a document in this way.

Note that the content of the document will not be encrypted, the Microsoft Office software will simply respect the restriction and a malicious user could quite easily remove that protection.

Usage is like this :

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
metaModule.restrictEdition({
    password: "my-complex-password", // This should be autogenerated
    // protect, default "readOnly",
    // algorithm, default: "sha512", // You most likely should not change this, this is the most secure algorithm that word does support
    // spinCount, default: 100000, // You most likely should not change this, a high spinCount will make the password much more difficult to guess
    // salt, base64 string (completely optional, it will be randomly generated when not provided)
});

doc.render(data);

The password length must be of at least 6 characters.

Note that spinCount and algorithm options already have default values which are secure enough for most use cases.

The protect option can take one of the following values :

  • "readOnly" => The document cannot be edited at all
  • "trackedChanges" => The document can be edited, all changes are tracked
  • "forms" => Only forms can be edited
  • "comments" => Only comments can be added/changed

There also is a salt parameter which is a base64string of 24 characters, but this value is generated by the library so you don't have to, in most cases.

Margins

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
// Margins are in inches, and apply to all pages
metaModule.setMargins({
    top: 0.5,
    left: 0.8,
    right: 1.2,
    bottom: 1,
});
doc.render(data);

Hyperlink Base

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
const baseLink = "https://github.com/facebook/react";
metaModule.setHyperlinkBase(baseLink);
doc.render(data);

Search and replace some text

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
const results = metaModule.search("Lorem"); // search also works with regex
if (results.length > 0) {
    metaModule.replace(results[0], "Tatum");
}
doc.render(data);

This will replace the first found "Lorem" by "Tatum".

Add a comment from a search

const DocxtemplaterMetaModule = require("docxtemplater-meta-module");
const metaModule = new DocxtemplaterMetaModule();
const doc = new Docxtemplater(zip, {
    modules: [metaModule],
});
const results = metaModule.search("Lorem");
if (results.length > 0) {
    metaModule.addComment(results[0], "This is a latin word", {
        author: "John Doe",
        initials: "JD",
        date: new Date(),
    });
}
doc.render(data);

This will search for the first "Lorem" and add a comment around it containing "This is a latin word".

Add a comment from a tag

Since version 3.4.0 of the meta module, it is possible to add a comment from a tag using the following code :

In your template :

Hello {user}
const CommentModule = require("docxtemplater-meta-module/comment-module.js");
const doc = new Docxtemplater(zip, {
    modules: [
        new CommentModule({
            author: "John the pirate",
            date: new Date().toISOString(),
        }),
    ],
});
doc.render({
    user: {
        text: "John",
        comment: "Updated 2022\nSome comment",
        // author: "Jane the pirate",
    },
});

CHANGELOG

3.4.2

Bugfix corruption when using comment module, if the tag was {user}, and the data was :

{
    "user": "John && Mary"
}

Then the output document would become corrupt.

With this version, the problem is fixed.

3.4.1

Bugfix to allow to template Hyperlinkbase when attaching the meta module (when not using setHyperlinkBase)

3.4.0

Add possibility to do search/replace or search/addComment

Add possibility to add some text together with a comment using the CommentModule, see this documentation.

3.3.1

Avoid possible issue of "Maximum call stack size exceeded"

3.3.0

Add possibility to restrict edition of generated document with : metaModule.restrictEdition({password: "user-entered-pass"}).

3.2.9

Bugfix metaModule.readonly()

3.2.8

Bugfix "Cannot read properties of undefined (reading 'xml')", when using metaModule.readonly();

3.2.7

Bugfix to always template "title" values, and all other possible tags contained in docProps/core.xml

3.2.6

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

3.2.5

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

3.2.4

Add typescript definitions for public API

3.2.3

Add support for setting hyperlink base using setHyperlinkBase(baseLink), see docs.

3.2.2

Add support for setting header/footer margins, see docs.

3.2.1

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

3.2.0

Add API to change margins

3.1.0

Add API to add text watermark

3.0.2

  • Update browser build to use XMLSerializer instead of xmldom

  • Use requiredAPIVersion

3.0.1

  • Move docxtemplater from devDependencies to dependencies

Explanation : On some versions of npm (notably 5.8.0), when having a package containing docxtemplater-meta-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.0.0

Initial release

Talk with sales