JavaScript API

Introduction

phpdocx 15 Premium licenses include phpdocxjs, a JavaScript library to work with DOCX documents using nodejs and web browsers.

Developed with TypeScript, phpdocxjs is the best and most complete JavaScript library to generate DOCX documents from scratch and using DOCX templates.

Among its many features, the following can be highlighted:

Add new contents.
Create and apply new styles.
Replace contents in templates.
Modify layouts.
Set settings.
WordFragments.
RTL settings.
Transform measuring units.
...

Compatibility and included bundles

To achieve the best possible compatibility with nodejs and web browsers, phpdocxjs uses TypeScript with the following compiler options:

"target": "es2015",
"module": "node16",
"lib": ["es2017", "DOM"],
"moduleResolution": "node16",
"strict": true,

The following formats are included in the package:

CommonJS: cjs
ESM: mjs
IIFE: iife.js

in addition to map files and TypeScript type information.

To use phpdocxjs it's not mandatory to develop with TypeScript, but it's recommended. Vanilla JavaScript can also be used with phpdocxjs.

New documents

Creating a new DOCX is as simple as instance the CreateDocx class, add new contents using the available methods and save the document.

The save method returns a Promise object.

For example, to add a text and a list using TypeScript with nodejs:

import { CreateDocx } from "build";
import * as fs from "fs";

const docx = new CreateDocx();

docx.addText("New content.");

const items: ListNested = [
    "Item 1",
    "Item 2",
    ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
    "Item 3",
    "Item 4",
    "Item 5",
];
const optionsListBullets: OptionsList = {
    type: "bullets",
};
docx.addList(items, optionsListBullets);

docx.save().then(contents => {
    fs.writeFileSync("document.docx", Buffer.from(contents));
});

fs.writeFileSync is available in nodejs File system.

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateDocx } from "build/dist/phpdocx.mjs";
import * as fs from "fs";

const docx = new CreateDocx();

docx.addText("New content.");

const items = [
    "Item 1",
    "Item 2",
    ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
    "Item 3",
    "Item 4",
    "Item 5",
];
const optionsListBullets = {
    type: "bullets",
};
docx.addList(items, optionsListBullets);

docx.save().then(contents => {
    fs.writeFileSync("document.docx", Buffer.from(contents));
});

The same sample using Vanilla JavaScript with nodejs and CommonJS:

"use strict";

var phpdocxjs = require("build");
var fs = require("fs");
var docx = new phpdocxjs.CreateDocx();

docx.addText("New content.");

var items = [
    "Item 1",
    "Item 2",
    ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
    "Item 3",
    "Item 4",
    "Item 5",
];

var optionsListBullets = {
    type: "bullets",
};

docx.addList(items, optionsListBullets);

docx.save().then(function (contents) {
    fs.writeFileSync("document.docx", Buffer.from(contents));
});

The following sample (generateDocx.js) generates and downloads a new DOCX in a web browser with the ESM module:

import { CreateDocx } from "./phpdocx.mjs";

const docx = new CreateDocx();

docx.addText("New content.");

const items = [
    "Item 1",
    "Item 2",
    ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
    "Item 3",
    "Item 4",
    "Item 5",
];
const optionsListBullets = {
    type: "bullets",
};
docx.addList(items, optionsListBullets);

docx.save().then(contents => {
    saveAs(new Blob([contents]), "document.docx");
});

<script src="//cdnjs.cloudflare.com/ajax/libs/FileSaver.js/2.0.4/FileSaver.min.js"></script>
<script src="./generateDocx.js" type="module"></script>

saveAs, available in FileSaver.js is the easiest way to download the document in a web browser.

The same sample using the IIFE format:

const docx = new phpdocx.CreateDocx();

docx.addText("New content.");

const items = [
    "Item 1",
    "Item 2",
    ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
    "Item 3",
    "Item 4",
    "Item 5",
];
const optionsListBullets = {
    type: "bullets",
};
docx.addList(items, optionsListBullets);

docx.save().then(contents => {
    saveAs(new Blob([contents]), "output.docx");
});

<script src="//cdnjs.cloudflare.com/ajax/libs/FileSaver.js/2.0.4/FileSaver.min.js"></script>
<script src="./phpdocx.iife.js"></script>
<script src="./generateDocx.js"></script>

Template documents

The openTemplate method is used to open a DOCX template and replace, remove and add new contents.

The openTemplate method returns a Promise object.

For example, to open a DOCX template and replace text variables in the document target using TypeScript with nodejs:

import { CreateDocx } from "build";
import * as fs from "fs";

const docxTemplate = fs.readFileSync("template.docx");

const docx = new CreateDocx();
// load the template
docx.openTemplate(docxTemplate).then(docx => {
    // variables to be replaced in the document target
    const variablesDocument = new Map<string, string>();
    variablesDocument.set("VARNAME", "new value");
    variablesDocument.set("OTHERVAR", "a new text\nwith a line break");

    // replace variables in the document target
    docx.replaceVariableText(variablesDocument);

    // save the DOCX
    docx.save().then(contents => {
        fs.writeFileSync("document.docx", Buffer.from(contents));
    });
});

fs.readFileSync is available in nodejs File system.

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateDocx } from "build/dist/phpdocx.mjs";
import * as fs from "fs";

const docxTemplate = fs.readFileSync("template.docx");

const docx = new CreateDocx();
// load the template
docx.openTemplate(docxTemplate).then(docx => {
    // variables to be replaced in the document target
    const variablesDocument = new Map();
    variablesDocument.set("VARNAME", "new value");
    variablesDocument.set("OTHERVAR", "a new text\nwith a line break");

    // replace variables in the document target
    docx.replaceVariableText(variablesDocument);

    // save the DOCX
    docx.save().then(contents => {
        fs.writeFileSync("document.docx", Buffer.from(contents));
    });
});

The following sample (generateDocxFromTemplate.js) opens a DOCX template, generates and downloads a new DOCX in a web browser:

import { CreateDocx } from "./phpdocx.mjs";

const docxTemplate = new FileReader();
// DOCX file as blob. For example from "const files = event.currentTarget.files;"
docxTemplate.readAsArrayBuffer(files[0]);

docxTemplate.onload = function() {
    const docx = new CreateDocx();
    // load the template
    docx.openTemplate(docxTemplate.result).then(docx => {
        // variables to be replaced in the document target
        const variablesDocument = new Map();
        variablesDocument.set("VARNAME", "new value");
        variablesDocument.set("OTHERVAR", "a new text\nwith a line break");

        // replace variables in the document target
        docx.replaceVariableText(variablesDocument);

        // save the DOCX
        docx.save().then(contents => {
            saveAs(new Blob([contents]), "output_template.docx");
        });
    });
};

Using FileReader API is the easiest approach to generate an ArrayBuffer from a local file (a File or a Blob object) in a web browser.

In addition to replacing contents, phpdocxjs includes methods to delete contents, get existing variables, optimize templates, customise the symbols used to define variables, and add WordFragments.

External files

External files such as images, DOCX templates and DOCX outputs in phpdocxjs use ArrayBuffer objects for maximum compatibility. Any JavaScript function or library compatible with ArrayBuffer can be used.

For example, to load an image using TypeScript with nodejs:

import { CreateDocx, OptionsImage } from "build";
import * as fs from "fs";

const docx = new CreateDocx();

const imageFile = fs.readFileSync("image.jpg");

const image: OptionsImage = {
    image: imageFile,
};
docx.addImage(image);

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateDocx } from "build/dist/phpdocx.mjs";
import * as fs from "fs";

const docx = new CreateDocx();

const imageFile = fs.readFileSync("image.jpg");

const image = {
    image: imageFile,
};
docx.addImage(image);

Using the FileReader API is the easiest approach to generate an ArrayBuffer from a local file (a File or a Blob object) in a web browser:

import { CreateDocx } from "build/dist/phpdocx.mjs";

const docx = new CreateDocx();

const imageFile = new FileReader();
// DOCX file as blob. For example from "const files = event.currentTarget.files;"
imageFile.readAsArrayBuffer(files[0]);

imageFile.onload = function() {
    const image = {
        image: imageFile.result,
    };
    docx.addImage(image);

    docx.save().then(contents => {
        saveAs(new Blob([contents]), "output_image.docx");
    });
}

The Fetch API can be used to fetch external files.

More information

On JavaScript API are available the documentation pages, with all methods, options and samples of use. In addition to this documentation, phpdocx Premium packages include many samples to illustrate how to use all methods.