Make a page (by hand and with AI) and add it to the navigation¶
Goal: a page of your own — a few components showing workers or live values — reachable from a tab.
What the TUI can do today, and what it cannot
| TUI | Web app | |
|---|---|---|
Write and share a page spec (cfg.page.<name>, openspec page-specs) |
No — pages are written and shared in the web app's Pages view | Yes |
| Make a page with AI | No — the catalog has no page operation, so the AI tab cannot write one | See https://app.docs.virtufin.com/ |
| Show a shared page | Yes — Config › Pages, Enter |
Yes |
| Put a shared page in your navigation | Yes — by hand in navigation.json ("page": "<name>") |
Yes |
Edit the navigation shared on the context (cfg.navigation) |
No — web app only | Yes |
| Make a page by hand in the TUI | Yes — a custom pane (a Python file), local to your machine | — |
A: Show a shared page and add it to your tabs¶
Prerequisites: someone shared a page on the context from the web app.
- Open Pages: Config top tab,
1(Pages). Each row: Name, Title, Detail (validor the page's first validation error). - Preview: highlight a page,
Enter. It renders below the list. The TUI drawsStack,Heading,Text,WorkerTableandValueStream; a whole-view component (WorkerBrowser,ConnectionBrowser, ...) opens that pane in its place; any other component shows a placeholder. - Make the navigation your own if it is not yet: on Config › Navigation do any
edit (e.g.
ctrl+downthenctrl+upon an entry). The structure in use is then written to~/.config/virtufin/tui/navigation.json. -
Add the page node by hand: edit
navigation.jsonand put a node withpagewhere you want it, e.g. under Trading:pageis the shared page's name (the Pages list's Name);idmust be unique. 5. Restart the TUI. The node is a sub-tab (My overview); a node nested in a group is labelled with its groups (Analytics › My overview).
B: Make a page by hand — a custom pane¶
Prerequisites: Python; for a live pane, some Textual.
-
Write the file in
~/.config/virtufin/tui/panes/(created automatically). Either:- Script + form pane:
<name>.pyplus<name>.form.json— a form that runs the script with the fields inVIRTUFIN_TUI_FORM_DATA(same contract as Scripts); or - Live widget pane:
<name>.pydefining a class named exactlyPane:
from textual.widgets import Static from virtufin_tui.screens._page import Page class Pane(Page): def compose(self): yield Static("", id="out") def on_mount(self): self.set_interval(1.0, self.update_view) def update_view(self): workers = self._stores.workers.get() or [] self.query_one("#out", Static).update(f"{len(workers)} workers")self._storesis the dashboard'sDataPump,self._clientthe activeTuiClient. 2. Add it to the navigation: Config › Navigation. Your pane is listed under Available views and custom panes (kindscript_formorwidget). Highlight the navigation entry it should follow, then highlight the pane in the available table and pressa(orEnter). Or presstfor a new top-level tab holding it (prompts for id and label). 3. It appears at once; the structure is saved tonavigation.json. - Script + form pane:
What you should see¶
- The new sub-tab with your page or pane;
</>reach sub-tabs past the tenth. - The Navigation pane's line
In use: the user structure.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
Pages status line: pages: 0 — share one from the web app's Pages view |
No page is shared on this context. |
| A page row's Detail shows an error | The spec does not validate; fix it in the web app. |
| A page sub-tab shows a placeholder | The page or one of its components is not one the TUI draws. |
| Your custom pane is not in the available list | The file has neither a sibling .form.json nor a class Pane; it is skipped with a warning in ~/.local/state/virtufin/tui/tui.log. |
A hand-edited navigation.json is ignored |
It does not validate; the Navigation pane says why the structure was skipped and which one is in use. |
| You want the shared structure back | Use the shared structure (delete navigation.json) on Config › Navigation. |
Reference: Tabs, pages & custom panes.