Inputs: hover, click, values

Name: Herald
Author: IVG Design

Inputs and how fields drive them#

inputBindings connects a state machine input to a piece of the notification, so the animation follows the data. Each entry maps an input name to a binding. This section explains what a binding can be and what value each kind of input receives.

JSON

{"type": "rive", "asset": "bell", "height": 40,
 "inputBindings": {"count": "{count}", "isUnread": "{unread}", "ring": "{count}",
                   "hover": "hover", "pressed": "pressed"}}

The key is the name of the input in the Rive file. The value is the binding:

Binding	Value written
`hover` or `pressed`, in any case.	Driven by the pointer, never by data.
A single token such as `"{count}"`.	The field's own value, so a number stays a number and a list stays a list.
Anything else, such as `"3"` or `"{n} new"`.	The substituted text.
Tokens that are all absent or blank.	Nothing. The input keeps whatever the animation set.

How each kind of input reads the value it is given:

Input	From a number	From a Boolean	From text	From a list
Number	The number.	1 or 0.	The number if the text parses, else ignored.	Its length.
Boolean	True when not zero.	The value.	False only for empty, `false`, `no`, `off` or `0` in any case.	True when not empty.
Trigger	Fires when not zero.	Fires when true.	Fires unless the text is empty, `false`, `no`, `off` or `0`.	Fires when not empty.

Two behaviours are worth knowing before you design a trigger:

Only changed values are written. Herald remembers what it last wrote to each input, so a redraw from hover or a timer never fires a trigger again. A trigger bound to {count} fires when the count changes to a truthy value, so a banner updated under the same id (count 2, then 3) rings again.
The first value counts. Inputs are written as soon as the animation loads. A trigger bound to a field that is truthy on the first notification fires once when the banner appears.

The tokens come from the notification's fields. Bindings explains token syntax.

Worked example: a bell that rings on new mail#

This example builds a bell that rings each time the unread count goes up and reacts to the mouse. It uses the fictional app example.bidbot and runs end to end: make the file, store it, check it, design the template and send two notifications.

1. In Rive. Build the file:

Make an artboard named Bell, 64 x 64, with a transparent background.
Add a state machine Main with a Number input count, a Boolean input hover and a Trigger ring.
Add a "ring" state that plays when ring fires or when hover is true.
Export bell.riv with its assets embedded.

2. Store it. Declare the file in the manifest with the asset example from Declare it in the manifest, setting inputs to ["count", "ring", "hover"], and save the manifest. Herald copies the file to assets/example.bidbot/bell.riv.

3. Check it. Run the request from Testing without a window with "inputBindings": {"count": "{count}", "ring": "{count}", "hover": "hover"}. Expect loaded to be true and your three inputs in inputs. Fix names until applied shows what you expect.

4. Write the template. The bell sits in a 48-point column. A text cell, a badge and an action row complete the banner:

JSON

{"name": "bid-bell", "app": "example.bidbot", "layoutVersion": 2, "collapseEmpty": true,
 "grid": {"rows": 3, "cols": 3, "rowSizes": ["auto", "auto", "auto"],
          "colSizes": ["48", "fill", "auto"], "gap": 8, "padding": 14, "width": 400},
 "cells": [
  {"id": "bell", "row": 0, "col": 0, "rowSpan": 2, "align": "topLeading",
   "component": {"type": "rive", "asset": "bell", "stateMachine": "Main", "height": 40,
                 "inputBindings": {"count": "{count}", "ring": "{count}", "hover": "hover"},
                 "action": {"id": "open", "label": "Open", "kind": "url", "url": "{url}"}}},
  {"id": "title", "row": 0, "col": 1,
   "component": {"type": "text", "binding": "{title}", "style": "title", "maxLines": 2}},
  {"id": "count", "row": 0, "col": 2, "align": "topTrailing",
   "component": {"type": "badge", "binding": "{count}", "color": "#FF3B30"}},
  {"id": "subject", "row": 1, "col": 1, "colSpan": 2,
   "component": {"type": "text", "binding": "{subject}", "style": "subtitle", "maxLines": 2}},
  {"id": "acts", "row": 2, "col": 0, "colSpan": 3,
   "component": {"type": "actions", "source": "merged", "layout": "wrap"}}]}

5. Preview and send. render_preview shows a stand-in where the bell is. send_test or herald notify shows the real banner. Send the same id twice with a higher count the second time, and the bell rings again:

shell

herald notify --app example.bidbot --id inbox --template bid-bell --title "2 new bids" \
  --metadata '{"count": 2, "subject": "Acme RFP", "url": "https://example.com/bids"}'
herald notify --app example.bidbot --id inbox --template bid-bell --title "3 new bids" \
  --metadata '{"count": 3, "subject": "Acme RFP, revised", "url": "https://example.com/bids"}'

The first banner rings once on appearance, because ring is bound to a count that is already truthy. The second replaces the first in place, and ring fires again because the value changed from 2 to 3.

Edit this page on GitHub