easy-template-x

To use easy-template-x in a Node.js environment, use the fs module to read your template file as a Buffer and write the resulting document back to the file system.

1. Read the template file using fs.readFileSync.
2. Initialize TemplateHandler.
3. Call handler.process(templateFile, data) with your data object.
4. Save the resulting Buffer using fs.writeFileSync.

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);

To create a custom plugin, extend the TemplatePlugin class. You must define a unique contentType that matches the _type property in your input data.

Implement the simpleTagReplacements method to handle the logic for your specific tag type. You can use utilities from officeMarkup and xml to query and modify the document structure.

Example Implementation:

import { officeMarkup, xml } from "easy-template-x";

export class RawXmlPlugin extends TemplatePlugin {

    // Declare the unique "content type" this plugin handles
    public readonly contentType = 'rawXml';

    public simpleTagReplacements(tag: Tag, data: ScopeData): void {
        
        const value = data.getScopeData<RawXmlContent>();
        if (value && typeof value.xml === 'string') {

            // Find the actual XML text node in MS Word
            const wordTextNode = officeMarkup.query.containingTextNode(tag.xmlTextNode);

            // Parse and insert the new XML content
            const newNode = xml.parser.parse(value.xml);
            xml.modify.insertBefore(newNode, wordTextNode);
        }

        // Remove the placeholder tag
        officeMarkup.modify.removeTag(tag);
    }
}

Required Content Interface:

export interface RawXmlContent extends PluginContent {
    _type: 'rawXml';
    xml: string;
}

import { officeMarkup, xml } from "easy-template-x";

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

    // Declare the unique "content type" this plugin handles
    public readonly contentType = 'rawXml';

    // Plugin logic goes here:
    public simpleTagReplacements(tag: Tag, data: ScopeData): void {
        
        // Get the value to use from the input data.
        const value = data.getScopeData<RawXmlContent>();
        if (value && typeof value.xml === 'string') {

            // 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 = officeMarkup.query.containingTextNode(tag.xmlTextNode);

            // If the input data contains an "xml" string property, parse it and insert the content next to the placeholder tag.
            const newNode = xml.parser.parse(value.xml);
            xml.modify.insertBefore(newNode, wordTextNode);
        }

        // Remove the placeholder tag.
        officeMarkup.modify.removeTag(tag);
    }
}

In the browser, you can process templates by fetching a .docx file as a Blob or obtaining it via an HTML File Input. The processing logic remains identical to the Node.js implementation. To save the resulting document, you typically create a temporary URL from the resulting Blob and trigger a download via a link element.

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

// 1. read template file (e.g., via fetch)
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) {
    const blobUrl = URL.createObjectURL(blob);
    let link = document.createElement("a");
    link.download = filename;
    link.href = blobUrl;
    document.body.appendChild(link);
    link.click();
    setTimeout(() => {
        link.remove();
        window.URL.revokeObjectURL(blobUrl);
        link = null;
    }, 0);
}