docx-reporting

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
    }
  }
}