Types of tags

The template is created in Microsoft Word or other software that can save a docx.

neoWord tags introduction

With this template (input.docx):


Hello {name} !


And given the following data (data.json):


{
    name:'John'
}


docxtemplater will produce (output.docx):


Hello John !


neoWord Conditions

Conditions start with a pound and end with a slash. That is {#hasKitty} starts a condition and {/hasKitty} ends it.

{#hasKitty}Cat’s name: {kitty}{/hasKitty}
{#hasDog}Dog’s name: {dog}{/hasDog}

and this data:


{
    "first_name":"Jane",
    "hasKitty": true,
    "kitty": "Minie"
    "hasDog": false,
    "dog": null
}


renders the following:

Cat’s name: Minie


neoWord Loops

Conditions and loops use the same syntax called Sections

The following template:


{#products}
    {name}, {price} €
{/products}


Given the following data:

{
    "products": [
        { name: "Windows", price: 100 },
        { name: "Mac OSX", price: 200 },
        { name: "Ubuntu", price: 0 }
    ]
}


will result in:

Windows, 100 €

Mac OSX, 200 €
Ubuntu, 0€


To loop over an array containing primitive data (ex: string):


{
   "products": [
       "Windows",
       "Mac OSX",
       "Ubuntu"
   ]
}


{#products} {.} {/products}


Will result in:

Windows Mac OSX Ubuntu


neoWord Sections

A section begins with a pound and ends with a slash. That is {#person} begins a “person” section while {/person} ends it.

The section behaves in the following way:


Type of the value

the section is shown

scope

falsy or empty array

never

 

non empty array

for each element of array

element of array

object

once

the object

other truthy value

once

unchanged


This table shows for each type of value, what is the condition for the section to be changed and what is the scope of that section.

If the value is of type boolean, the section is shown once if the value is true, and the scope of the section is unchanged.

If we have the section


{#hasProduct}
    {price} €
{/hasProduct}


Given the following data:


{
    "hasProduct": true,
    "price": 10
}


Since hasProduct is a boolean, the section is shown once if hasProduct is true. Since the scope is unchanged, the subsection {price} € will render as 10 €

neoWord Inverted Sections

An inverted section begins with a caret (hat) and ends with a slash. That is {^person} begins a “person” inverted section while {/person} ends it.

While sections can be used to render text one or more times based on the value of the key, inverted sections may render text once based on the inverse value of the key. That is, they will be rendered if the key doesn’t exist, is false, or is an empty list. The scope of an inverted section is unchanged.

Template:


{#repo}
  <b>{name}</b>
{/repo}
{^repo}
  No repos :(
{/repo}


Data:


{
  "repo": []
}


Output:

No repos :(


neoWord Sections and newlines

New lines are kept inside sections, so the template:


{#repo}
  {name}>
{/repo}
{^repo}
  No repos :(
{/repo}


Data:


{
  "repo": [
      {name: "John"},
      {name: "Jane"},
  ]
}


Will actually render


NL
  John
NL
NL
  Jane
NL


(where NL represents an emptyline)

The easiest to make this work is to enable the paragraphLoop option, like this :

// Now, all sections in the form of :
// {#section}
// something
// {/section}
// will keep just the inner paragraphs, and drop the newlines of the outer section
const doc = new Docxtemplater(zip, {paragraphLoop: true});


An other less recommended way if you don’t want to set this option, is to remove the new lines after the start of the section and before the end of the section.

For our example , that would be:

{#repo} {name}
{/repo} {^repo} No repos :( {/repo}


neoWord Raw XML syntax

It is possible to insert raw (unescaped) XML, for example to render a complex table, an equation, …

With the rawXML syntax the whole current paragraph (w:p) is replaced by the XML passed in the value.


{@rawXml}


with this data:


doc.render({
    rawXml : `
    <w:p>
        <w:pPr>
            <w:rPr>
                <w:color w:val="FF0000"/>
            </w:rPr>
        </w:pPr>
        <w:r>
            <w:rPr>
                <w:color w:val="FF0000"/>
            </w:rPr>
            <w:t>
                My custom
            </w:t>
        </w:r>
        <w:r>
            <w:rPr>
                <w:color w:val="00FF00"/>
            </w:rPr>
            <w:t>
                XML
            </w:t>
        </w:r>
    </w:p>
    `
})


This will loop over the first parent <w:p> tag

neoWord Dash syntax

When using sections, neoWord will try to find on what element to loop over by itself:

If between the two tags {#tag}______{/tag}


  • there is a tag <w:tc> , that means that your loop is inside a table, and it will loop over <w:tr> (table row).
  • by default, it will loop over <w:t>, which is the default Text Tag


With the Dash syntax you can specify the tag you want to loop on: For example, if you want to loop on paragraphs (w:p), so that each of the loop creates a new paragraph, you can write:


{-w:p loop} {inner} {/loop}