JavaScript API: replaceVariableList

CONTENTS

LAYOUTS

SETTINGS

STYLES

TEMPLATES

OTHERS

replaceVariableList

PREMIUM

TRIAL / ADVANCED

Replaces list variables.

Note

You are reading the JavaScript API documentation. For the PHP API method please go to replaceListVariable.

Description

replaceVariableList (variables: Map<string, ListNested[]>, target: Target = "document", options: OptionsReplaceVariableList = {}): this

type ListNested = string | WordFragment | ListNested[];

type Target =
    | "document"
    | "header"
    | "footer"
    | "comment"
    | "endnote"
    | "footnote";

interface OptionsReplaceVariableList
    extends OptionsFirstMatch,
        OptionsParseLineBreaks {}

interface OptionsFirstMatch {
    /** Replace only the first match. Default as false */
    firstMatch?: boolean;
}

interface OptionsParseLineBreaks {
    /** Parse line breaks. Default as true */
    parseLineBreaks?: boolean;
}

Code samples

Example #1

import { CreateDocx, ListNested } 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 => {
    const itemsA: ListNested = [
        "Item 1",
        "Item 2",
        ["Item A", "Item B", "Item C", ["Item C.1", "Item C.2"]],
        "Item 3",
        "Item 4",
        "Item 5",
    ];

    // variables to be replaced in the document
    const variablesDocumentA = new Map<string, ListNested[]>();
    variablesDocumentA.set("LISTVAR_BODY_BULLET", itemsA);
    variablesDocumentA.set("LISTVAR_BODY_CUSTOM", itemsA);

    // replace variables in the document target
    docx.replaceVariableList(variablesDocumentA);

    // replace a list with line breaks
    const itemsB: ListNested = [
        "Item 1",
        "Item 2",
        ["Item \n2.A &", "Item \n2.B", "Item \n2.C"],
        "Item 3",
        "Item 4",
        "Item 5",
    ];

    const variablesDocumentB = new Map<string, ListNested[]>();
    variablesDocumentB.set("LISTVAR_BODY_NUMBERING", itemsB);

    // replace variables in the document target setting options
    docx.replaceVariableList(variablesDocumentB);

    const itemsHeader: ListNested = [
        "Item header 1",
        "Item header 2",
        "Item header 3",
    ];

    // variables to be replaced in the header target
    const variablesHeader = new Map<string, ListNested[]>();
    variablesHeader.set("LISTVAR_HEADER", itemsHeader);

    // replace template variables in the header target
    docx.replaceVariableList(variablesHeader, "header");

    const itemsFooter: ListNested = [
        "Item footer 1",
        "Item footer 2",
        "Item footer 3",
    ];

    // variables to be replaced in the footer target
    const variablesFooter = new Map<string, ListNested[]>();
    variablesFooter.set("LISTVAR_FOOTER", itemsFooter);

    // replace template variables in the footer target
    docx.replaceVariableList(variablesFooter, "footer");

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

The resulting Word document looks like:

Example #2

import {
    CreateDocx,
    ListNested,
    OptionsDateTime,
    OptionsImage,
    OptionsLink,
    OptionsText,
    WordFragment,
} 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 => {
    // create a text WordFragment
    const wordFragmentText = new WordFragment();
    const text: OptionsText = {
        bold: true,
        italic: true,
        fontSize: 14,
        text: "Item 2.",
    };
    wordFragmentText.addText([text]);

    // create a link WordFragment
    const wordFragmentLink = new WordFragment();
    const link: OptionsLink = {
        link: "https://www.phpdocx.com",
        text: "phpdocx",
    };
    wordFragmentLink.addLink(link);

    // create a link WordFragment
    const wordFragmentLinkB = new WordFragment();
    const optionsLinkB: OptionsLink = {
        link: "https://www.phpxlsx.com",
        text: "phpxlsx",
    };
    wordFragmentLinkB.addLink(optionsLinkB);

    // create texts WordFragments
    const wordFragmentTextA = new WordFragment();
    wordFragmentTextA.addText("A link to ");
    const wordFragmentTextB = new WordFragment();
    wordFragmentTextB.addText(
        " in the middle of a paragraph with the following date: "
    );

    // create a date WordFragment
    const dateTime: OptionsDateTime = {
        format: "M/d/yyyy",
        bold: true,
        color: "333333",
    };
    const wordFragmentDate = new WordFragment();
    wordFragmentDate.addDateTime(dateTime);
    const wordFragmentTextComplex = new WordFragment();
    wordFragmentTextComplex.addText([
        wordFragmentTextA,
        wordFragmentLinkB,
        wordFragmentTextB,
        wordFragmentDate,
    ]);

    const fileJpg = fs.readFileSync("image.jpg");
    const wordFragmentImageA = new WordFragment();
    const imageJpg: OptionsImage = {
        image: fileJpg,
    };
    wordFragmentImageA.addImage(imageJpg);

    const itemsA: ListNested = [
        "Item 1",
        wordFragmentText,
        [
            "Item A",
            "Item B",
            wordFragmentTextComplex,
            [wordFragmentImageA, "Item C.2"],
        ],
        wordFragmentLink,
        "Item 4",
        "Item 5",
    ];

    // variables to be replaced in the document
    const variablesDocumentA = new Map<string, ListNested[]>();
    variablesDocumentA.set("LISTVAR_BODY_BULLET", itemsA);

    // replace variables in the document target
    docx.replaceVariableList(variablesDocumentA);

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

The resulting Word document looks like:

Release notes

phpdocx 15.0:
- new method.