easy-template-x

easy-template-x

Generate docx documents from templates, in Node or in the browser.

• Prior art and motivation
• Node Example
• Browser Example
• Writing your own plugins
• API
• Binary Formats
• Limitations
• Changelog

Prior art and motivation

There are already some very good templating libraries out there, most notably these two:

• docxtemplater
• docx-templates

easy-template-x takes great inspiration from both. It aspires to take the best out of both and to support some usecases that are not supported by either. Specifically, it keeps the ease of use that docxtemplater provides to the end user and adds line break auto insertion which is currently missing there.

Internally it works more like docx-templates than docxtemplater in that sense that it traverses xml documents node by node in a strongly typed manner rather than using a text matching approach.

It was also inspired by docxtemplater modules system and introduces a similar plugins system. The main difference in that area is that the library is fully written in TypeScript and the code base provides a lot of comments and explanation inside, thus making it as easy as possible to write your own custom plugins.

Node Example

import * as fs from 'fs';
import { TemplateHandler } from 'easy-template-x';

// 1. read template file
const templateFile = fs.readFileSync('myTemplate.docx');

// 2. process the template
const data = {
    posts: [
        { author: 'Alon Bar', text: 'Very important\ntext here!' },
        { author: 'Alon Bar', text: 'Forgot to mention that...' }
    ]
};

const handler = new TemplateHandler();
const doc = await handler.process(templateFile, data);

// 3. save output
fs.writeFileSync('myTemplate - output.docx', doc);

Input:

Output:

Browser Example

The following example produces the same output while running in the browser. Notice that the actual template processing (step 2) is exactly the same as in the previous Node example.

import { TemplateHandler } from 'easy-template-x';

// 1. read template file

// (in this example we're loading the template by performing  
//  an AJAX call using the fetch API, another common way to  
//  get your hand on a Blob is to use an HTML File Input)
const response = await fetch('http://somewhere.com/myTemplate.docx');
const templateFile = await response.blob();

// 2. process the template
const data = {
    posts: [
        { author: 'Alon Bar', text: 'Very important\ntext here!' },
        { author: 'Alon Bar', text: 'Forgot to mention that...' }
    ]
};

const handler = new TemplateHandler();
const doc = await handler.process(templateFile, data);

// 3. save output
saveFile('myTemplate - output.docx', doc);

function saveFile(filename, blob) {

    // see: https://stackoverflow.com/questions/19327749/javascript-blob-filename-without-link

    // get downloadable url from the blob
    const blobUrl = URL.createObjectURL(blob);

    // create temp link element
    let link = document.createElement("a");
    link.download = filename;
    link.href = blobUrl;

    // use the link to invoke a download
    document.body.appendChild(link);
    link.click();

    // remove the link
    setTimeout(() => {
        link.remove();
        window.URL.revokeObjectURL(blobUrl);
        link = null;
    }, 0);
}

Writing your own plugins

To write a plugin inherit from the TemplatePlugin class.
The base class provides two methods you can implement and a set of utilities to make it easier to do the actual xml modification.

Example plugin implementation (source):

/**
 * A plugin that inserts raw xml to the document.
 */
export class RawXmlPlugin extends TemplatePlugin {

    // Declare your prefix:
    // This plugin replaces tags that starts with a @ sign.
    // For instance {@my-tag}
    public readonly prefixes: TagPrefix[] = [{
        prefix: '@',
        tagType: 'rawXml',
        tagDisposition: TagDisposition.SelfClosed
    }];

    // Plugin logic goes here:
    public simpleTagReplacements(tag: Tag, data: ScopeData): void {

        // Tag.xmlTextNode always reference the actual xml text node.
        // In MS Word each text node is wrapped by a <w:t> node so we retrieve that.
        const wordTextNode = this.utilities.docxParser.containingTextNode(tag.xmlTextNode);

        // Get the value to use from the input data.
        const value = data.getScopeData();
        if (typeof value === 'string') {

            // If it's a string parse it as xml and insert.
            const newNode = this.utilities.xmlParser.parse(value);
            XmlNode.insertBefore(newNode, wordTextNode);
        }

        // Remove the placeholder node.
        // We can be sure that only the placeholder is removed since easy-template-x
        // makes sure that each tag is isolated into it's own separate <w:t> node.
        XmlNode.remove(wordTextNode);
    }
}

API

TODO - Meanwhile, you can checkout the typings file.

Binary Formats

The library supports the following binary formats:

• Blob (browser)
• Buffer (node)
• ArrayBuffer (browser and node)

Limitations

Iterating table rows is currently not supported. Feel free to write your own plugin for that ;)

Changelog

The change log can be found here.

Changelog

0.4.0 - 2018-12-13

Added

• Easily find out what tags are present in a given template (TemplateHandler.parseTags).