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.

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

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);
const buffer = doc.getZip().generate({ type: "nodebuffer" });

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);
const buffer = doc.getZip().generate({ type: "nodebuffer" });

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,
    protect = "readOnly",
    algorithm = "sha512", // You most likely should not change this, this is the most secure algorithm that word does support
    spinCount = 100000, // You most likely should not change this, a high spinCount will make the password much more difficult to guess
    // salt: "...." base64 string (very optional, it will be randomly generated when not provided)
});

doc.render(data);
const buffer = doc.getZip().generate({ type: "nodebuffer" });

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);
const buffer = doc.getZip().generate({ type: "nodebuffer" });

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);
const buffer = doc.getZip().generate({ type: "nodebuffer" });

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

CHANGELOG

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, for example :

const baseLink = "https://github.com/facebook/react";
metaModule.setHyperlinkBase(baseLink);

3.2.2

Add support for setting header/footer margins, for example :

metaModule.setMargins({
    left: 0.1,
    right: 0.1,
    top: 0.5,
    bottom: 0.5,
    header: 0.05,
    footer: 0.05,
});

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