Html Module

This module exposes a tag to include html. The HTML is converted to Native Open XML by the module. This allows you to add a formatted field entered by the user, or add more complex data by writing simple HTML (Open XML is much more complex to work with then HTML).

The HTML module currently supports:

<br> tags
<p> tags
<h1-6> tags, <h1> translates to Title, <h2> translates to Header1, <h3> translates to Header2, because there is no concept of title in the body of HTML
<p> tags
<b> tags
<i> tags
<u> tags
<ul> tags
<ol> tags
<li> tags
<span> tags
<small> tags
<s> tags
<strong> tags
<em> tags
<code> tags
<table>, <tr>, <td>, <tbody>, <thead>, <tfoot>, <th> tags
<a href="URL">Linktext</a> tags
<input type="checkbox"> and <input type="checkbox" checked>
<sub> and <sup>
<img> only if including the imageModule too, by using base64 src
<svg> only if including the imageModule too, but this format is only readable on newer Word version : Microsoft Word, PowerPoint, Outlook, and Excel 2016 on Windows, Mac, Android and Windows Mobile. See https://support.office.com/en-us/article/edit-svg-images-in-microsoft-office-2016-69f29d39-194a-4072-8c35-dbe5e7ea528c for details about this feature
style="color: #bbbbbb" property
style="font-size: 30px" property
style="background-color: blue" property (or with rgb codes)
style="text-decoration: underline" property
style="padding-left: 30px"
style="width:33%; height: 50%;" (on td only)
style="text-align:justify" (or other values)
style="vertical-align: bottom" (on td)
style="border: none" (on table)

Important : This module only supports docx, not pptx, for multiple reasons

Installation:

You will need docxtemplater v3: npm install docxtemplater

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

Usage

var HTMLModule=require('docxtemplater-html-module')

var opts = {}

var htmlModule =new HTMLModule(opts);

var zip = new JSZip(content);
var docx=new Docxtemplater()
    .attachModule(htmlModule)
    .loadZip(zip)
    .setData({html:'<b>Hello</b>, Foo !'})
    .render();

var buffer= docx
        .getZip()
        .generate({type:"nodebuffer", compression: "DEFLATE"});

fs.writeFile("test.docx",buffer);

In the browser, use following HTML file :

<html>
    <script src="node_modules/docxtemplater/build/docxtemplater.js"></script>
    <script src="node_modules/jszip/dist/jszip.js"></script>
    <script src="node_modules/jszip/vendor/FileSaver.js"></script>
    <script src="node_modules/jszip-utils/dist/jszip-utils.js"></script>
    <script src="build/html-module.js"></script>
    <script>
    JSZipUtils.getBinaryContent('examples/html-block-example.docx', function(error, content) {
        if (error) {
            console.error(error);
            return;
        }
        var opts = {}

        var htmlModule = new DocxtemplaterHtmlModule(opts);
        var zip = new JSZip(content);
        var doc = new docxtemplater()
            .loadZip(zip)
            .attachModule(htmlModule)
            .compile();

        doc.setData({html:'<p>Hello <b>John</b></p>'})
        doc.render();
        var out=doc.getZip().generate({
            type:"blob",
            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        })
        saveAs(out, "generated.docx");
    });
    </script>
</html>

Your docx should contain the text: {~html}. After installing the module, you can use a working demo by running node sample.js.

Any tag starting with ~ is used for inline HTML, such as : {~html} or {~inlineComment} which will use the "inlineComment" data
Any tag starting with ~~ is used for block HTML, such as : {~~html} or {~~styledTable} which will use the "styledTable" data

To be clear :

The {~inline} tag is used when you want to replace part of a paragraph. For example you can write :

My product is {~blueText} and costs ...

The tag is inline, there is other text in the paragraph. In this case, you can only use inline HTML elements (<span> , <b> , <i>, <u>\, …)

The {~~block} tag is used when you want to replace a whole paragraph, and you want to insert multiple elements

{~~block}

The tag is block, there is no other text in the paragraph. In this case, you can only use block HTML elements (<p>, <ul>, <table>, <ol>, <h1>)

Also, in tr elements, we can have lists, …, so you have to surround your tags with <p>.

This code will throw an error (Tag 'em' is of type inline, it is not supported as the root of a block-scoped tag) :

<td style="width:33.333333333333336%;">
foobar<em>italics</em>
</td>

And this code will work :

<td style="width:33.333333333333336%;">
<p>foobar<em>italics</em></p>
</td>

Options

It is possible to set options to the htmlModule.

Description of the options :

ignoreUnknownTags [default=false]: If this option is set to true, and the module finds an HTML tag that it doesn't handle, it will not fail but instead make as if the tag was of type <span>;
ignoreCssErrors [default=false]: If this option is set to true, all CSS errors are ignored and the library tries to parse the CSS with a best-effort algorithm;
styleTransformer makes it possible to rewrite the styles that are used by the HTML module, see below for an example;
sizeConverters makes it possible to change the ratio between px and dxa for different tags;
styleSheet makes it possible to add style to all HTML tags that are inserted.

To ignore all unknown tags:

const module = new HTMLModule({
    ignoreUnknownTags: true,
});

To remap the styles so that h1 maps to Heading1 (instead of the default Title)

function styleTransformer (tags, docStyles) {
    tags.h1 = docStyles.Heading1;
    tags.h2 = docStyles.Heading2;
    tags.h3 = docStyles.Heading3;
    tags.h4 = docStyles.Heading4;
    tags.h5 = docStyles.Heading5;
    return tags;
};
const module = new HTMLModule({
    styleTransformer: styleTransformer,
});

To change the size of "padding-left":

const module = new HTMLModule({
    sizeConverters: {
        paddingLeft: 20,
    },
});

This will make paddingLeft a little bit larger on word than the default (which is 15).

Reasons for not supporting pptx

This module handles only docx documents, not pptx.

The reason for that is that HTML maps well to docx because they use the same linear flow, eg elements are placed one after the other in the document. However PPTX documents have multiple slides, which are stored in different files, and each element is positioned absolutely in the slide. For example, in PPTX if you have a table element and a paragraph in the same slide, they need to be placed in two "different" blocks.

Lets take a simple example :

pptx Paragraph and table in PPTX

docx Paragraph and table in DOCX

Here is how these documents map to XML :

For pptx

<p:spPr>
    <a:xfrm>
        <a:off x="2376000" y="936000"/>
        <a:ext cx="3384000" cy="346320"/>
    </a:xfrm>
    <a:t>My paragraph</a:t>
</p:spPr>
<p:graphicFrame>
    <p:xfrm>
        <a:off x="3579480" y="2726640"/>
        <a:ext cx="5075280" cy="1439280"/>
    </p:xfrm>
    <a:tbl>
    ...
    </a:tbl>
</p:graphicFrame>

For docx

<w:p>
  <w:r>
    <w:t>My paragraph</w:t>
  </w:r>
</w:p>
<w:tbl>
...
</w:tbl>

As you can see, in docx, the elements come one after the other, without any "placement" information, in pptx however, these are placed absolutely with the <a:xfrm> and <p:xfrm> tags.

In standard HTML, you would write this example with :

<p>My paragraph</p>
<table>
    ...
</table>

which maps very well to docx, but not to pptx.

Support for images with `<img>`

To be able to replace the <img> tag, you have to also have access to the Image Module.

Then, you can do :

const HTMLModule = require("docxtemplater-html-module");
const ImageModule = require("docxtemplater-image-module");
const htmlModule = new HTMLModule({
    img: {
        Module: ImageModule,
        // By default getSize returns the width and height attributes if both are present, or 200x200px as a default value.
        getSize: function(data) {
            // The html element, for example, if the data is :
            // '<img height="20" src="...">'
            // you will have data.element.attribs.width = '20'
            console.log(data.element);
            // The arraybuffer of your image
            // (you could use https://github.com/image-size/image-size to calculate the size)
            console.log(data.src);
            console.log(data.part.value); // This contains 'myTag' if your tag is {~myTag}
            // You return an array in pixel (here we have width 50px and height 100px)
            return [50, 100];
        }
    }
}):

The <img> tag supports base64 and also urls, so for example, you can do :

<p>Hello</p>
<img src="data:image/gif;base64,R0lGODlhDAAMAIQZAAAAAAEBAQICAgMDAwQEBCIiIiMjIyQkJCUlJSYmJigoKC0tLaSkpKampqenp6ioqKurq66urrCwsPb29vr6+vv7+/z8/P39/f7+/v///////////////////////////yH+EUNyZWF0ZWQgd2l0aCBHSU1QACwAAAAADAAMAAAFSiCWjRmViVVmZRWWjiurXrBI2uMkFcdjrRfaJQIQCAKQTDBmKAYACAwuswAABoBEDMUgYAkOpWiFeRgUDZIKNnqpLaJLXM2KjaYhADs=" alt="">

Note that HTTP URLs in src will not work by default, you have to configure docxtemplater in async mode to do so.

You can use the following getSize function if you would like to use the same width and height as the image source.

import sizeOf from "image-size";
function getSize(img) {
    const buffer = new Buffer(img.src);
    return sizeOf(buffer);
}

Support for images in async support (for urls)

It is possible to add images with src="http://......" by using async docxtemplater.

You can customize the image resolver with the getValue function.

Here is an example showing how to retrieve the data form https://avatars3.githubusercontent.com/u/2071336?v=3&s=100 :

const fs = require("fs");
const https = require("https");
const http = require("http");
const url = require("url");
const DocxTemplater = require("docxtemplater");
const ImageModule = require("docxtemplater-image-module");
const HTMLModule = require("docxtemplater-html-module");
const JSZip = require("jszip");

function base64DataURLToArrayBuffer(dataURL) {
    const stringBase64 = dataURL.replace(/^data:image\/([a-z]+);base64,/, "");
    let binaryString;
    if (typeof window !== "undefined") {
        binaryString = window.atob(stringBase64);
    } else {
        binaryString = Buffer.from(stringBase64, "base64").toString("binary");
    }
    const len = binaryString.length;
    const bytes = new Uint8Array(len);
    for (let i = 0; i < len; i++) {
        const ascii = binaryString.charCodeAt(i);
        bytes[i] = ascii;
    }
    return bytes.buffer;
}
const defaultImage = base64DataURLToArrayBuffer(
    "data:image/gif;base64,R0lGODlhDAAMAIQZAAAAAAEBAQICAgMDAwQEBCIiIiMjIyQkJCUlJSYmJigoKC0tLaSkpKampqenp6ioqKurq66urrCwsPb29vr6+vv7+/z8/P39/f7+/v///////////////////////////yH+EUNyZWF0ZWQgd2l0aCBHSU1QACwAAAAADAAMAAAFSiCWjRmViVVmZRWWjiurXrBI2uMkFcdjrRfaJQIQCAKQTDBmKAYACAwuswAABoBEDMUgYAkOpWiFeRgUDZIKNnqpLaJLXM2KjaYhADs="
);
const base64Regex = /^data:image\/(png|jpg|svg|svg\+xml);base64,/;
const opts = {
    img: {
        Module: ImageModule,
        getValue: el => {
            const src = el.attribs.src;
            return new Promise(function(resolve) {
                // This is to continue to handle base64 images
                if (base64Regex.test(src)) {
                    return base64DataURLToArrayBuffer(src);
                }

                let parsedUrl;
                try {
                    parsedUrl = url.parse(src);
                } catch (e) {
                    resolve(defaultImage);
                    return;
                }

                let client;
                if (parsedUrl.protocol === "https:") {
                    client = https;
                }
                if (parsedUrl.protocol === "http:") {
                    client = http;
                }
                if (!client) {
                    return resolve(defaultImage);
                }

                client
                    .get(parsedUrl, function(res) {
                        const data = [];

                        res.on("error", function(err) {
                            console.log("Error during HTTP request", err);
                            resolve(defaultImage);
                        });

                        res
                            .on("data", function(chunk) {
                                data.push(chunk);
                            })
                            .on("end", function() {
                                resolve(Buffer.concat(data));
                            });
                    })
                    .on("error", () => {
                        resolve(defaultImage);
                    });
            });
        },
    },
};

const htmlModule = new HTMLModule(opts);
const content = fs.readFileSync("demo_template.docx");
const zip = new JSZip(content);
const docx = new DocxTemplater().loadZip(zip);
docx.attachModule(htmlModule);
docx.compile()
docx.resolveData({
    html: '<img width="30" height="30" src="https://avatars3.githubusercontent.com/u/2071336?v=3&s=100"/>'
}).then(function () {
    docx.render();
    const buffer = docx.getZip().generate({compression: "DEFLATE", type: "nodebuffer"});
    fs.writeFileSync("demo_generated.docx", buffer);
});

How are pixels converted to word ?

The problem is that a pixel is not a distance, but just the smallest entity on a given screen. Our usual devices will get more and more pixels but use the same size.

Thus we can't set in stone how long a pixel (in inches or centimeters).

To specify the conversion, we ask two questions :

deviceWidth : How large is your HTML document in pixels (typically it would be 1024px).
getDxaWidth : How large is your Docx document in dxas (1/1440 of an inch), for a standard A4 document, the total width (including margins) is 11906 dxas, and the width without margins (1 inch margin on the left and 1 inch margin on the right), is 11906-2880=9026 dxas

With these two options, docxtemplater can then accordingly convert any pixel value to a coherent size in your word document.

By default the options are as follows :

options = {
    deviceWidth: 487,
    getDxaWidth: function defaultGetDxaWidth(sections) {
        return 9026;
    }
}

It is possible to calculate the size in dxa directly from the template :

getDxaWidth: function(sections) {
    const firstSection = sections[0];
    // We use the width of the first section (the first page), minus the left and right margins by default
    return (firstSection.width - firstSection.leftMargin - firstSection.rightMargin);
}

You can change your deviceWidth to 1200, to be able to have a <table width="1200">...</table> fit into the page for example.

Customize docx-styles with classes

For block elements (p, h1,h2,h3,h4,h5,h6, ul, ol, and table), it is now possible to customize the docxstyle that is used depending on the html class of that element.

const options = {
    elementCustomizer: function(element) {
        if (element.classNames.indexOf("my-heading-class") !== -1 && element.name === "p") {
            return { pStyle: "Heading" };
        }
        // element.part.value will be the string "html1" if the tag used is {~~html1}
    }
}
const htmlModule = new HTMLModule(opts);
doc.attachModule(htmlModule);

The following HTML :

<p>Paragraph</p>
<p class="my-heading-class">Paragraph - heading</p>
<p>Normal paragraph</p>

will have the second paragraph rendered by using the Heading type.

Of course, you can use any docx style that you have defined in your docx template.

CSS Selectors

It is also possible to add CSS style with CSS selectors.

For example, if you want to change the font size with the CSS selector : h4, th p.important

const options = {
    elementCustomizer(element) {
        if (element.matches("h4, th p.important")) {
            return {
                // htmlStyle must be valid CSS style
                htmlStyle: "font-size: 30px;",
            };
        }
    },
}
const htmlModule = new HTMLModule(opts);
doc.attachModule(htmlModule);

You can use following selectors currently :

Selector	Example	Example description
.class	.intro	Selects all elements with class="intro"
#id	#firstname	Selects the element with id="firstname"
*	*	Selects all elements
element	p	Selects all <p> elements
element,element	div, p	Selects all <div> elements and all <p> elements
element element	div p	Selects all <p> elements inside <div> elements
element>element	div > p	Selects all <p> elements where the parent is a <div> element
element+element	div + p	Selects all <p> elements that are placed immediately after <div> elements
[attribute]	[target]	Selects all elements with a target attribute
[attribute=value]	[target=_blank]	Selects all elements with target="_blank"

Customize bullets

It is possible to customize bullets with the elementCustomizer API

For example, you can write :

options = {
    elementCustomizer(element) {
        if (element.matches("ul")) {
            return {
                bullets: ["·", "-", "+"],
            };
        }
    },
};
const htmlModule = new HTMLModule(opts);
doc.attachModule(htmlModule);

Edgar Hipp

I'm the creator of docxtemplater. I work on making docxtemplater great since 2013.