docx-reporting

NPM module to render a docx file from a template.

The template docx file support a template syntax for text insertion, conditionals, loops and images.

Installation

yarn add docx-reporting

Usage

import * as docx from "docx-reporting";

const template = fs.readFileSync(`template.docx`);
const data = {
  text: "Hello, World!",
};

docx.generate(template, data).then(rendered => {
  fs.writeFileSync(`rendered.docx`, rendered);
});

Template Syntax

| Template | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | {value} | Simple placeholder. {value} will be substituted with the real value. | | {#items}...{/items} | Loop placeholder. The content within the loop scope, indicated by "...", will be repeated for as many items there are. See "Loops" below for further details | | {?value}...{/value} | Condition placeholder. The content within the condition scope, indicated by "...", will be rendered if value is not null, undefined or false. Otherwise the whole construct is removed. | | {!image}🖼️{/image} | Image placeholder. The image within, indicated by 🖼️, will be replaced with a provided image. See "Images" below for further details |

Loops

Each time the loop is rendered, the scope is set to the current array element.

Example:

Template:

{#fruits}
{name}
{price} EUR
{/fruits}

Data:

{
  fruits: [{ name: "Apple", price: 1.0 }, { name: "Orange", price: 1.8 }];
}

To access variables outside the element scope, $parent can be used.

Example:

Template:

{#fruits}
{name}
{price} {$parent.currency}
{/fruits}

Data:

{
  "currency": "EUR",
  "fruits": [
    { "name": "Apple", "price": 1.0 },
    { "name": "Orange", "price": 1.8 }
  ]
}

Additionaly a set of special variables are provided for additional loop control

| Variable | Type | Description | | ----------- | --------- | --------------------------------------------------------------------------- | | $index | number | iterator offset of the repeated element (0..length-1) | | $first | boolean | true if the repeated element is first in the iterator. | | $notFirst | boolean | true if the repeated element is not first in the iterator. | | $middle | boolean | true if the repeated element is between the first and last in the iterator. | | $last | boolean | true if the repeated element is last in the iterator. | | $notLast | boolean | true if the repeated element is not last in the iterator. | | $even | boolean | true if the iterator position $index is even | | $odd | boolean | true if the iterator position $index is odd |

Images

The template need to include an image that will be repalced during rendering. You can use this placeholder image to set the correct size and position.

Example:

Template:

{?image}
🖼️
{/image}

Data:

{
  "image": {
    "name": "image.jpg"
  }
}

The actual image data must be passed as an ArrayBuffer or Buffer as the third parameter to the docx.generate function.

import * as docx from "docx-reporting";

const template = fs.readFileSync(`template.docx`);
const image = fs.readFileSync(`image.jpg`);
const data = {
  image: { name: "image.jpg" },
};
const media = {
  "image.jpg": image,
};

docx.generate(template, data, media);

If you do not want your image to keep the size set in the template you can provide a size in pixels in the image object:

{
  "image": {
    "name": "image.jpg",
    "size": {
      "width": 500,
      "height": 300
    }
  }
}