af — action flows (.af) and the full action table

Audience: people building a tool, and the AI working on their behalf. Both read this same page.

What it is

.af is the flow that runs after the user moves a finger: tapping a widget, long-pressing to edit, pressing a button on a page, submitting a form. It is allowed to have side effects — show a toast, fire haptics, open a page, write local data, write parameters back to a widget, make a widget fetch again.

It runs on the same ActionFlow engine and the same syntax as the data flow .df; there is exactly one dividing line: .df is an allowlisted subset with zero UI, zero navigation and zero App-injected capability; .af is the full set. Fetching goes in .df, side effects go in .af. The extension is the capability declaration: get it wrong and the App answers "flow not found" outright (check G12b). For data-flow syntax, see numable docs df.

The engine then cuts again by carrier, and this cut is harder than the extension:

So "show a toast while fetching / refresh myself while fetching" is impossible. Writing it raises no error; that step simply does not exist.

A minimal working example

The flow that runs when "Save" is pressed on a page (page/flow/save.af). Write to disk, then make this package's widgets fetch again: this is the most common shape of an .af.

{
  "version": 1,
  "actions": [
    { "action": "ui.haptic", "params": { "type": "tap" } },
    { "op": "set", "props": { "key": "lk", "value": "log_${id}" } },
    { "op": "set", "props": { "key": "sk", "value": "stat_${id}" } },
    { "action": "data.set", "params": { "key": "${lk}", "value": "${log}" } },
    { "action": "data.set", "params": { "key": "${sk}", "value": "${stat}" } },
    { "action": "data.set", "params": { "key": "agg", "value": "${agg}" } },
    { "action": "widget.refresh" }
  ]
}

Line by line: ui.haptic sits at actions[0] (nothing else gives feedback between the press and the screen changing) · op:set lands the dynamic key names as variables first · three data.set calls write to disk · finally widget.refresh makes this package's widgets really fetch and repaint. Every write must come before widget.refresh, otherwise the refresh reads the old disk.

File format

{
  "version": 1,                                  // required, always 1
  "inputs": ["secid", "period"],                 // optional; declares expected inputs, static check only
  "i18n": { "zh-CN": { "k": "文案" },            // optional: this file's own content table (A), read with ${@i18n.k}
            "en-US": { "k": "text" } },
  "actions": [ /* the array of steps */ ]
}

A _note field may appear anywhere; it is prose for humans and AI, and the engine ignores it.

The three shapes a step can take

A composite step written as {"op":"concurrent"} is skipped silently as a whole — the flow still reports success and not one action inside it ran.

policy (optional, set on a step): wait (default, wait for it) / detach (don't wait) / skip (skip it).

params are evaluated recursively: strings go through the expression engine, object keys are evaluated too, arrays element by element; when a whole-value @[…] reference cannot be resolved it is passed through literally. For expressions and methods, see numable docs methods.

id = the result key

An action step with an id writes its result into scope under that key, and you read it later with ${id.xxx}. The result is discarded in two cases: no id; or the result is null or undefined.

The second one is the most common source of silent failure: if data.get finds nothing and you did not write a default, that key never appears in scope at all, and every downstream ${k} is permanently empty without an error. Always write a default on data.get.

Except across concurrent branches, a written key is visible to the very next step.

The four shapes of an inline flow binding

A node's depends, the value of an events entry, and an onSubmit binding all use one of these four shapes:

"depends": [
  { "flow": "@[file://page/flow/quote.df]", "params": { "secid": "${secid}" } },  // ① file reference + inputs (recommended)
  { "flow": { "version": 1, "actions": [ … ] }, "params": { "x": "${y}" } },      // ② inline object
  "@[file://page/flow/noop.df]",                                                   // ③ bare reference, inputs = {}
  { "op": "set", "props": { "key": "cards", "value": [] } }                        // ④ bare inline single step
]

flow written as an array does nothing. The bare-reference shape passes empty inputs — if the flow needs inputs and you write shape ③, it still succeeds and the widget paints a wall of -- (check G12c). Keys that are not used for fetching but do get displayed (a city name, say) must also be listed in params.

The path base of @[file://…] follows the carrier

The symptom of a wrong base is "tapping does nothing": the App reads no actions and ends silently (check G12d).

The full action table

Built into the engine (the .df column = also usable in render flows / data flows)

data.* has no scope parameter; writing one is ignored silently. The data domain is isolated per package, and the host injects the identity.

For loading and toasts on a page, use the App-injected ui.showLoading / ui.toast below (they take text and a type), not the built-in showLoading / toast.

⚠️ The two toasts differ in both the parameter name and the accepted values; mixing them up is silent — you just get no styling:

So ui.toast has no warning and the built-in toast has no info; putting style on ui.toast, or type on the built-in toast, is treated as if you had written nothing and falls back to the default style. In an event flow, always use ui.toast.

App-injected (event flows only)

"no-op" = callable but does nothing (there is no page to change on a widget host).

Names to stop writing

operation nodes

op:include is the one entry in this table that will not run: the flow engine does not implement its expansion, so that step always expands to zero child steps while the flow still reports success. To reuse shared steps there are exactly two routes: copy the steps, or split them into a separate .df and bind one more entry in depends (see the multiple depends in numable docs xwidget).

Two things you must remember:

1. The condition key of op:if is props.val. Writing cond means the condition is permanently false, the entire branch body silently never runs, the flow still reports success, and everything outside the branch works normally — only the writes inside the branch never happened (check G30).
2. Keys produced by op:set inside an op:if branch are gone once the branch ends. Leaving the branch restores the outer bindings. So: compute values with a nested if:: expression, and use op:if only to dispatch actions.

events: where an .af can be attached

onClick / onEdit in .xwidget

events has exactly these two keys, written on the outer shell of .xwidget (not inside canvas). For field details see numable docs xwidget.

"events": {
  "onClick": "/detail?secid=${secid}",
  "onEdit": "/pick?ref=board&base=${base}"
}

If the value resolves to a string it is treated as a navigation string; if it is a structure (@[file://x.af] or an inline object) it runs as an ActionFlow. A bare flow filename is not allowed.

The four legal forms:

• When onEdit navigates it must be a bare route path (/pick), never the numable:// form — the App matches that string against router.json verbatim, and a miss opens a blank page with no error (check G12d). onClick accepts both forms.
• onEdit may target an html / xpage / form page, but you must be able to prove it can write back (check G12e).
• The path base of the af form is xWidget/.
• ${…} inside a navigation string only reads top-level scalars; the scope, from lowest to highest precedence: shell params → instance params → local data → the depends result set.

When a whole-widget onClick / onEdit runs an af, its inputs are that widget's instance params + @i18n (only this af file's own table) + @app — there is no @event. The widget was tapped as a whole; there is no "which element".

@event.* (XPage nodes / RCN cells / forms)

For how to read @i18n, see numable docs i18n.

The primitives you will use

widget.refresh — make a widget really fetch

{ "action": "widget.refresh", "params": { "scope": "bundle", "widgetId": "streak", "desktop": true } }

• The semantics are clear the fetch timer + really fetch + repaint, not reload. A reload would hit the render-image cache, which means nothing was refreshed at all.
• Returns { refreshed: <count> }. Matching 0 widgets is a success, not an error.
• Called again inside the 5000 ms throttle window, it returns { refreshed: 0 } immediately.
• It does nothing across packages; render flows refuse it outright; it is unavailable in .df.
• The errors (no_brick_context / no_bundle_context / unknown_scope / widget_not_in_bundle) fail the whole flow.
• You must call it after writing to disk, with every data.set ahead of it (manual review; the run layer cannot see this, and the symptom is "I changed the setting and the widget didn't move").

widget.updateParams — write values back to the widget instance

{ "action": "widget.updateParams", "params": { "city": "${r.value.value}", "sub": null } }

• The top-level object is the params to merge; do not wrap it in another layer. Merged key by key: a value overwrites, null deletes the key and falls back to the default in .xwidget.
• Values must be scalars, and they are normalized to a standard form: 1.0 → "1", true → "true". Passing an object or array errors immediately (non_scalar_value).
• Returns { params }; a failure (no_brick_context / non_scalar_value / brick_not_found) fails the flow.
• Only reachable from an onEdit af. A whole-widget onClick flow has no widget-instance context, so calling it there always fails. An html parameter page uses the bridge's xbridge.updateParams (see numable docs bridge); every other page type uses this action.
• Render flows refuse it outright.

The usual chain: onEdit: "@[file://flow/edit.af]" → singleValue or startPageForResult collects one value → widget.updateParams writes it back. The whole thing needs no page of your own.

startPageForResult — open a page and wait for its value

{
  "id": "picked",
  "action": "startPageForResult",
  "params": { "page": "/for-result-pick", "container": "sheet", "params": { "secid": "${secid}" } }
}

The output is always { value, cancelled }; read ${picked.value.xxx} and ${picked.cancelled}.

It handles all three page types: xpage / html / form. How a child page returns a value:

The user pressing ✕ or ‹, tapping the scrim, or using the system back gesture is a cancel: it does not go through onSubmit, and the host delivers { value: null, cancelled: true } directly. Cancelling is a normal path — always test cancelled before you use value.

ui.confirm — a confirmation step that hands back a boolean

{ "id": "ok", "action": "ui.confirm",
  "params": { "title": "Clear every record?", "message": "This cannot be undone", "okText": "Clear", "destructive": true } }

Feed ${ok} straight into an op:if afterwards:

{ "op": "if", "props": { "val": "${ok}" },
  "items": [ { "action": "data.clear" }, { "action": "widget.refresh" } ] }

• ok is a real boolean, so put it directly in props.val.
• ⚠️ Do not convert it to a number first. The truthiness test behind props.val is narrow: a boolean is itself, a string counts only as 1 / true / on / yes / y (case-insensitive), and a number is true only when it is exactly 1 (2 and -1 are both false). Code that computes a 2 and assumes "there is something there" walks silently into the false branch while the flow reports success.
• destructive: true colours the confirm button red; use it for operations you cannot come back from, such as deletion.
• It waits for the user, and that wait does not count against the event flow's 15-second timeout.

ui.alert — a one-button notice that waits to be dismissed

{ "action": "ui.alert", "params": { "title": "Already checked in today", "message": "Come back tomorrow" } }

It returns nothing. Use ui.toast to say something in passing (no interruption); reach for ui.alert only when the user has to acknowledge it before anything continues.

ui.presentSheet — raise a child page from the bottom

{ "id": "r", "action": "ui.presentSheet",
  "params": { "source": "/detail", "params": { "id": "${id}" } } }

It returns exactly the object the child page passed to page.setResult, or null if the page was closed. It is the primitive underneath startPageForResult — write startPageForResult instead in normal code: its return value is normalized to { value, cancelled }, so you never have to guess whether a null meant "cancelled" or "returned nothing".

nav.openForResult — push a page onto the stack and wait for its value

{ "id": "picked", "action": "nav.openForResult",
  "params": { "url": "/city-pick", "params": { "cur": "${city}" } } }

Also a primitive underneath startPageForResult, except that it always pushes onto the stack (equivalent to container: "page") and returns the bare result or null. New flows should always use startPageForResult; these two primitives remain for packages that already call them.

xpage.setState and patchState — change page data

Both take "the whole params object is the table"; there is no value wrapper:

{ "action": "xpage.patchState", "params": { "tab": "week", "loading": "0" } }

The most common mistake is using setState where patchState was meant: you change one tab value and clear every other key on the page, and the symptom is that unrelated content suddenly goes blank.

Once the state is changed, decide how much to repaint:

{ "action": "xpage.patchState", "params": { "tab": "week" } }

{ "action": "xpage.redraw", "params": { "id": "chart" } }

There is also xpage.const: it writes top-level variables into this flow's own scope (later steps read them with ${name}), not into page state, so nodes on the page cannot see them. Use patchState when the page has to see the value.

input.* — drive an input box imperatively

An input node's value normally writes itself into page state silently (the key is props.bindKey, defaulting to the node id). These five are for moving it from a flow:

{ "action": "input.focus",     "params": { "id": "kw" } }

{ "action": "input.setValue",  "params": { "id": "kw", "value": "${@i18n.preset}" } }

{ "action": "input.clear",     "params": { "id": "kw" } }

{ "action": "input.selectAll", "params": { "id": "kw" } }

{ "action": "input.blur",      "params": { "id": "kw" } }

• id is the node id, not the bindKey.
• input.setValue also updates the state the bindKey points at, exactly as if the user had typed it.
• Where there is no input host (a widget's event flow), all five spin without effect and without an error.
• Dismissing the keyboard is a separate action, ui.dismissKeyboard (no parameters); it does not touch the value: { "action": "ui.dismissKeyboard" }.

widget.pick — open the "add to dashboard" panel

{ "action": "widget.pick",
  "params": { "items": [ { "id": "today", "params": { "habit": "water" } }, { "id": "streak" } ] } }

• Omitting items lists every widget in this package; supplying it lists only those, each with its own instance parameters.
• id is the file name of xWidget/<name>.xwidget (without the extension).
• If not one id matches, this step fails (no_matching_widget); it does not fall back to "list them all". So when you rename a widget file, remember to update this too.
• Returns { listed: <how many were listed> }.
• ⚠️ The write happens on the button inside the panel, not in this step. After calling it, do not say "Added" — the user may well browse and close (check G24).

installBundle — propose installing another package

{ "action": "installBundle", "params": { "id": "01M050AARQ0R08T9EHGDSGZBHJ" } }

id is required (the target package's ULID); version / ref are optional. All it does is raise the install panel; whether anything gets installed is the user's decision inside that panel, and the flow never learns the outcome (the return value is always null). As with widget.pick: do not say "Installed" after calling it.

page.close — close this page

{ "action": "page.close" }

No parameters. On a page opened by ordinary routing it really closes the page; on a child page opened by startPageForResult it dismisses the overlay and delivers { value: null, cancelled: true }. To close with a value use page.setResult, which closes the page itself — no extra page.close needed.

Form input

Use singleValue for one value; collect several fields at once with a .xform page.

{
  "id": "r",
  "action": "singleValue",
  "params": {
    "container": "page",
    "title": "Pick from a list",
    "desc": "Subtitle",
    "confirmTxt": "OK",
    "component": {
      "type": "select",
      "value": "b",
      "props": { "items": [ { "label": "Option A", "value": "a" }, { "label": "Option B", "value": "b" } ] }
    }
  }
}

container is required (page / sheet / dialog). It returns { value: { value: <string | array | null> }, cancelled }, so the value lives at ${r.value.value} — one layer deeper than you'd expect.

A .xform is a page of type form, opened with startPageForResult, and it does not write its own container (the caller decides which of the three). The keys of form are the result keys, and declaration order is render order; the flow bound to onSubmit sees only @event.value. For the full field-type table, props, and value shapes, see numable docs params.

nav.open and jumping to an external App

{
  "id": "r",
  "action": "nav.open",
  "params": { "url": "futunn://quote/00700", "fallback": "https://www.futunn.com/stock/00700-HK" }
}

The order of decisions: dangerous-scheme denylist (javascript / file / data / intent / about / blob, check G16) → gesture gate (anything outside the 10-second window after a real user gesture is refused silently, without even a dialog) → this package's remembered authorization for that scheme → the first-jump confirmation dialog. Authorization is remembered per (package, scheme), never enters a backup, and is cleared on uninstall.

Five possible return values: opened · no-handler · denied · fallback · presented (returned immediately, without waiting, when container is sheet or dialog).

• fallback is optional and only accepts http(s) (check G16); it fires only for an external App with no-handler. A user refusal (denied) never falls back.
• nav.open waits for the user and is marked interactive; a waiting action that is not marked interactive will hit the event flow's hard 15-second timeout.
• Any ${…} spliced into the URL after the scheme needs $[urlEncode::(…)] around it (check G16, warning level).
• numable://self does not work inside nav.open — it round-trips through the system scheme, and the receiving end has no "which package am I" context, so you get "the tool 'self' is not installed". self is only valid in in-page routing; to open your own package from a flow, write this package's ULID literally: {"action":"nav.open","params":{"url":"numable://01M050AARQ0R08T9EHGDSGZBHJ"}}.

Rules (break one = rework)

When something goes wrong

For more silent failures, see numable docs pitfalls.

See also

• numable docs df — the data flow's allowlist and syntax
• numable docs xwidget — where events attaches, and where instance params come from
• numable docs params — the full form field-type table and .xform