builtins — the built-in variables (@app / @i18n / @env / @device / @time / @contentInset / @safeArea / @window / @fetch / @event)

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

What it is

A set of root variables starting with @, injected by the platform so you never pass them yourself: which device this is, which language, what time it is now, how wide the container is, whether what is on screen is fallback data. They live in a different namespace from the package's own data — a field called time inside the package and @time can never overwrite each other.

You read them like any other variable: ${@time.nowMs}, ${@window.width}, and they work inside method arguments too: $[formatDate::(${@time.nowMs},HH:mm)].

Two things to get straight first:

• Not every root exists in every file type. Write a root that is not available where you are and it evaluates to empty, with no error — the symptom is a blank slot, or a condition that is permanently false. Every root below states which files it is available in.
• @i18n is readable in both .df and .af (the host page's table ⊕ this file's top-level i18n table); the language built-ins (@app.language / @device.language / @time.locale) may be read in a .df as well. How to fetch by language and produce text in the data layer is in numable docs i18n.

A minimal working example

In a widget's RCN: the time anchor, a fallback hint, and a width that follows the container:

{
  "type": "txt",
  "id": "anchor",
  "x": "16pt", "y": "12pt", "w": "${@window.width}pt",
  "text": "$[if::(eq::(${@fetch.stale},1),${@i18n.stale},formatDate::(${@time.nowMs},HH:mm))]"
}

How to write it (root by root, key by key)

@app — the app itself

⚠️ @app carries different things in the two families of files: in rendering and event files (.rcn / .xpage / .xform / .af), @app guarantees only language and locale (.af also has region) — the environment keys above cannot be read there. To branch on platform, read ${@app.platform} in the .df, land the conclusion in a top-level key and expose it (isIos = $[eq::(${@app.platform},ios)]); the rendering layer looks only at that key.

region is the region this device is distributed under. It comes from the install channel; it is not the language, and it does not say whether a given site is reachable: cn = mainland China, overseas = everywhere else, an empty string = unknown. Typical use: when a data flow has a fallback source that cannot be reached from mainland China, skip it under cn rather than making the user wait out a timeout first.

country, firstWeekday and upColor are this device's conventions: country is the region from the system settings (not the store front, not the current location), firstWeekday is the day the system calendar starts the week on (always Monday in China), and upColor is the up/down color the user picked under Me (on Automatic: red for up in China, green elsewhere). Any of the three can be empty (older app versions don't have them), so always read them with a fallback — for the up color write $[if::($[ne::(${@app.upColor},)],$[eq::(${@app.upColor},red)],$[startsWith::(${@app.language},zh)])], and when the week start is empty use 1 in China and 7 elsewhere. Switching the up/down color makes widgets fetch again, just like switching the language.

@i18n — the content table for the current language

${@i18n.<key>}, and the value is a string. Which table you can read depends on the file type; the rules, the fallback chain and the meaning of an empty string are all in numable docs i18n and not repeated here. The two people hit most: a key cannot be assembled dynamically, and a reference that cannot be resolved is displayed on screen verbatim.

In a .df / .af you read the host page's table ⊕ this file's top-level i18n table; a flow attached directly to a .xwidget has no host table, only its own.

@env — the runtime environment

Use it to log while developing, or to point temporarily at a test endpoint. Do not leave it in a published package as a switch: what users install is always the release branch, so the other branch is dead code.

@device — the device

⚠️ The host may replace @device wholesale with a root of the same name (in a data flow driven by a page it often carries platform and nothing else). So do not branch on device details inside a data flow; if you really must branch, land the decision in an explicit top-level key, or have the caller pass it in as a parameter (see numable docs params).

@time — time

• nowMs is cached within a single evaluation: reference it several times in one expression (or even across one render pass) and you get the same value every time. To work out "how long ago", subtract the timestamp in the data from nowMs; do not expect two reads to differ.
• Remember to guard the time anchor against empty; the pattern is in "The six rules you must keep" in numable docs df.

@contentInset / @safeArea / @window — container geometry

Where they work: XPage nodes, the .rcn of a canvas inside a page, and the params of an .af event binding. A data flow (.df) has none of the three — write one there and it evaluates to empty, so every size you compute comes out as 0.

• To stay clear of the UI, always use @contentInset. Reading @safeArea runs you into the floating capsule: on a large screen the container does not touch the edge of the screen, so @safeArea is only 5 at the top and 0 on the other three sides, while the capsule still floats right there.
• All three are values that change (folding, rotation, split screen and the keyboard all re-issue them), so do not cache them into a key of your own as if they were first-frame constants.
• A page normally needs none of them: the container already lays the content out in the right place. Only a page that needs fine control (a hero image running up under the status bar, say) reads them.
• @window.width is the container width, not the screen width. On a large screen the container is a single phone-width column of widgets, and drawing to the screen width draws outside it.

@fetch — is the data on this screen fresh

It always has a value and is never absent, which makes eq::(${@fetch.stale},1) a reliable test. The typical use is to swap the time anchor for a "last updated …" line, rather than leaving the user to read a stale number as if it were live:

{ "type": "txt", "id": "tip", "x": "16pt", "y": "40pt",
  "text": "$[if::(eq::(${@fetch.stale},1),${@i18n.stale},${at})]" }

⚠️ It means the fetch failed and fell back, not "this data came from a cache". Switching theme is a pure re-render that by design does not fetch, and there it is 0; switching language refetches, and after a successful fetch it is 0 as well. The data cache is split by language: after a switch there is no old data for the new language to fall back to, so a failed fetch shows the widget's empty or error state rather than stale=1.

@event — what this interaction brought with it

Only an .af action flow has it, and the keys differ by touchpoint (which element was tapped / what was typed / which page was swiped to). The full table is in numable docs af and is not repeated here.

Rules (breaking one means rework)

When something goes wrong

See also

numable docs i18n · numable docs af · numable docs df