This module adds multiple features :

• Loop over table columns with the {:vt#users} {:vt/users} syntax (Vertical Loop Table) (for docx only)
• Create a table from scratch with the{:table table1} syntax, (Full Table) (for docx files only)
• Create a table by copying a cell over and over with the {:#grid user} syntax (Grid Table) (for docx files only)
• Create a table by copying a cell over and over together with the slides module : {:companies}{:#1} {:#2} syntax (Grid Table) (for pptx files only)
• Merge cells that are adjacent vertically into a single cell by using the {:merge-cells-col 1} where 1 is the column number, starting from 1. (for docx and pptx files)

Vertical Loop Table

To have the vertical-loop-table, write :

const TableModule = require("docxtemplater-table-module");
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Vertical()],
});
doc.render(data);

To create a vertical loop table, use the tag : {:vt#users} and {:vt/users}, for example

This will create a column for each user in the users array.

It will drop the column if users is false or empty.

It is also possible to conditionally show or hide a given column in a table using this tag, and using a boolean as the value for that tag.

Full Table

Usage

Your docx should contain the text: {:table table1}. You can find a working sample at ./sample.js

const TableModule = require("docxtemplater-table-module");
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Full()],
});
doc.render(data);

Options

In all options, the following units are used :

• Pixels (px), where 75pixels = 1inch = 2.54cm
• Dxa (dxa), where 1440dxa = 1inch = 2.54cm

When creating the table, you have multiple options :

• data : Example :

  data: [
      ["A1", "lorem"],
      ["B1", "lorem"],
      ["C1", "lorem"],
  ]
  

  This option defines the data of the table.

• fixedColumns: Example : [null, "Example 1", null, "Example 2"], this option defines the columns that should take the whole height of the table

• widths : [unit:px] Example : [100, 150, 320, 100], this option defines the width of each column

• totalWidth : [unit:px or percentage] Example : 300 This option cannot be used together with widths. if you use totalWidth, the width of each cell will be the totalWidth divided by the number of columns. For example, you can set totalWidth to 700 and have 2 columns of each width 350. It is also possible to set a width as a percentage with a string (for example : totalWidth: "80%". When using percentages, the current page layout will be taken into account, to have the table width depend on the page layout

• header : Example ["Source", "Hazard", "Handling", "Protection"] : This option defines the header of the table (in bold)

• subheader: Example ["The source", "The Hazard", "The Handling", "The Protection"] : This option defines the subheader of the table (in italic)

• finalPageBreak: (true or false), default false. Whether to insert a finalPageBreak after the generated table/tables

• indent : [unit:dxa] Example : 150, this option defines the indentation of the table, ie the indentation to be added before the leading edge of the table. It can also be used with a negative value, to make the table take more space than the page-margins allow

• border: Example : { type: "all", size: 5, color: "000000"} : This option defines the borders that are around each cell.

• cellMargin : [unit:dxa] Example : {left: 250, top: 100, right: 250, bottom: 0} : This option defines the margins in each cell (it controls the <w:tblCellMar> tag)

• chunkSize: Example : 6 : This option defines the number of rows after which to break the table into multiple tables

• spacingAfter: [unit:dxa] Example : 100 : This option defines the amount of space after each paragraph

• style : This option allows to restyle the table, for example the shades and the textAlignment properties

You can also have dynamic chunkSize, for example:

const doc = new Docxtemplater(zip, {
    modules: [
        new TableModule.Full({
            chunkSize: {
                type: "dynamic",
                size: { min: 7000, max: 8100 },
            },
        }),
    ],
});
doc.render();

This means that the height of the table will never exceed 8100 (the max). If the table exceeds the min, the next line will be in a new table. The unit is an internal word unit.

You can change the shade of the header, subheaders, or normal cells using the style option like this :

doc.render({
    table: {
        data: [
            [
                "1",
                "John",
                "Foobar",
                "3374 Olen Thomas Drive Frisco Texas 75034",
            ],
            [
                "2",
                "Mary",
                "Foobaz",
                "352 Illinois Avenue Yamhill Oregon(OR) 97148",
            ],
        ],
        size: [2, 4], // means 2 lines, 4 columns
        widths: [175, 175, 175, 175], // The widths of each column
        height: 200, // The height of each column
        header: ["Index", "Name", "Title", "Description"],
        style: {
            header: {
                shade: "DDDD33",
                textAlign: "left",
            },
            normal: {
                shade: "E0E0E0",
                textAlign: "right",
            },
        },
    },
});

Style

It is possible to change the following styles :

• The background-color:

  doc.render({
      table: {
          style: {
              header: {
                  shade: "DDDD33",
              },
          },
      },
  });
  

• The text alignment (left,right,center)

  doc.render({
      table: {
          style: {
              header: {
                  textAlign: "right",
              },
          },
      },
  });
  

• The vertical alignment (top,bottom,center)

  doc.render({
      table: {
          style: {
              header: {
                  verticalAlign: "right",
              },
          },
      },
  });
  

• The runProperties (bold, italic, underline, font sizes, …)

  doc.render({
      table: {
          style: {
              header: {
                  runProperties:
                      '<w:sz w:val="42"/><w:u w:val="single"/><w:b/><w:i/>',
              },
          },
      },
  });
  

Borders

Borders can use following syntax :

To set the borders on each direction :

doc.render({
    table: {
        border: { type: "all", size: 5, color: "000000" },
        data: [
            ["1", "John"],
            ["2", "Mary"],
        ],
        size: [2, 2],
        widths: [175, 175],
        height: 200,
    },
});

To set the border only on the left :

doc.render({
    table: {
        border: {
            left: {
                val: "triple",
                size: 10,
                color: "00FF00",
            },
        },
        data: [
            ["1", "John"],
            ["2", "Mary"],
        ],
        size: [2, 2],
        widths: [175, 175],
        height: 200,
    },
});

Global Options

It is possible to have global options for all tables created in the document, for example, to have all tables center-aligned :

const options = { align: "center" };
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Full(options)],
});
doc.render(data);

If options is an object, it will be merged with the default options.

It is also possible to pass a function here which gets the default options as an argument, and returns the used options.

For example, to remove the default spacingAfter of 200, you can write

const doc = new Docxtemplater(zip, {
    modules: [
        new TableModule.Full((defaultOptions) => {
            console.log("defaultOptions", defaultOptions);
            return {};
        }),
    ],
});
doc.render(data);

Adding HTML inside a table

It is possible to include HTML inside each table, by using the following code :

const TableModule = require("docxtemplater-table-module");
const HtmlModule = require("docxtemplater-html-module");
const doc = new Docxtemplater(zip, {
    modules: [
        new HtmlModule(),
        new TableModule.Full({ html: true }),
    ],
});
doc.render({
    header: ["Header1", "Header2"],
    data: [
        ["<p><strong>Strong</strong> Text</p>", "Good"],
        ["<p><u>Underline</u> Text</p>", "Good"],
        ["<p><span style='color:#f00'>Red</u> Text</p>", "Good"],
    ],
});

Merging multiple cells

It is possible to create a cell that spans multiple columns with the FullTable Module, like this :

const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Full()],
});
doc.render({
    table: {
        data: [
            [
                { colspan: "2", text: "John" },
                { colspan: "2", text: "Foobar" },
            ],
            [
                "2",
                "Mary",
                "Foobaz",
                "352 Illinois Avenue Yamhill Oregon(OR) 97148",
            ],
        ],
        size: [2, 4], // means 2 lines, 4 columns
        widths: [175, 175, 175, 175], // The widths of each column
        height: 200, // The height of each column
        header: ["Index", "Name", "Title", "Description"],
    },
});

Grid Layout

It is possible to create a grid layout like this :

Which will be rendered like this :

In your code, do the following

const TableModule = require("docxtemplater-table-module");
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Grid()],
});
doc.render({
    user: {
        size: [2, 4], // means 2 lines, 4 columns
        widths: [175, 175, 175, 175], // The widths of each column
        height: 200, // The height of each column
        data: [
            {
                index: 1,
                name: "John",
                title: "Foobar",
                description:
                    "3374 Olen Thomas Drive Frisco Texas 75034",
            },
            {
                index: 2,
                name: "Mary",
                title: "Foobaz",
                description:
                    "352 Illinois Avenue Yamhill Oregon(OR) 97148",
            },
            /* ... */
        ],
    },
});

PPTX Grid Layout - loop over multiple slides

If you also have access to the slides module version 3.2.0 or above, you can also have PPTX Grid Layout support.

You can generate multiple "slides" in a grid layout with following template :

companies is an array of objects representing each company.

It will generate output similar to this :

In your code, do the following

const TableModule = require("docxtemplater-table-module");
const SlidesModule = require("docxtemplater-slides-module");
const ImageModule = require("docxtemplater-image-module");
const imageOptions = {
    /* getImage, getSize */
};
const doc = new Docxtemplater(zip, {
    modules: [
        new TableModule.GridPptx(),
        new SlidesModule(),
        new ImageModule(imageOptions),
    ],
});

doc.render({
    companies: [
        {
            name: "first company",
            id: "first id",
            logo: "2",
            region: "france",
        },
        {
            name: "second company",
            id: "second",
            region: "germany",
        },
        {
            name: "third",
            id: "third id",
            logo: "4",
            region: "russia",
        },
        {
            name: "fourth",
            id: "fourth id",
            region: "italy",
        },
    ],
});

PPTX Grid Layout - loop on single slide

It is also possible to use the Grid Layout on some named data, for example :

will render :

with following data :

{
    "people": [
        {
            "personName": "Mary foo",
            "awards": [
                {
                    "name": "Swim 15km",
                    "image": "disc.png"
                },
                {
                    "name": "Jump 2m",
                    "image": "disc.png"
                },
                {
                    "name": "Drink 2L",
                    "image": "disc.png"
                }
            ]
        }
    ]
}

Merge cells vertically

It is possible to merge adjacent cells that have the same value.

In your code, do :

const TableModule = require("docxtemplater-table-module");
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Merge()],
});
doc.render(data);

The syntax for that is : {:merge-cells-col 1}, that should be placed inside a table, which means that in the first column, all adjacent cells that have the same content should be merged together.

For example :

will render :

When using the merge-cells-col tag, you specify on which columns you want the cells to be merged when they are identical. In this sample, it is just for column 1, but you could also write : {:merge-cells-col 1,2,4} to merge cells in column 1, 2 or 4

Merge cells horizontally

Since version 3.18.0, it is possible to merge adjacent cells that contain the same text horizontally.

This applies to the full table, and can be used like this :

const TableModule = require("docxtemplater-table-module");
const doc = new Docxtemplater(zip, {
    modules: [new TableModule.Merge()],
});
doc.render(data);

The syntax to use is : {:merge-cells-row}, that should be placed inside a table, which means that for all cells, if on the left or on the right of that cell, the content is the same, then the cells should be merged together.