You are currently offline, serving cached version

Important : This module only supports pptx (Powerpoint documents), not docx, see the html if you to include HTML inside Word documents.

This module currently supports:

  • <p>
  • <h1-h6> with some default sizes for each level, the sizes of the titles can be customized
  • <span>
  • <br>
  • <ul>, <ol> and <li> for ordered and unordered lists
  • <strong> and <em>
  • <a href="URL">Linktext</a>

To insert HTML :

  • 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

Usage (nodejs)

const HTMLPptxModule = require("docxtemplater-html-pptx-module");

const zip = new PizZip(content);
const doc = new Docxtemplater(zip, {
    modules: [new HTMLPptxModule({})],
}).render({ html: "<b>Hello</b>, Foo !" });

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

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

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/html-module.js"></script>
    <script>
        PizZipUtils.getBinaryContent(
            "examples/input.docx",
            function (error, content) {
                if (error) {
                    console.error(error);
                    return;
                }

                var zip = new PizZip(content);
                var doc = new docxtemplater(zip, {
                    modules: [
                        new DocxtemplaterPptxHtmlModule({}),
                    ],
                });

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

Limitations

It is not possible to mix different types of HTML elements in a single shape.

In the PPTX format, everything is inside a "box" which is techically called a "shape" (XML tag <p:sp>) , and a box can contain either :

  • one or multiple paragraphs
  • one table
  • one shape
  • one image

The reason for that is that each box is statically positioned (x and y coordinate are set in the powerpoint document), so it is not possible to place a table and an image on the same tag for example because we do not know where we should place the second element.

In a pptx template, the tag {~~html} will be inside one particular box, so it can't generate multiple boxes (or they would overlap, which would be unreadable).

This is why one HTML tag : {~~html} will alway render one box, so for example the following HTML data would throw an error because it mixes tables and paragraphs :

<p>Hello</p>
<table>
  <tr>
    <td><p>Hello</p></td>
  </tr>
</table>
<p>Hello</p>

Options

It is possible to set options to the module in its constructor.

The options are as follows :

  • 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;
  • styleSheet makes it possible to add style to all HTML tags that are inserted.

To ignore all unknown tags:

const doc = new Docxtemplater(zip, {
    modules: [
        new HTMLPptxModule({
            ignoreUnknownTags: true,
        }),
    ],
});

CHANGELOG

3.4.0

Add support for inline html tag using {~html} (block tag is with {~~html}).

Rename property this.prefix to this.blockPrefix.

3.3.1

Bugfix "Cannot read properties of undefined (reading 'forEach')", when using stylesheet with comments.

3.3.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.2.5

Bugfix issue : TypeError: Cannot read properties of undefined (reading 'getElementsByTagName') in `getSlideLayoutPath when using together with the slides module.

3.2.4

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

3.2.3

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

3.2.2

Add typescript definitions for public API

3.2.1

When specifying a color with CSS, in previous versions, if the text containing the {~~html} tag was colored with a theme, the document could be corrupted.

This release fixes the bug, the color is now the right one.

3.2.0

Better handle override of style. Includes a quite big rewrite.

For example, it is now possible to override the color of some text in a given run without producing a corruption and without losing all other formatting on that block of text.

3.1.6

Disallow to pass something other than a string to the stylesheet option (because this option only allows to pass a given global stylesheet)

3.1.5

Bugfix when using together with slides module, it would result in the following error :

MultiError :
TypeError: Cannot read property 'length' of undefined
    at HtmlModule.hasListInSlideMaster (docxtemplater-html-pptx-module/es6/index.js:289:19)

Now, loops created with the slides module can contain html-pptx tags

3.1.4

Fix issue with css module :

Module not found: Error: Can't resolve 'fs' in '[...]\node_modules\css\lib\stringify'

Now, the module requires only the part that it uses, which removes this error.

3.1.3

Bugfix to ignore <br> at the end of block elements.

3.1.2

Bugfix to render space in inline HTML tag when using : <b>Foo</b> <i>Bar</i>

3.1.1

Bugfix corruption when using ul and li, sometimes, it would return a float value for spcPts

3.1.0

Add way to specify spacing between bullet and text, and indent of bullet with :

ul li {
    -dxt-bullet-indent: 1in;
    -dxt-bullet-spacing: 1in;
}

Better handle margin-top/margin-bottom for li tags

3.0.2

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

3.0.1

Add support for <u>, <sub> and <sup> tag and for style : text-decoration: underlined.

3.0.0

Initial release