Skip to content

Latest commit

 

History

History
97 lines (72 loc) · 3.38 KB

patcher.md

File metadata and controls

97 lines (72 loc) · 3.38 KB

Patcher

The patcher allows you to modify existing documents, and add new content to them.

!> The Patcher requires an understanding of Paragraphs.

Usage

import * as fs from "fs";
import { patchDocument } from "docx";

patchDocument(fs.readFileSync("My Document.docx"), {
    patches: {
        // Patches here
    },
});

Patches

The patcher takes in a patches object, which is a map of string to Patch:

interface Patch {
    type: PatchType;
    children: FileChild[] | ParagraphChild[];
}
Property Type Notes Possible Values
type PatchType Required DOCUMENT, PARAGRAPH
children FileChild[] or ParagraphChild[] Required The contents to replace with. A FileChild is a Paragraph or Table, whereas a ParagraphChild is typical Paragraph children.

The patcher also takes in a keepOriginalStyles boolean, which will preserve the styles of the patched text when set to true.

How to patch existing document

  1. Open your existing word document in your favorite Word Processor
  2. Write tags in the document where you want to patch in a mustache style notation. For example, {{my_patch}} and {{my_second_patch}}.
  3. Run the patcher with the patches as a key value pair.

Example

Word Document

Word Document screenshot

Patcher

?> Notice how there is no handlebar notation in the key.

The patch can be as simple as a string, or as complex as a table. Images, hyperlinks, and other complex elements within the docx library are also supported.

patchDocument(fs.readFileSync("My Document.docx"), {
    patches: {
        my_patch: {
            type: PatchType.PARAGRAPH,
            children: [new TextRun("Sir. "), new TextRun("John Doe"), new TextRun("(The Conqueror)")],
        },
        my_second_patch: {
            type: PatchType.DOCUMENT,
            children: [
                new Paragraph("Lorem ipsum paragraph"),
                new Paragraph("Another paragraph"),
                new Paragraph({
                    children: [
                        new TextRun("This is a "),
                        new ExternalHyperlink({
                            children: [
                                new TextRun({
                                    text: "Google Link",
                                }),
                            ],
                            link: "https://www.google.co.uk",
                        }),
                        new ImageRun({ type: 'png', data: fs.readFileSync("./demo/images/dog.png"), transformation: { width: 100, height: 100 } }),
                    ],
                }),
            ],
        },
    },
});

Demo

Source: https://github.com/dolanmiu/docx/blob/master/demo/85-template-document.ts

Example