Html-pptx module

Important : This module only supports pptx (Powerpoint documents), not docx, see the html if you want 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>
<table>, <tr>, <tbody>, …

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 {~~styledParagraphs} which will use the "styledParagraphs" data
Any tag starting with ~~~ is used for shape HTML, such as : {~~~html} or {~~~styledTable} which will use the "styledTable" data

Usage

Usage (nodejs)

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

const doc = new Docxtemplater(zip, {
    modules: [new HTMLPptxModule({})],
});
doc.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;
                }

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

                doc.render({
                    html: "<p>Hello <b>John</b></p>",
                });
                const 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>

Inserting tables

To insert a table, you'll have to use the "shape" level HTML tag, with three "tilde" symbols, like this :

{~~~myTable}

In your code, you can then write :

doc.render({
    myTable: `
            <table>
              <tr>
                <td><p>Hello</p></td>
              </tr>
            </table>
        `,
});

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 HTMLPptxModule = require("docxtemplater-html-pptx-module");
const doc = new Docxtemplater(zip, {
    modules: [
        new HTMLPptxModule({
            ignoreUnknownTags: true,
        }),
    ],
});
doc.render(/* data */);

List support

It is possible to customize the list-style-type using the following code :

const doc = new Docxtemplater(zip, {
    modules: [
        new HTMLPptxModule({
            styleSheet: `
                ul {
                    list-style-type: "•";
                }
                ul ul {
                    list-style-type: decimal;
                }
                ul ul ul {
                    list-style-type: "🟥";
                }
                ul ul ul ul {
                    list-style-type: "🟨🟨";
                }
                ul ul ul ul ul {
                    list-style-type: "\\1F44D";
                    /* => will show : 👍 */
                }
            `,
        }),
    ],
});
doc.render({
    html: "<ul><li>List</li><ul><li>Lvl2</li></ul></ul>",
});

We support the following values :

- `none`
- `decimal`
- `lower-alpha`
- `lower-latin`
- `upper-alpha`
- `upper-latin`
- `lower-roman`
- `upper-roman`
- `disc`
- `circle`
- `square`
- `"\\1F44D"` (will show : 👍)
- `"•"`

CHANGELOG

3.7.1

Use new internal xmlContentTypes API (requires docxtemplater 3.55.1 or higher)

3.7.0

Improve support of lists : we correctly will use the style from the bullets defined in the master slide if a style is defined there.

Add support for CSS property : -dx-list-start-level: 1 : this will use the lvl="1" as the start level for HTML lists. The default is 0.

Add support for customizing the bullet for your lists using list-style-type.

We're simplifying our CSS custom property prefix from -dxt- to -dx- while maintaining backward compatibility.

Changes

Old prefix: -dxt- (still supported)
New prefix: -dx- (now preferred)

Examples

Previous:

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

Preferred:

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

Migration

Use -dx- for all new code
Existing -dxt- code will continue to work
Update old code gradually when convenient

For bulk updates, find -dxt- and replace with -dx-.

3.6.3

Fix corruption when havingtag

3.6.2

Add support for text-decoration-color (on normal text or links) to customize the underline color.
Improve support for star selector.

3.6.1

Make it possible to use prefix from the constructor

3.6.0

Add support for :

the <mark> tag to highlight text in yellow
background-color set on text
calling nullGetter if the value of the data is nullish

3.5.11

Bugfix of a corruption, when using a {~html} tag that itself is a link, the output document could get corrupted.

It now works correctly.

3.5.10

Add typescript typings to be able to change the module prefix

3.5.9

When having a loop with an inline HTML tag inside it, the following error would sometimes appear :

HtmlInlinePptxTag should be placed inside a run

This error should no more appear, the document should generate correctly now.

3.5.8

Allow to change text color of links using following cod :

const HTMLPptxModule = require("docxtemplater-html-pptx-module");
const doc = new Docxtemplater(zip, {
    modules: [
        new HTMLPptxModule({
            styleSheet: `
                a {
                    color: #f3a;
                }
            `,
        }),
    ],
});
doc.render({
    html: '<a href="https://docxtemplater.com">link</a>',
});

3.5.7

Fix regression : correctly template slideMaster and slideLayout files (if some {placeholders} are present in the slideMaster, those will now be correctly templated).

3.5.6

Add support for vertical-align: bottom (or middle, top).

3.5.5

When including the module using webpack, throw specific error if cssParser could not be loaded.

See this Create React App issue and this @adobe/css-tools issue.

3.5.4

Add support for <figure> and <figcaption> tag (which renders exactly like a div).

3.5.3

Upgrade module to use NodeNext moduleResolution setting. See explanation here

3.5.2

Bugfix to set or get xml attributes correctly, even when using tabs instead of spaces in tags attributes

3.5.1

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

3.5.0

Add initial support for tables.

To add a table, you need to use a tag with three ~, like this :

{~~~html}

const HTMLPptxModule = require("docxtemplater-html-pptx-module");
const doc = new Docxtemplater(zip, {
    modules: [
        new HTMLPptxModule({
            styleSheet: `
                    tr td,tr th {
                        border-top: none;
                        border-left: 6px solid orange;
                        border-bottom: 4px dashed orange;
                    }
                `,
        }),
    ],
});
doc.render({
    html: `
    <table>
        <tr>
            <td>Hello</td>
            <td>Foo</td>
        </tr>
    </table>
`,
});

This initial version supports the following :

colspan and rowspan
background-color
border using the stylesheet option

3.4.4

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

3.4.3

Bugfix issue when having {~~html} as the title :

The following error was thrown :

Raw tag not in paragraph

Now, the generation happens (no stacktrace thrown).

3.4.2

Add support for margin-left or padding-left on paragraph element.

3.4.1

Correctly keep font-family of existing text used in the {~~html} tag.

Previously, the font-family was lost.

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.

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.

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

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

Try the demos