Docs  /  Template authoring

Template authoring

Templates are ordinary Microsoft Word documents with merge fields and ranges. DocsNG fills in your data when it generates documents, so business users can own the layout — no code required.

Add fields to a Word document

Add fields using Word's Quick Parts menu:

1. Open a new or existing document in Microsoft Word.
2. Place the cursor where you want the field.
3. On the Insert tab, choose Quick Parts in the Text group.
4. Choose Field to open the Field dialog.
5. Under Categories, select MergeField.
6. In Field properties, enter the field name as ModelName.FieldName (for example Invoice.Number).
7. Click OK. The field appears in the document as «Invoice.Number».

Repeat for each field you want to add.

Define ranges

To tell DocsNG which data model a section belongs to, mark its start and end with ranges. Add a merge field RangeStart:ModelName at the beginning and RangeEnd:ModelName at the end. For the invoice example, the main model is Invoice, so the template begins with RangeStart:Invoice and ends with RangeEnd:Invoice.

Multiple & nested data models

To include data from related models, nest their ranges inside the main range:

RangeStart:Invoice
  Invoice.Number
  Invoice.Date
  RangeStart:Customer
    Customer.Name
    Customer.Address
  RangeEnd:Customer
  RangeStart:InvoiceItems
    InvoiceItems.Description
    InvoiceItems.Amount
  RangeEnd:InvoiceItems
  Invoice.Total
RangeEnd:Invoice

All rows of Customer render first, then all rows of InvoiceItems, as specified by the nested structure. If a model has multi-row data (datasets/arrays), DocsNG renders each row.

Worked example: an invoice template

A typical invoice template contains a table with two cells — Customer data on the left and Invoice data on the right. Because InvoiceItems may have many rows, it is placed in a table: the first row is the header; the first cell of the second row starts with RangeStart:InvoiceItems and the last cell ends with RangeEnd:InvoiceItems. DocsNG outputs one table row per item, then continues rendering the remaining Invoice fields (such as the totals).

Tables that span multiple pages

If the items table is too long for one page, keep it readable by repeating the header and allowing rows to break across pages:

1. Select the table, go to Table Tools → Layout → Properties.
2. On the Row tab, check Repeat as header row at the top of each page.
3. Also check Allow row to break across pages, then click OK.

For a totals table you want kept together, do the opposite: on the Table Properties disable row breaking so it stays on a single page.

Multiple documents in a single file

To render several invoices in one output file, add a page break just before the RangeEnd:Invoice tag. Each invoice then starts on a new page.

Example Word documents

• Single-invoice template (.docx)
• Multiple-invoices-in-one-document template (.docx)

Localisation

The template engine supports localisation for all fields — numbers, currencies, date and time. Each template has a default localisation setting that determines language and formatting. Users can override it at generation time (for example, French date and currency conventions for a French client, or 24-hour time for Japan).

Advanced localisation with MS Word field switches

You can apply custom formatting to individual fields with Word field switches (independent of the template's default localisation):

1. Select the merge field, e.g. Invoice.Date.
2. Press Alt+F9 (or right-click → Toggle Field Codes) to reveal the code, e.g. { MERGEFIELD Invoice.Date }.
3. Insert a switch, e.g. { MERGEFIELD Invoice.Date \@ "dd/MM/yyyy" }.
4. Press Alt+F9 again, then F9 to update the field.

Text case switches

Date switches

Use the date/time switch \@ with expressions in double quotes. yyyy/yy = year; MMMM/MMM/MM/M = month (note uppercase M for month, lowercase m is minutes); dddd/ddd/dd/d = day. You can add literal text and separators inside the quotes.

Number & currency switches

Use the numeric switch #. A 0 creates a fixed position; # sets a pattern without a required digit.

Conditional sections & loops

Show or hide parts of a template based on data, and repeat content. Author these by clicking in the Word add-in, or type them:

«If:Customer.VIP=Y»
  Thank you for being a valued customer.
«EndIf»

Conditionals support equality, inequality, comparisons and empty/not-empty checks, and apply to paragraphs, table rows, cells and inline runs. Repeating ranges (above) provide loops over related records.

In-template formatters

Format values inline without changing the template default — dates, numbers, currency, case, padding and defaults for empty values, honouring the selected culture (you can also use the MS Word field switches described above):

«Invoice.Date:date('yyyy-MM-dd')»
«Invoice.Total:currency»
«Customer.Name:upper»
«Customer.Ref:default('—')»

Aggregation

Compute totals inside or after a repeating range, honouring field type and culture:

«Sum:InvoiceItems.Amount»
«Count:InvoiceItems»
«Avg:InvoiceItems.UnitPrice»

Images, logos & QR codes

Insert images and logos from data (a stored image, base64, or an allow-listed URL) sized by the placeholder, and generate QR codes and barcodes from field values — from the add-in or with markers such as «Qr:Field». Image sourcing is size-limited and SSRF-safe. The classic Word DisplayBarcode approach is below.

Barcodes

Add barcodes and QR codes driven by your data:

1. Ensure the model has a field for the barcode data (e.g. CustomerAddress.AddressBarcode) and place its merge field inside the relevant range.
2. Position the cursor where the barcode should appear, then press Ctrl+F9 to create a field placeholder { } (typing curly brackets directly will not work).
3. Enter the barcode field. Syntax: { DISPLAYBARCODE "BarcodeData" BarcodeType [switches] }. Put a DocsNG merge field between the quotes as the data.

Example — a QR code of size 50 from CustomerAddress.AddressBarcode:

{ DISPLAYBARCODE "<<CustomerAddress.AddressBarcode>>" QR \s 50 }

Save the document and upload it to DocsNG as a template.

Supported barcode types

Need help? Contact us or try the live demo.