Handlebars Helpers Reference
HTML assets are rendered with Handlebars, using its standard helper set plus one SignStack helper, asset_url, for resolving image assets.
The template layer is deliberately presentational: it places values, loops and branches. Anything that needs to be computed — a total, a formatted date, a comparison, a label — is produced by the Template's data.transform and arrives as a plain variable. This is the data-first principle, and it keeps a document's logic in one reviewable place instead of scattered through markup.
This page lists the full helper set and shows how to express common computations in the transform.
The rule: arguments make it a helper call
A bare {{name}} is always safe, however unknown — Handlebars falls back to a property lookup and renders nothing if it misses. Only a name carrying arguments must resolve to a registered helper.
| Expression | Result |
|---|---|
{{unknownThing}} |
Renders "" — property lookup miss |
{{person.name}} |
Renders — path lookup |
{{#person}}…{{/person}} |
Renders — block with context |
{{#customers}}…{{/customers}} |
Renders — iterates the array |
{{someName 1 2}} |
Throws Missing helper: "someName" |
{{#someName tier}}…{{/someName}} |
Throws — block form with an argument |
{{#if (someName a b)}} |
Throws — subexpressions are calls too |
This is enforced before you ever reach a render: resource validation rejects an HTML asset that calls an unknown helper, so the error surfaces on save rather than in a failed job.
What you can use
Block helpers
| Helper | Notes |
|---|---|
{{#if}} / {{else}} / {{else if}} |
Truthiness only — no comparison operators |
{{#unless}} |
The negative branch without an empty if |
{{#each}} / {{else}} |
Arrays and objects; {{else}} covers the empty case |
{{#with}} |
Scope into a nested object |
{{^name}} |
Inverted section — renders when the value is falsy or empty |
{{else}} is a separator inside the blocks above, not a helper of its own — it is never opened or closed.
Inline helpers
| Helper | Notes |
|---|---|
{{lookup obj key}} |
Dynamic property access, e.g. {{lookup ../tiers @index}} |
{{log value}} |
Writes to the server console, emits nothing. Debugging only |
{{asset_url 'alias'}} |
SignStack-specific. Resolves an image asset to its signed URL |
Never write an inline helper in block form. {{#lookup obj key}}…{{/lookup}} does not error — Handlebars discards the block body and emits only the helper's value, so the markup between the tags silently disappears from the document.
Data variables (inside {{#each}})
| Variable | Notes |
|---|---|
{{@index}} |
Zero-based |
{{@key}} |
Property name, when iterating an object |
{{@first}} / {{@last}} |
Booleans for the first and last iteration |
{{this}} |
The current item |
{{../parent}} |
Reach out to the enclosing scope |
Other syntax
{{{triple-stash}}} for pre-sanitised HTML · {{> partialName}} for partials · {{~ ~}} for whitespace control · {{! }} and {{!-- --}} for comments.
helperMissingandblockHelperMissingare Handlebars' internal resolution hooks. They're never written by hand.
Computing values in the transform
Arithmetic, comparison, and date or string formatting happen in the Template's data.transform. The transform emits a named value; the template prints it.
Numbering the items of a loop is a good example. {{@index}} is zero-based, so a "Customer 1, Customer 2" label is computed in the transform — #$i binds the index:
"customers": $.agreement.customers#$i.$merge([$, {
"label": "Customer " & ($i + 1)
}])[]
{{#each customers}}
{{label}}
{{/each}}
The same shape covers the other common cases:
| To render | Compute in data.transform |
Then in the template |
|---|---|---|
| A conditional section | "isPremium": $.pricing.tier = "premium" |
{{#if isPremium}}…{{/if}} |
| A formatted date | "dateLabel": $fromMillis($toMillis($.date), "[D01]/[M01]/[Y0001]") |
{{dateLabel}} |
| A currency amount | "feeFormatted": "$" & $formatNumber($.fee, "#,##0.00") |
{{feeFormatted}} |
| Text in a different case | "nameUpper": $uppercase($.name) |
{{nameUpper}} |
| A total or subtotal | "total": $sum($.order.lines.amount) |
{{total}} |
See the JSONata Expressions Reference for the transform language.
If a render reports a missing helper
Missing helper: "<name>" means <name> isn't in the set above. Compute that value in data.transform and reference the result as a plain variable.
Complete worked example
An agreement document exercising every supported feature. It compiles and renders with only asset_url registered, and performs no computation — every label, flag and formatted value arrives precomputed.
{{! log writes to the server console and emits nothing — debug only }}
{{log 'rendering enterprise agreement'}}
<article class="agreement">
<header class="agreement__header">
<img class="agreement__logo" src="{{asset_url 'company_logo'}}" alt="{{provider.name}} logo">
<h1>{{agreementTitle}}</h1>
<p class="agreement__ref">Reference: {{contract.reference}}</p>
</header>
{{!-- if / else if / else chain --}}
<section>
<p>
This
{{#if contract.isNew}}new subscription agreement
{{else if contract.isRenewal}}renewal agreement
{{else if contract.isAmendment}}amendment
{{else}}agreement
{{/if}}
takes effect on {{contract.effectiveDateLabel}} for a term of
{{contract.termLabel}}.
</p>
</section>
{{!-- with: scope into a nested object --}}
<section class="party">
<h2>Provider</h2>
{{#with provider}}
<p><strong>{{name}}</strong><br>{{address}}</p>
<p>
Signatory: {{signerName}}{{#if signerTitle}}, {{signerTitle}}{{/if}}
<{{signerEmail}}>
</p>
{{/with}}
</section>
{{!-- each over objects, with block params, @first/@last and the
1-based label precomputed in data.transform --}}
<section class="party">
<h2>Customer(s)</h2>
{{#each customers as |customer|}}
<p class="party__row{{#if @first}} party__row--first{{/if}}{{#if @last}} party__row--last{{/if}}">
<strong>{{customer.label}}:</strong>
{{customer.name}}, located at {{customer.address}}
</p>
{{else}}
<p class="party__row party__row--empty">No customers listed.</p>
{{/each}}
</section>
{{!-- unless: the negative branch without a bare else --}}
{{#unless reseller.enabled}}
<p class="note">This agreement is executed directly between the parties, with no reseller.</p>
{{/unless}}
{{!-- inverted section: renders only when the value is falsy/empty --}}
{{^subProcessors}}
<p class="note">The Provider engages no sub-processors under this agreement.</p>
{{/subProcessors}}
{{!-- each with @index (0-based) used as-is, plus a lookup into a
parallel array by the same index --}}
<section>
<h2>Included Services</h2>
<ol class="services">
{{#each services}}
<li>
{{this.name}}
{{#if this.included}}<span class="tick">included</span>{{/if}}
<span class="tier">{{lookup ../serviceTiers @index}}</span>
</li>
{{/each}}
</ol>
</section>
{{!-- each over an OBJECT: @key gives the property name --}}
<section>
<h2>Compliance Certifications</h2>
<dl class="compliance">
{{#each complianceLabels}}
<dt>{{@key}}</dt>
<dd>{{this}}</dd>
{{/each}}
</dl>
</section>
{{!-- each over a flat array of strings: {{this}} --}}
<section>
<h2>Governing Terms</h2>
<ul>
{{#each governingTerms}}
<li>{{this}}</li>
{{/each}}
</ul>
</section>
{{!-- nested each + parent access via ../ --}}
<section>
<h2>Sub-Processors</h2>
{{#each subProcessors}}
<p>{{this.name}} — {{this.purpose}} ({{this.location}})</p>
{{#each this.dataCategories}}
<span class="chip">{{this}} for {{../name}}</span>
{{/each}}
{{/each}}
</section>
{{!-- boolean precomputed in the transform, NOT {{#if (eq tier 'x')}} --}}
{{#if pricing.isPremium}}
<section class="premium">
<h2>Premium Support</h2>
<p>Annual fee: {{pricing.feeFormatted}} ({{pricing.currency}})</p>
</section>
{{/if}}
{{!-- triple-stash: pre-sanitised rich text from the transform.
Double braces would escape the markup. --}}
<section class="clauses">
<h2>Additional Clauses</h2>
{{{additionalClausesHtml}}}
</section>
{{!-- whitespace control: ~ trims surrounding whitespace so the inline
run has no stray gaps --}}
<p class="inline-run">
Total contract value:
{{~#if pricing.totalFormatted~}}
<strong>{{pricing.totalFormatted}}</strong>
{{~else~}}
<em>to be determined</em>
{{~/if~}}
.
</p>
{{!-- partial: shared markup from another Asset --}}
<section class="signatures">
<h2>Signatures</h2>
{{> signature_block provider}}
{{#each customers as |customer|}}
{{> signature_block customer}}
{{/each}}
</section>
</article>
Where $.agreement comes from
agreement isn't a reserved word — it's an input key declared on the Template. Every input becomes a root key in the transform's evaluation context, named exactly by its key:
spec:
type: html
content: enterprise_agreement_html@draft
inputs:
- key: agreement # ← this is the `$.agreement` below
name: Enterprise Agreement Data
schema: enterprise_agreement_schema@draft
data:
transform: |
{ "agreementTitle": ..., "provider": $.agreement.provider, ... }
Declare three inputs and you get three roots. The bundled Common Paper CSA example template declares provider, customer and order_form, and its transform reads $.provider.companyName, $.customer.address.street and $.order_form.effectiveDate.
The data filling each root depends on how the template is being rendered:
| Context | Source of the entity data |
|---|---|
| Preview in Studio | The selected Scenario — its entities[].key must equal the input key |
| A running workflow | The workflow's entity data, mapped from the Blueprint's inputs |
| Direct render API | The entities[] array on the request, keyed by inputKey |
When a Blueprint drives the Template, inputs whose keys match map by name. A document inputMap (template input key → '$.<blueprintInputKey>') replaces that matching entirely: once present, only the inputs it lists are mapped, so list every input — including those whose keys already match.
This is why a scenario whose
keydoesn't match an input key silently produces an empty root —$.agreementresolves to nothing and every field renders blank. The keys have to line up exactly.
The transform that feeds it
Every value the template prints is produced here. Note the date formatting takes no $zoneOffset — effectiveDate is a calendar day, not an instant, so applying an offset would shift it a day.
{
"agreementTitle": "Enterprise Subscription Agreement",
"provider": $merge([$.agreement.provider, {"key": "provider"}]),
"contract": {
"reference": $.agreement.contract.reference,
"isNew": $.agreement.contract.type = "new",
"isRenewal": $.agreement.contract.type = "renewal",
"isAmendment": $.agreement.contract.type = "amendment",
"effectiveDateLabel": $fromMillis($toMillis($.agreement.contract.effectiveDate), "[D] [MNn] [Y0001]"),
"termLabel": $string($.agreement.contract.termMonths) & " months"
},
"customers": $.agreement.customers#$i.$merge([$, {
"key": "customer" & ($i + 1),
"label": "Customer " & ($i + 1)
}])[],
"reseller": { "enabled": $boolean($.agreement.reseller.enabled) },
"services": $.agreement.services[].{ "name": name, "included": included },
"serviceTiers": $.agreement.services.tier[],
"governingTerms": $.agreement.governingTerms[],
"subProcessors": $.agreement.subProcessors[],
"pricing": {
"isPremium": $.agreement.pricing.tier = "platinum" or $.agreement.pricing.tier = "gold",
"currency": $.agreement.pricing.currency,
"feeFormatted": "$" & $formatNumber($.agreement.pricing.subscriptionFee, "#,##0.00"),
"totalFormatted": "$" & $formatNumber($.agreement.pricing.subscriptionFee + $.agreement.pricing.setupFee, "#,##0.00")
}
}
This transform covers the fields used above except
complianceLabelsandadditionalClausesHtml, which are omitted for brevity.
Every array projection ends in []. Without it JSONata collapses a single-element sequence to a scalar, and a one-item list renders blank or duplicated under {{#each}}.
Related
- Assets — authoring HTML assets, partials and styles
- Templates — where
data.transformlives - JSONata Expressions Reference
- Data-First Principle
