Templates

ScaiScribe templates support DOCX, PPTX, and XLSX. The three paths differ in grammar:

• DOCX — full grammar via docx-templates v4 (FOR, IF, ALIAS, IMAGE, LINK, HTML, EXEC, plus JS expression evaluation).
• PPTX — Tier 1 substitution only via the hand-rolled engine in workers/node/lib/ooxml-template-fill.js. No FOR/IF/commands; no JS evaluation. Dotted paths only.
• XLSX — same Tier 1 engine as PPTX. Inline strings AND shared strings are substituted.

Most of this page describes the DOCX grammar (the broadest surface). The "PPTX & XLSX (Tier 1)" section at the end covers what's supported on the other two formats.

If you just want the concept overview, see Concepts → Templates. For an end-to-end walkthrough, see Tutorials → Templates.

Delimiter#

ScaiScribe configures the engine with cmdDelimiter: ["{{", "}}"]. Every command lives inside {{ ... }} — there is no {% ... %} syntax, no Jinja-style block markers, no Mustache sections. One pair of double braces wraps everything.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{{ variable }}                                   ← insert
{{ INS variable }}                               ← insert (explicit form)
{{ = variable }}                                 ← insert (shorthand)
{{ FOR item IN items }} … {{ END-FOR item }}     ← loop
{{ IF condition }} … {{ END-IF }}                ← conditional
{{ ALIAS x INS something }} … {{ *x }}           ← alias
{{ IMAGE jsExpr }}                               ← image (see caveats below)
{{ LINK ({ url, label }) }}                      ← hyperlink
{{ HTML expression }}                            ← raw HTML (Word-only)
{{ EXEC something }}                             ← side-effect (no output)

The JavaScript expression inside any command has full access to the variables passed in variables at instantiation time.

Insertion#

Three ways to spell it#

1
2
3

{{ recipient.name }}             ← shorthand (most common)
{{ = recipient.name }}           ← shorthand with explicit `=`
{{ INS recipient.name }}         ← explicit

All three produce identical output. The "shorthand" form is what you'll use 95% of the time.

Expressions, not just paths#

The content between the delimiters is a JavaScript expression. The last evaluated statement gets inserted:

1
2
3
4
5

{{ recipient.name.toUpperCase() }}
{{ items.length }}
{{ amount > 1000 ? 'High value' : 'Standard' }}
{{ new Date(deadline).toLocaleDateString('en-GB') }}
{{ items.filter(x => x.urgent).map(x => x.name).join(', ') }}

Multi-line expressions work too — the last value is what gets inserted:

1
2
3
4

{{ INS
const total = items.reduce((sum, item) => sum + item.amount, 0);
`Total: €${total.toFixed(2)}`
}}

Nested paths#

{{ user.address.street }} resolves through the structure. Missing intermediate keys produce an error at render time (see Error handling).

If you want optional access, use JS optional chaining: {{ user?.address?.street ?? '—' }}.

Loops — FOR / END-FOR#

Iterate over arrays:

1
2
3

{{ FOR item IN line_items }}
- {{ $item.name }}: {{ $item.amount }}
{{ END-FOR item }}

Inside the loop, the current item is named with a $ prefix. Without the prefix, item would shadow… actually it just doesn't resolve cleanly. Always use the $ prefix inside loop bodies.

Loop variables#

• {{ $idx }} — current 0-based index of the innermost loop.
• {{ $item }} (or whatever you named it) — the current element.

Nested loops#

1
2
3
4
5
6

{{ FOR company IN companies }}
{{ $company.name }}
{{ FOR person IN $company.people }}
  - {{ $person.name }} (since {{ $person.since }})
{{ END-FOR person }}
{{ END-FOR company }}

$idx always refers to the innermost loop. Save the outer index to a variable if you need it:

1
2
3
4
5
6
7

{{ FOR company IN companies }}
{{ EXEC const companyIdx = $idx }}
  ...
{{ FOR person IN $company.people }}
  Person {{ companyIdx }}.{{ $idx }}: {{ $person.name }}
{{ END-FOR person }}
{{ END-FOR company }}

Filtering and sorting inline#

The expression after IN is JavaScript:

1
2
3

{{ FOR person IN project.people.filter(p => p.active).sort((a, b) => a.name.localeCompare(b.name)) }}
{{ $person.name }}
{{ END-FOR person }}

Loops over table rows#

Put the FOR marker in the row above the data row, and the END-FOR marker in the row below:

1
2
3
4
5

| Name                | Since              |
|---------------------|--------------------|
| {{ FOR p IN people }}                    |
| {{ $p.name }}       | {{ $p.since }}     |
| {{ END-FOR p }}                          |

docx-templates detects this and replicates the data row for each iteration. The marker rows themselves are removed from the output.

This works for arbitrary numbers of columns. It does NOT work for header rows (those aren't replicated).

Dynamic columns#

Loop horizontally too — FOR in the row above, END-FOR after the cell:

1

| {{ FOR col IN columns }} | {{ $col.label }} | {{ END-FOR col }} |

Combine row + column loops for fully dynamic tables. See the docx-templates README for the cell-template pattern.

Empty arrays#

{{ FOR x IN [] }} … {{ END-FOR x }} produces no output and no error. The block is skipped. If you want fallback text, wrap in IF:

1
2
3
4
5
6
7
8

{{ IF items.length > 0 }}
{{ FOR item IN items }}
- {{ $item.name }}
{{ END-FOR item }}
{{ END-IF }}
{{ IF items.length === 0 }}
_No items._
{{ END-IF }}

Conditionals — IF / END-IF#

1
2
3

{{ IF recipient.urgent }}
**URGENT** — please respond by {{ recipient.deadline }}.
{{ END-IF }}

The expression is plain JavaScript. Truthy values match — 0, "", null, undefined, false, NaN are falsy.

There is no ELSE. Use two separate IFs (or a ternary in an INS) for if-else:

1
2

{{ IF status === 'paid' }}Thank you for your payment.{{ END-IF }}
{{ IF status !== 'paid' }}Please remit within 30 days.{{ END-IF }}

Or:

1

{{ status === 'paid' ? 'Thank you for your payment.' : 'Please remit within 30 days.' }}

IF over table rows#

Same row-marker pattern as FOR. Put IF in the row above the conditional content, END-IF in the row below.

Nested IFs#

1
2
3
4

{{ IF subscriber }}
{{ IF subscriber.tier === 'gold' }}**Gold member** — priority support.{{ END-IF }}
{{ IF subscriber.tier === 'silver' }}Silver member.{{ END-IF }}
{{ END-IF }}

Internally IF is a FOR that iterates 0 or 1 times depending on the condition. They compose freely.

Aliases — ALIAS / *name#

Long expressions used in many places get unwieldy:

1
2
3

| {{ FOR p IN people }}                                                     |
| {{ $p.name.toUpperCase() }}  | {{ $p.contracts.filter(c => c.active).length }} |
| {{ END-FOR p }}                                                            |

Define aliases once, reference by *name:

1
2
3
4
5
6

{{ ALIAS upperName INS $p.name.toUpperCase() }}
{{ ALIAS activeCount INS $p.contracts.filter(c => c.active).length }}

| {{ FOR p IN people }}        |              |
| {{ *upperName }}             | {{ *activeCount }} |
| {{ END-FOR p }}              |              |

Aliases are particularly valuable in table rows where Word forces line-wrapping of long commands across multiple visual lines.

Images — IMAGE#

1

{{ IMAGE qrCode(project.url) }}

The expression must return an image object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  width: 6,            // cm
  height: 6,           // cm
  data: ArrayBuffer | base64 string,
  extension: '.png' | '.jpg' | '.jpeg' | '.gif' | '.svg',
  alt?: string,
  rotation?: number,   // degrees, clockwise
  caption?: string,
  thumbnail?: { data, extension }   // SVG fallback for older Word
}

Important: ScaiScribe does not pass additionalJsContext#

The IMAGE command needs access to helper functions (like qrCode() above) via the additionalJsContext option to createReport(). ScaiScribe currently does NOT pass that option, which means IMAGE is only usable with literal/inline image objects:

1

{{ IMAGE ({ width: 5, height: 5, data: variables.logo_b64, extension: '.png' }) }}

Pass the image data into your variables payload as a base64 string, then reference it via the expression. You'll still need exact width/height in cm.

For dynamic image generation (QR codes, charts as images, etc.), the workaround is to render the image in your application before instantiation and pass the bytes through.

Centering images#

Center the {{ IMAGE … }} command itself in the template (use Word's centre alignment on that paragraph). The image inherits the paragraph alignment.

Hyperlinks — LINK#

1
2
3

{{ LINK ({ url: 'https://scaiscribe.scailabs.ai', label: 'ScaiScribe' }) }}
{{ LINK ({ url: project.url, label: project.name }) }}
{{ LINK ({ url: project.url }) }}                          ← label defaults to url

The expression must return an object with url (required) and label (optional).

Raw HTML — HTML#

1
2
3

{{ HTML `
<p>This is <strong>HTML</strong> inserted via altchunk.</p>
` }}

Word supports this; LibreOffice and Google Docs do not (the altchunk feature is Word-specific). The HTML appears as a placeholder in those clients.

Avoid HTML for cross-client compatibility. If you need rich formatting, do it in the docx body directly or generate the formatted content as multiple commands.

Side effects — EXEC#

Run JavaScript without inserting output. Useful for setting variables you'll use later:

1
2
3
4
5
6
7

{{ EXEC let runningTotal = 0 }}
{{ FOR item IN items }}
{{ EXEC runningTotal += $item.amount }}
- {{ $item.name }}: {{ $item.amount }}
{{ END-FOR item }}

**Total: {{ runningTotal }}**

EXEC is equivalent to {{= undefined }} — the expression evaluates, the output is empty.

ScaiScribe-specific notes#

What counts as a "placeholder" in the API response#

When you POST /v1/templates, the response includes a placeholders array — every {{ … }} token found in word/document.xml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "template_id": "tpl_...",
  "name": "letterhead",
  "format": "docx",
  "byte_size": 24500,
  "placeholders": [
    "recipient.name",
    "FOR item IN items",
    "$item.name",
    "$item.amount",
    "END-FOR item",
    "IF urgent",
    "deadline",
    "END-IF"
  ]
}

The list reports every token verbatim — including FOR/END-FOR/IF/END-IF/ALIAS markers and $-prefixed loop variables. It's not a "variable catalogue"; it's a structural inventory.

To extract just the variable names a caller needs to provide, filter out anything starting with FOR/END-FOR/IF/END-IF/ALIAS/EXEC/INS/= and anything starting with $.

Where placeholders are scanned#

ScaiScribe currently scans only word/document.xml for the API response. Placeholders in headers, footers, and side-zip parts ARE rendered correctly at instantiation time — the engine processes everything — but they don't surface in the API's placeholders list. If your operator UI relies on the list to validate variable bindings, account for this gap.

What ScaiScribe does NOT pass through#

1
2
3
4
5

createReport({
  template,
  data,
  cmdDelimiter: ["{{", "}}"],
})

That's the full call. So these docx-templates features are unavailable:

• additionalJsContext — no custom JS helpers; IMAGE/EXEC/INS snippets can only use built-in JS (Math, Date, Array, etc.) and the data payload.
• processLineBreaks — defaults to true; you can't disable it.
• failFast — defaults to true; the first error stops processing.
• noSandbox — sandboxed by default; can't disable.
• Custom error handlers — uses the default.

Maximum template size#

Templates are capped at the same per-file ceiling as other binary uploads (~32 MB). Most templates are well under 1 MB.

Quotas#

• Each registered template counts under templates_count quota (default 20 per tenant).
• Each instantiation produces a normal document, counted under documents_count.
• Instantiation doesn't have its own quota; just the per-day render budget via renders_per_day.

Error handling#

ScaiScribe uses docx-templates with failFast: true (the default). The first error stops instantiation; the API returns a structured envelope:

1
2
3
4
5
6
7
8

{
  "error": {
    "code": "TEMPLATE_FAILED",
    "message": "docx-templates failed: TemplateError: Could not find ... in path \"recipient.name\"",
    "details": {},
    "request_id": "req_..."
  }
}

Common errors:

failFast means one mistake in one place kills the whole render. Test templates with realistic data before relying on them in production.

Limitations vs upstream docx-templates#

These are deliberate scope choices, not bugs. If your use case requires one of them, file a feature request.

PPTX & XLSX (Tier 2)#

PPTX and XLSX templates use a separate, smaller engine (workers/node/lib/ooxml-template-fill.js) rather than docx-templates. The reasons: no production-quality npm library covers PPTX templating; and XLSX templating libraries that exist are either tiny or unmaintained. Hand-rolled gives us the same {{ … }} syntax across all three formats with a predictable, debuggable code path.

What's supported#

What gets scanned for placeholders#

The API's placeholders field reports tokens found in:

• DOCX: word/document.xml
• PPTX: every ppt/slides/slideN.xml + every ppt/notesSlides/notesSlideN.xml
• XLSX: xl/sharedStrings.xml (interned text) + every xl/worksheets/sheetN.xml (inline strings)

Tokens in headers/footers (DOCX), master slides (PPTX), or other side parts still RENDER correctly at instantiation time. The scanner just doesn't surface them in the API field. If your operator UI relies on the list to validate variable bindings, account for the gap.

Expression language (PPTX/XLSX safe subset)#

The expression inside {{ … }} is parsed by a recursive-descent parser in workers/node/lib/template-expr.js. There is no eval, no VM, no native dependency. The parser walks the AST against your variables payload, applying methods only from a curated allowlist per type.

Supported syntax:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{{ recipient.name }}                        # path
{{ recipient.name.toUpperCase() }}          # method chain
{{ amount.toFixed(2) }}                     # numeric formatting
{{ items.0.name }}                          # array index (legacy)
{{ items[0].name }}                         # array index (bracketed)
{{ items.length }}                          # property access
{{ count > 5 ? "high" : "low" }}            # ternary
{{ count > 3 && status === "paid" }}        # logical + comparison
{{ price * 1.21 }}                          # arithmetic
{{ name.slice(0, 3).toUpperCase() }}        # chains compose

Allowed methods, by receiver type:

Any method call outside the allowlist (e.g. name.eval("…"), items.filter(...), count.constructor) is rejected at evaluation time and the token renders as empty + a TEMPLATE_EXPRESSION_ERROR warning lands in the result. This is the safety boundary — there is no path through the parser that lets a user expression access global state, allocate VMs, or escape the data scope.

Loops — FOR / END-FOR#

Three placement contexts:

PPTX text-frame loop#

Markers occupy whole paragraphs within an <a:txBody>:

1
2
3
4

{{ heading }}
{{ FOR item IN items }}
{{ $item.label }}: {{ $item.value }}
{{ END-FOR item }}

Three items → three replicated lines. Inside the body, $item is the current element and $idx is the 0-based index of the innermost loop.

XLSX row loop#

Markers occupy whole rows. The block between replicates per item; rows are renumbered to be contiguous; formula cell refs that point at the template row get rewritten per replica:

1
2
3
4
5
6
7

| A           | B            |
|-------------|--------------|
| Region      | Revenue      |   ← header (passthrough)
| {{ FOR row IN data }}      |   ← marker (removed)
| {{ $row.region }} | {{ $row.revenue }} |   ← data template (replicated)
| {{ END-FOR row }}          |   ← marker (removed)
| TOTAL       | =SUM(B2:B?)  |   ← totals (passthrough)

Three items → three data rows numbered 2, 3, 4; the totals row that started at row 5 in the template ends up at row 5 in the output. Relative cell refs in formulas get rewritten when their template row number equals the source row's number — absolute refs ($B$3) stay verbatim.

PPTX slide-level loop#

A slide-level FOR signals "clone this whole slide per data item":

• The slide's first text content must be {{ FOR x IN list }} on its own
• The slide's last text content must be {{ END-FOR x }} on its own

The slide between them is cloned N times. Each clone gets its own scope binding $x to the current item. The presentation's relationships, content types, and <p:sldIdLst> are updated. Slides are renumbered 1..N (no gaps).

Empty input (x = []) drops the template slide entirely — no marker-only slide remains in the output.

Conditionals — IF / END-IF#

Same paragraph / row placement as FOR. Truthy → keep content, falsy → drop:

1
2
3

{{ IF urgent }}
**URGENT** — please respond by {{ deadline }}
{{ END-IF }}

{{ END-IF }} takes no name (vs. DOCX's {{ END-IF }} which also doesn't, despite the FOR naming difference).

Authoring PPTX/XLSX templates#

For PPTX, use PowerPoint or LibreOffice Impress. Type {{ recipient.name }} directly into text frames where you want substitution. Avoid pasting the placeholders — pasting from another app often splits the token across many runs and even our coalescing has limits.

For XLSX, use Excel or LibreOffice Calc. Type {{ subject }} into a cell. Both cell types (interned strings via sharedStrings.xml and inline strings via <is>) are handled.

For multi-row loops, put each marker on its own row. Mixing data and a {{ FOR }} marker in the same row is treated as substitution, not a loop start.

Numbers, dates, and currency#

You have two options now (Tier 2):

Option 1 — pre-format in your application (recommended for dates):

1
2
3
4

variables = {
    "deadline": deadline.strftime("%d %B %Y"),   # "15 June 2026"
    "ratio_pct": f"{ratio:.1%}",                 # "8.5%"
}

Template: Due {{ deadline }} ({{ ratio_pct }}).

Option 2 — use the expression evaluator (good for currency / numeric formatting):

1
2
3

{{ amount.toFixed(2) }}                                    1234.57
{{ amount.toLocaleString("de-DE") }}                       1.234,567
{{ '€' + amount.toFixed(2) }}                              €1234.57

Dates aren't easy here — there's no Date global, so use Option 1 for date formatting. Currency works in-template with method chains.

Where to next#

• Concepts → Templates — the model.
• Tutorials → Templates — end-to-end example.
• Troubleshooting → Templates — error catalogue.
• docx-templates upstream — the underlying library's own docs for things ScaiScribe doesn't override.