xpage — declarative pages (.xpage)

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

What it is

.xpage is "RCN for a whole page": one JSON file is a node tree, containers place things and leaves draw things. It sits alongside html pages and is selected by type: "xpage" on that route in page/router.json (for how to write routes, see numable docs page).

There is exactly one reason to pick it: you want the page to speak the same visual language as the widgets. Detail pages, chart pages, tab pages, paginated lists — written this way they use the same render core, the same .rcn drawing model and the same light/dark pairs as a .xwidget. Conversely, forms, long-form text and anything you want to lay out with the DOM are less work as an html page.

Two structural differences from html pages shape how you write it:

• No WebView, and no xbridge: fetch data by writing depends on a node to bind a .df, and handle interaction by writing events on a node to bind an .af.
• @[file://…] is relative to the package root: both the .xpage and the page/rc/*.rcn files it references must spell out page/flow/x.df, page/rc/x.rcn. Writing flow/x.df resolves to nothing — no fetch, nothing drawn, and no error.

A minimal working example

page/xpage/detail.xpage:

{
  "type": "page",
  "id": "detail",
  "i18n": {
    "zh-CN": { "empty": "还没有数据" },
    "en-US": { "empty": "Nothing yet" }
  },
  "root": {
    "type": "container",
    "id": "root",
    "layout": "list",
    "direction": "vertical",
    "padding": "16pt",
    "gap": "12pt",
    "paddingTop": "${@contentInset.top}pt",
    "paddingBottom": "${@contentInset.bottom}pt",
    "depends": [{ "flow": "@[file://page/flow/detail.df]", "params": { "id": "${id}" } }],
    "events": { "onLoad": "@[file://page/flow/mark-read.af]" },
    "items": [
      {
        "type": "Canvas",
        "id": "hero",
        "h": "120pt",
        "params": { "title": "${title}", "sub": "${sub}" },
        "canvas": { "source": "@[file://page/rc/hero.rcn]" }
      },
      {
        "op": "forEach",
        "props": { "items": "${rows}", "key": "r", "index": "i" },
        "items": [
          {
            "type": "Canvas",
            "id": "row-${r.id}",
            "h": "56pt",
            "params": { "label": "${r.label}", "value": "${r.value}" },
            "events": { "onClick": "@[file://page/flow/open-row.af]" },
            "canvas": { "source": "@[file://page/rc/row.rcn]" }
          }
        ]
      }
    ]
  }
}

The shell and the root

The shell has only four keys, three of them required:

The shell has no depends / events / layout / state / width. Page-level fetching is the depends on root, the page lifecycle is the events on root, the width is always given by the container, and the presentation belongs to router.json.

The page title goes on root (optional): "title": "${detail.name}". Once the page scrolls past its header, the container shows a small title in the pill row, and this is where it comes from. It is evaluated against everything the root node can read (route params, state, data, the output of the root's depends) and recomputed on first paint, on every redraw and when the root's fetch returns, so the title follows the data; if it evaluates to empty, it falls back to name / title in the route query, then to the router.json title and the package name (see numable docs page). You can leave it out — users then see the route title after scrolling.

There are only two kinds of node:

• container: {type:"container", id, layout, items, …}. items may mix containers, leaves and op operations (forEach / if / set).
• leaves: only two — Canvas (one piece of RCN; for how to draw see numable docs rcn) and input (a bare input, below).

id must be unique within the page; nodes generated by forEach stay unique through interpolation ("id": "row-${r.id}"), because a duplicate id makes a redraw land on the wrong cell.

Besides canvas.source, a Canvas leaf can carry its own canvas.depends (re-fetch only this block without disturbing the page) and canvas.refresh (timed re-fetch; for the syntax and the floor see numable docs xwidget):

{
  "type": "Canvas",
  "id": "quote",
  "h": "96pt",
  "canvas": {
    "source": "@[file://page/rc/quote.rcn]",
    "depends": { "flow": "@[file://page/flow/quote.df]", "params": { "code": "${code}" } },
    "refresh": { "interval": ["300"] }
  }
}

Making room at the top

The container chrome is a floating capsule and it reserves no space for the page. The root container has to make room itself:

{
  "paddingTop": "${@contentInset.top}pt",
  "paddingBottom": "${@contentInset.bottom}pt"
}

• Read @contentInset, not @safeArea: the former is the safe area plus the chrome's footprint, the latter is the bare system safe area, which is always 0 inside an overlay widget — write that and a large screen will cover your content. For the difference between the two and the rest of the built-in variables, see numable docs builtins.
• G17 in numable check catches a missing inset; if you really want content to run to the very top (a full-bleed hero header, say), write "_lintTopInset": "exempt" and state the reason in _notePad.
• Each side has its own key: paddingTop / paddingBottom / paddingLeft / paddingRight; whichever you write overrides padding on that side. Making room at the top only touches paddingTop — the left and right are still yours to set.
• The root can't be layout: "pager": the pager branch ignores padding entirely, so the inset you wrote has no effect — G17 catches this too. For tab paging, use a list as the root and put the pager inside it.

The eight layouts

layout is required. The default is flex, not list — a scrolling list that forgot its layout becomes a vertical flex with no spacing, which looks like "gap isn't working".

Each layout only understands its own fields; fields belonging to another layout raise no error and do nothing.

absolute — free anchoring

Children position themselves with x/y/w/h (plus r for the right edge and b for the bottom) and support geometry expressions: {parent.w}, sibling anchors {sibling_id.r}, arithmetic, and pt/px.

{
  "type": "container",
  "id": "hero",
  "layout": "absolute",
  "h": "220pt",
  "items": [
    { "type": "Canvas", "id": "bg", "x": "0pt", "y": "0pt", "w": "{parent.w}", "h": "{parent.h}", "canvas": { "source": "@[file://page/rc/bg.rcn]" } },
    { "type": "Canvas", "id": "badge", "x": "{bg.r}-72pt", "y": "16pt", "w": "56pt", "h": "24pt", "canvas": { "source": "@[file://page/rc/badge.rcn]" } }
  ]
}

{parent.h} is only available when the parent's height is known (the parent declared h, or the parent is the page root). If the parent's height is content-driven, referencing it can't be resolved and falls back to auto.

stack — overlay

Children cover each other, items order is bottom to top, and positioning comes from align on the child — no coordinates.

{
  "type": "container",
  "id": "card",
  "layout": "stack",
  "h": "160pt",
  "items": [
    { "type": "Canvas", "id": "bg", "align": "fill", "canvas": { "source": "@[file://page/rc/bg.rcn]" } },
    { "type": "Canvas", "id": "tag", "align": "bottom|right", "w": "88pt", "h": "28pt", "canvas": { "source": "@[file://page/rc/tag.rcn]" } }
  ]
}

align is matched as a substring, not an enum, and three rules cover it:

The default is top|left|fill. Because matching is by substring, words like middle and middleCenter mean nothing at all and silently fall back to the default. A child that isn't fill must write its own w, or it gets stretched to the full width.

flex — sequential placement

Only two fields do anything: direction (vertical by default / horizontal) and gap. Horizontally, children use their own w, and share the space equally if they don't declare one.

{
  "type": "container",
  "id": "tabbar",
  "layout": "flex",
  "direction": "horizontal",
  "padding": "12pt",
  "gap": "8pt",
  "items": [
    { "type": "Canvas", "id": "tab0", "w": "112pt", "h": "44pt", "params": { "label": "Quotes" }, "events": { "onClick": "@[file://page/flow/tab0.af]" }, "canvas": { "source": "@[file://page/rc/tab.rcn]" } },
    { "type": "Canvas", "id": "tab1", "w": "112pt", "h": "44pt", "params": { "label": "Watchlist" }, "events": { "onClick": "@[file://page/flow/tab1.af]" }, "canvas": { "source": "@[file://page/rc/tab.rcn]" } }
  ]
}

wrap / justify / align, and flexGrow / flexShrink / flexBasis on children, are not implemented and do nothing. For wrapping use flow; for centering, compute w and padding yourself.

flow — wrap when full

For tags, chips and other naturally flowing blocks. Fields: itemSpacing (spacing between items, default 8) and lineSpacing (spacing between lines, default 8). Children declare their own w (80 is assumed when absent) and wrap to the next line when they no longer fit.

{
  "type": "container",
  "id": "tags",
  "layout": "flow",
  "itemSpacing": "8pt",
  "lineSpacing": "8pt",
  "items": [
    { "type": "Canvas", "id": "t1", "w": "72pt", "h": "28pt", "params": { "label": "A-shares" }, "canvas": { "source": "@[file://page/rc/tag.rcn]" } },
    { "type": "Canvas", "id": "t2", "w": "96pt", "h": "28pt", "params": { "label": "HK stocks" }, "canvas": { "source": "@[file://page/rc/tag.rcn]" } }
  ]
}

lineAlignment and maxLines are not implemented.

list — single-axis collection

The one you'll use most, and the default choice for a page root.

A horizontal band:

{
  "type": "container",
  "id": "band",
  "layout": "list",
  "direction": "horizontal",
  "h": "120pt",
  "itemSpacing": "8pt",
  "edgeInsets": "16pt",
  "snap": true,
  "items": [
    { "type": "Canvas", "id": "s1", "w": "140pt", "h": "120pt", "params": { "label": "1" }, "canvas": { "source": "@[file://page/rc/slot.rcn]" } },
    { "type": "Canvas", "id": "s2", "w": "140pt", "h": "120pt", "params": { "label": "2" }, "canvas": { "source": "@[file://page/rc/slot.rcn]" } }
  ]
}

Children of a horizontal list take their own w (omit it and one item fills the screen), the content scrolls horizontally when it overflows, and it scrolls without requiring an h — the "needs a fixed height to scroll" rule is vertical-only. ⚠️ A horizontal list does not support onReachEnd, so there is no horizontal infinite scroll.

pager — paging

The paging axis is always horizontal. Each page is a container, and a page runs its own depends only when you first turn to it, so "one data set per page" needs no nested pages.

{
  "type": "container",
  "id": "pager",
  "layout": "pager",
  "h": "300pt",
  "pageSize": "280pt",
  "pageSpacing": "12pt",
  "loop": "true",
  "page": "${activeTab}",
  "events": { "onPageChange": "@[file://page/flow/tab-sync.af]" },
  "items": [
    { "type": "container", "id": "p0", "layout": "list", "depends": [{ "flow": "@[file://page/flow/p0.df]", "params": {} }], "items": [] },
    { "type": "container", "id": "p1", "layout": "list", "depends": [{ "flow": "@[file://page/flow/p1.df]", "params": {} }], "items": [] }
  ]
}

The payload of onPageChange is @event.page, always the logical index 0..n-1 (loop included). direction: "vertical" and initialPage are not implemented; set the initial page with the page expression. loop and pageCacheCount take effect on a device; the local preview doesn't simulate either of them.

grid — equal-width grid

{
  "type": "container",
  "id": "grid",
  "layout": "grid",
  "columnCount": 2,
  "rowSpacing": "12pt",
  "columnSpacing": "12pt",
  "items": [
    { "type": "Canvas", "id": "g1", "h": "88pt", "canvas": { "source": "@[file://page/rc/cell.rcn]" } },
    { "type": "Canvas", "id": "g2", "h": "88pt", "canvas": { "source": "@[file://page/rc/cell.rcn]" } }
  ]
}

The container computes the column width ((content width − spacing) / columns), and children get stretched to it whether or not they declare a w; every row is as tall as its tallest item. itemAspectRatio and crossAxisAlignment are not implemented.

waterfall — ragged-height masonry

Same fields as grid (columnCount / columnSpacing / rowSpacing), except each child keeps its own height and a new item always lands in whichever column is currently shortest. The column assignment strategy isn't configurable; balanceStrategy does nothing.

{
  "type": "container",
  "id": "feed",
  "layout": "waterfall",
  "columnCount": 2,
  "columnSpacing": "12pt",
  "rowSpacing": "12pt",
  "items": []
}

Control flow: op

Besides XContainer and Canvas, a node array can hold op nodes: an op renders nothing itself, it only decides which nodes this stretch expands into, and with what variables. Its children go in items (not the react that RCN uses).

There are five, and they behave identically on iPhone, Android, HarmonyOS and desktop:

{
  "op": "forEach",
  "props": { "items": "${rows}", "key": "r", "index": "i" },
  "items": [
    { "type": "Canvas", "id": "row-${r.id}", "h": "56pt",
      "params": { "label": "${r.label}", "n": "${i}" },
      "canvas": { "source": "@[file://page/rc/row.rcn]" } }
  ]
}

⚠️ if takes its condition in cond — this is not the same thing as the op:if in a data flow or an action flow, which reads props.val. Getting them the wrong way round raises no error, and breaks differently in each direction: writing val in a .xpage leaves cond empty, and an empty condition counts as true — so the stretch expands every time and else is never reached, which looks like "the condition does nothing"; in a flow, writing cond means you never branch at all. The rule is one line: write cond in a .xpage, and val in a .df / .af.

⚠️ For the same reason, a cond that cannot be evaluated counts as true (as does leaving cond out entirely). So "cond": "${maybeMissing}" needs that key to be present: an empty string reads as false, while a missing key reads as true — the two kinds of "empty" give opposite answers.

⚠️ for takes from / to / step, not the count that RCN's for uses. The same word means different things in the two places; do not copy one into the other.

⚠️ set changes what follows it, not what is inside it: it merges the variable into the scope of this level, so every node after it — items included — can read it, while nodes written before it cannot.

⚠️ Loop variables are gone once the stretch is expanded: key and index exist only during expansion and are not kept on the node tree. To use one inside an event flow, pass it in through params at expansion time ("n": "${i}" above).

⚠️ Put the loop variable in the id ("id": "row-${r.id}"): duplicate ids on one page make a redraw land on the wrong row.

Page scopes: params / state / data

When reading values there is one merged scope. Write ${rows}, not ${params.rows}. At runtime the six levels below are searched top down, and the first hit wins:

The write side, in contrast, is strictly three separate scopes:

state is the only channel that carries values sideways or upward within a page: a child taps and sets state.selectedId, and a sibling reads ${selectedId} to highlight itself. It isn't declared in the .xpage file and is empty when you enter the page; all the pages of a pager share one state.

When names really do collide, disambiguate with a prefix: ${state.tab} / ${params.tab} / ${data.tab}.

The two state-writing actions behave very differently:

• xpage.setState — wholesale replacement; keys you didn't include this time are cleared;
• xpage.patchState — a shallow merge that only overwrites the keys you list.

Use patchState for everyday appending and tab switching; save setState for when you genuinely want to wipe and start over. After changing state, remember to follow it with a redraw (below).

⚠️ Referencing a key that doesn't exist raises no error — the literal string is passed straight through. A title rendered as Box ␣␣ or a date showing 1970 is almost always this. When something renders oddly, check whether the first character is $.

depends and the three states

depends can go on any node, not just the root:

{
  "depends": [
    { "flow": "@[file://page/flow/quote.df]", "params": { "code": "${code}" } },
    { "flow": "@[file://page/flow/news.df]", "params": {} }
  ]
}

• It must be a {flow, params} object, even when params is empty. A bare string swallows the input parameters, the flow still reports success, and the page renders a screen full of -- (check G12 catches it).
• Multiple entries in the array run concurrently and merge in declaration order; branching, retries and serial dependencies all belong inside a single .df (see numable docs df).
• The output merges straight into that node's params, and the whole subtree can read it.

Every node with a depends is an async boundary with three states:

The phrase that matters is "has never had successful data": once data exists, a later refresh keeps the current content, fetches in the background and swaps it in — no skeleton flash; a failure keeps the old data rather than switching to an error page. So nested boundaries fill in block by block instead of making the whole page wait on the slowest flow.

The app draws both of these states for you — you don't write them and can't: a loading / error field on a node has no effect, and check flags it with G1c so you remember to remove it.

The skeleton doesn't appear the moment a fetch starts, either: if the result comes back within 150ms it is shown straight away, without a single skeleton frame; only after 150ms does the skeleton fade in, and once shown it stays for at least 300ms before cross-fading into the result. So on pages that hit the local cache or call a fast API, users never see a skeleton at all.

A node with a depends must have a height that can be computed before the fetch (a hard-coded h, or one given by the parent). Otherwise the height changes when loading finishes and the whole page jumps.

Events

Values are always standard bindings: "@[file://page/flow/x.af]", {"flow": "…", "params": {…}}, or an inline array of actions.

The timing of the three data events, pinned down in one table:

Two easy traps follow from that:

1. Once onRefresh exists, pulling down no longer re-fetches automatically, even when the root has a depends. If you want to reset state and re-fetch, add an explicit xpage.reloadPage at the end of that .af.
2. onLoad runs only once. For "start over every time I come back to this page", use xpage.reenterPage — don't count on onLoad.

The four redraw / reload actions, by strength (the full table is in numable docs af):

Infinite scroll is the standard combination of those four: put onReachEnd on the list → fetch the next page in the flow → xpage.patchState to append the new data to ${items} → xpage.redraw to redraw just that list. Don't reload the page — it flashes, and it re-runs every depends.

Pagination also needs loadMore declared on the same list, or the reach-end event never fires (hasMore defaults to false):

{
  "type": "container",
  "id": "rows",
  "layout": "list",
  "direction": "vertical",
  "events": { "onReachEnd": "@[file://page/flow/next-page.af]" },
  "loadMore": { "hasMore": "${hasMore}", "noMoreText": "No more items" },
  "items": []
}

There is one more switch on root: "refresh": false = don't attach a pull-to-refresh header. A root with neither a depends nor an onRefresh has none anyway, so you don't need to write it.

visible

visible accepts true / false or an expression; absent means visible.

{
  "type": "Canvas",
  "id": "k90",
  "visible": "$[if::(eq::(${seg},90),1,0)]",
  "h": "180pt",
  "canvas": { "source": "@[file://page/rc/k90.rcn]", "depends": { "flow": "@[file://page/flow/k90.df]", "params": { "n": 90 } } }
}

A node with visible: false isn't in the tree at all: it takes no space, doesn't render, and its depends doesn't run either. It fetches for the first time only once state changes — which is exactly how three mutually exclusive chart ranges avoid two requests nobody is going to look at.

⚠️ The test is strict: only true, 1 or a non-zero number counts as visible, and everything else is treated as hidden. So referencing a key that doesn't exist (leaving the literal ${…} string) makes the whole node disappear with no error. The safe form is $[if::(…,1,0)], which explicitly produces 1 or 0.

enabled is a different matter: it does get evaluated, but nothing consumes it, so writing it won't disable events. To make a node untappable, don't give it events.

menu

A menu array on any node means a long-press opens a declarative menu there. For the fields and their precedence see the "long-press node menu" section of numable docs page; only two things are specific to xpage:

• flow is required; label / icon / role are optional.
• A ${@i18n.key} inside label is looked up in this page's top-level i18n table, and renders as an empty string when it isn't found (check G35 catches it).

The input node

input is the second kind of leaf and handles exactly three things: text editing, the keyboard, and the caret. It has no visuals of its own — no border, no background, no focus highlight. Visuals come from layering: put a Canvas underneath to draw the rounded background and border, and lay the input on top.

{
  "type": "input",
  "id": "kw",
  "x": "28pt",
  "y": "16pt",
  "w": "276pt",
  "h": "44pt",
  "props": {
    "bindKey": "kw",
    "hint": "Search…",
    "hintColor": "#999999|#8E8E93",
    "inputType": "text",
    "fontSize": 16,
    "color": "#1C1C1E|#F2F2F7",
    "caretColor": "#128F66|#6FE8BE",
    "changeFireOn": "change",
    "changeDebounce": 300
  },
  "events": { "onChange": "@[file://page/flow/search.af]" }
}

w and h must be written explicitly (a single-line input does not size its height to its content).

The value lives in page state, and the write-back is silent: every keystroke writes into state[bindKey] for other nodes to read, but triggers no redraw (otherwise every keystroke would rebuild the whole tree and yank the box you are typing in out from under you). For anything reactive — a focus highlight, a character counter — call xpage.patchState + xpage.redraw explicitly in the onChange / onFocus flow.

Imperative control goes through five actions, all taking the input node's id: input.focus / input.blur / input.clear / input.selectAll / input.setValue (which also takes value and updates the state key that bindKey points at).

If what you want is "pop something up and ask for one value" rather than a box living on the page, don't use an input node — use singleValue / .xform (see numable docs params).

Fields that do nothing

These names are legal, raise no error, and have no effect whatsoever. They turn up most often in pages copied from somewhere else:

Rules (breaking one means rework)

When something breaks

Related

• numable docs page — routes, the three page types, the long-press node menu, navigation and external links
• numable docs af — the full table of xpage.* / input.* actions and how to write interaction flows
• numable docs rcn — how to draw the .rcn inside a Canvas