Bindings & tokens

A banner shows data that arrives with each notification. A binding is how a template says which data goes where: a string with {token} placeholders, written in a component's binding property. This page explains what a token is, where its value comes from, how values are printed, and what happens when a value is missing. It is for anyone who writes template JSON or designs a banner in the Designer.

Concepts#

A token is a name between braces, such as {title} or {customer.name}. When Herald draws a banner it replaces each token with the value of the field of that name. A binding can be one token, several tokens with text around them, or plain text:

{"type": "text", "binding": "{count} new from {sender}"}

Everything a notification sends is flattened into one dictionary of fields. A token reads one field. Nothing else connects a notification to a banner, so a field a template never names is never shown.

A field is absent when the notification does not send it or sends a blank value. A component whose tokens are all absent is empty, and an empty component can collapse. See Empty values.

Syntax#

Where values come from#

Each source adds fields. An earlier source wins over a later one when two define the same name.

Blank values are left out, so a field that is an empty string is the same as a field that is missing.

image is also present whenever the banner has a picture, for example a preview that was handed one.

Built-in tokens#

These tokens exist without any manifest. Whether they have a value depends on what the notification sent.

Metadata#

metadata carries any data your app wants a template to use. Herald flattens it into fields:

• A string, number or boolean becomes a field with the key's name.
• An object becomes dotted names, up to three levels of nesting: customer.name, customer.address.city.
• An array of strings, numbers or booleans becomes a list.
• null, and arrays that hold objects, are skipped.
• A key that is already taken by an earlier source is skipped.

A key at the top level of a notification request that is not a notification field, such as a manifest field called count, is moved into metadata before any of this. These two requests give the same fields. When a key is in both places, the top-level one wins.

{"app": "example.bidbot", "title": "Bid accepted", "count": 2}

{"app": "example.bidbot", "title": "Bid accepted", "metadata": {"count": 2}}

A request with nested data and the fields it produces:

{
  "app": "example.bidbot",
  "title": "Bid accepted",
  "amount": 4200,
  "metadata": {
    "client": {"name": "Acme", "address": {"city": "Oslo"}},
    "tags": ["rfp", "q3"],
    "note": null
  }
}

Where a token comes from in the Designer#

The Designer files every token it offers under where its value comes from. The sample shown beside a token is what the preview fills it with.

The palette on the left lists the same tokens in smaller groups: Issuer fields, Standard, Seen in notifications, Extra (yours) and Custom.

A fixed picture is the same idea without a token. An image component whose binding is a plain file path shows that file for every notification, and is never empty while the file exists. See Image source.

Formatting#

Values are printed as plain text. Components that need a number or a date read the text.

When the app has a manifest, a field declared number or bool that arrives as text is converted.

How components read their value:

Empty values#

A component is empty when its binding has at least one token and every token is absent. A binding with no token is literal text, and it is empty only when it is blank.

In a binding with several tokens, absent tokens become empty text, literal text stays, and the result is trimmed. Literal text never keeps a component alive.

Write bindings so that a missing part still reads well, or split them into two components that collapse independently. A multi-line text drops a line whose tokens are all absent, and is empty when no line has content.

What each component counts as its binding is on its page under empty values: Components. issuerIcon and spacer never read data and are never empty. A rive cell is empty only when it names no animation. An action label that comes out empty shows the action's id. The full rules for collapsing are in Collapse semantics.

Template default text#

A template's default title, subtitle, body and url use the same token syntax, but they are filled when the notification arrives, from a smaller set of values:

1. metadata, including nested names such as {customer.name}.
2. The notification's own title, subtitle, body, app, id and group.

A token with no value becomes empty text. Only text that comes from the template is filled. A notification's own text may contain braces, and they are left alone. In a url, each substituted value is percent-encoded.

Sample values#

The Designer, POST /v1/preview with "data": "sample" and the MCP tool render_preview fill fields from the sample values in the app's manifest. A declared field with no sample gets a stand-in:

Without a manifest, only a generic title, subtitle and body exist.

Where tokens may be used#

Declared fields and warnings#

The manifest tells the Designer and the validator which tokens an app sends, with a type and a sample. See Manifests. With a manifest, the validator warns about a token the manifest does not declare:

token {sender} is not declared in the manifest (it only resolves if the issuer sends it)

The warning does not block saving, because a notification can still send the field in metadata. The validator also warns when {extra.key} has no matching key in the template's extra.

Related#

• Grid, cells and layout: where components and their bindings sit.
• Template guide: bindings in a worked template.
• Design a banner in the Designer: the Insert field menus and the palette.
• Manifests: declaring the fields an app sends.
• Components: each component's bindings and empty behaviour.