Tabs, pages & custom panes¶
The dashboard's tabs are the navigation structure (openspec navigation-specs, tui#52), the same the web app follows: a tree of nodes, each opening a built-in view (a View Id), a page spec, or holding children. The structure in use is
- your own
~/.config/virtufin/tui/navigation.json, if it validates; - else the structure an admin shared on the context (
cfg.navigation, from the web app's Navigation editor), followed live; - else the built-in default virtufin-domain-devkit ships (the same default the web app has).
The pages and navigation views are always reachable: a structure without them gets a Config group
holding them. The Navigation pane says which structure is in use and why another was skipped.
{
"$schema": "https://app.virtufin.com/schemas/navigation.v1.schema.json",
"version": 1,
"nodes": [
{"id": "home", "label": "Home", "view": "home"},
{"id": "trading", "label": "Trading", "children": [
{"id": "feeds", "label": "Feeds", "view": "feeds"},
{"id": "analytics", "label": "Analytics", "children": [
{"id": "pnl", "label": "P&L", "view": "pnl"},
{"id": "overview", "label": "My overview", "page": "stopped_workers"}
]}
]}
]
}
How the TUI draws it (its representation profile): the first level is the top tabs, the second the
sub-tabs (keys 1-9, 0 for the tenth, </> beyond); a top-level leaf (home) is a tab without
sub-tabs; a deeper node is a sub-tab labelled with its groups (Analytics › P&L). A view names a
built-in view (home, feeds, instruments, orderbook, indicators, portfolio, pnl, risk,
strategy, scenario, workers, connections, scripts, triggers, states, eventstores,
alerts, changes, events, ai, pages, navigation) or a custom pane below; a view the TUI lacks
(services) shows a placeholder naming it. A page opens the context's shared page of that name.
The pane_order of config.toml is gone: a customised one was written to navigation.json once, an
unchanged one dropped.
Editing your structure from the TUI¶
The Navigation pane (Config → Navigation) shows the structure in use, two levels:
| Key | Action |
|---|---|
ctrl+up / ctrl+down |
Move the highlighted entry within its tab |
d |
Delete the highlighted entry (the navigation table focused); protected entries (Pages, Navigation) stay |
a |
Add the view highlighted in "Available views and custom panes" (or Enter on it) after the highlighted entry |
t |
A new top-level tab holding the highlighted available view (prompts for id + label) |
The first edit makes the structure your own (navigation.json); each edit is validated, saved and
applied at once, new tabs included. "Use the shared structure" deletes navigation.json. The structure
shared on the context is edited in the web app only.
Pages¶
A node with page renders a page spec shared on the context (openspec page-specs; written and shared in
the web app's Pages view). The Pages view lists them; Enter renders one. The TUI draws Stack,
Heading, Text, WorkerTable (the Worker Filter over the workers) and ValueStream (the value view
of a topic, state key or read); a component that is a whole view (WorkerBrowser, ConnectionBrowser,
...) opens that pane in its place, with its keys; any other component shows a placeholder. A page that
does not validate lists its errors.
To put a shared page or a custom pane in your tabs step by step, see Make a page and add it to the navigation. Pages are written and shared in the web app (https://app.docs.virtufin.com/).
Custom panes¶
Drop files into ~/.config/virtufin/tui/panes/ (created automatically).
Two kinds, distinguished by what's alongside the .py file:
Script + form pane¶
A <name>.py with a sibling <name>.form.json — the same convention
already used by the Scripts page's built-in examples (see
create_worker.py / create_worker.form.json there for a full
reference). The form's fields are collected and passed to your script as
JSON via the VIRTUFIN_TUI_FORM_DATA env var when submitted; the script
also receives the same VIRTUFIN_TUI_API_{HOST,PORT,TLS,KEY} /
VIRTUFIN_TUI_WORKER_API_{HOST,PORT} env vars every script gets — see
Scripts → The env-var contract for the
full table and who sets these. Output
streams to a log below the form. This is a one-shot action pane, not a
continuously updating one. The form schema itself is defined by
textual_jsonforms -- see docs/textual-jsonforms-spec.md in the repo
root for the full field-type reference. (The same library also powers
the Workers page's a/Add worker form, built dynamically from a
worker's JSON-Schema config_schema rather than a hand-written
.form.json.)
Live widget pane¶
A <name>.py with no sibling .form.json, defining a module-level
class named exactly Pane:
from virtufin_tui.screens._page import Page
class Pane(Page):
def compose(self):
...
def on_mount(self):
self.set_interval(1.0, self.refresh)
Pane subclasses Page, the base of the built-in pages: it is built with
(stores, client) (self._stores is the dashboard's DataPump,
self._client the active TuiClient). This gives you a genuine persistent
page — live polling, subscriptions, whatever you need — not just a form
submission. A plain textual.widget.Widget with the same
__init__(self, stores, client, **kwargs) works too.
A Page gets the connection state from the dashboard in self.connection
(the active context, its URL, whether it answers, and every context's
health); override connection_changed() to redraw when it changes.
While no context is active, a pane shows "needs a context" instead of
mounting, so client is never None in your page. A pane that works without
a context (and handles client being None) sets the class attribute
WORKS_UNBOUND = True, as Home and Config do.
A file matching neither pattern (no form, and no Pane class) is skipped
and logged as a warning; it won't crash the TUI.