Menus — overview
A menu in Liberty is what the user sees in the left navigation panel when they open one of your apps. It groups screens, endpoints, dashboards and routes into a tree of folders and leaves.
Three things are worth knowing up front:
| Fact | Implication |
|---|---|
| There is no separate "app" object in Liberty. | An "app" is just a connector that has a menu attached and whose show_in_switcher flag is on. Both conditions are required for the application picker of the sidebar to list it. |
Menus are stored as a flat list of items linked by parent. | The tree is assembled by the backend — easier to hand-edit, round-trips cleanly through TOML, drag operations only ever mutate one list. |
Every menu key is a connector name ([menus.<connector>]). | The connector named crm carries the menu under [menus.crm]; the screen customers on crm is reached from a leaf with target = "customers_get". |
The page that manages menus is Liberty Next → Build → Menus.
In the application
At the bottom of the sidebar, Open on hover folds the menu to its icons: it opens over the page while the mouse is on it and folds back once a page is picked, leaving the whole width to the screens. Keep open brings back the fixed menu. The choice is kept in the browser.
The Menus page at a glance
Three regions:
| Region | What it carries |
|---|---|
| Top scope bar | One chip per app (a connector that has a menu). Click a chip → its tree loads below. The + Add scope chip gives an existing connector a menu. Discard / Save on the right commit or revert page-wide edits. |
| Tree (left column) | The selected app's menu tree. Click a row to select it for editing. On hover, action icons appear over the row's right edge — Move up / down, Indent / Outdent, Add child, Delete. A filter input narrows the list. |
| Inspector (right column) | The full editor for the selected item — a generic form over the MenuItem schema. Fields adapt to the selected type (a folder shows fewer fields than a leaf). |
What a menu carries
The schema's top-level shape:
| Field | Notes |
|---|---|
label | The app's display name. Falls back to the connector name. Shown in the application picker. |
items | A flat list of menu items, linked by their parent field. |
Each item:
| Field | Required | What it does |
|---|---|---|
id | yes | Unique inside this menu. Referenced by children's parent. |
parent | no | Pick a folder, or leave blank for a top-level item. |
label | yes | The sidebar text. |
l | no | Per-language label overrides — l.fr, l.de, etc. |
icon | no | One of the icon names the sidebar draws (shield, users, barchart, …) — see Translations and icons. |
type | no | Blank = folder. Otherwise one of screen, query, endpoint, dashboard, page (see Item types). |
connector | no | Connector hosting the target. Blank = the app's own connector (the menu key). |
target | conditional | Required on every leaf; ignored on folders. |
params | no | Fixed parameters passed to the target when the item opens. |
roles | no | Restrict to these roles. Empty = visible whenever the user can run the target. |
Folder vs leaf
The type field decides:
| Setting | Behaviour |
|---|---|
type blank | The item is a folder — groups children. No target, no connector, no params. A folder is hidden when none of its descendants are visible (the runtime collapses empty folders). |
type set | The item is a leaf — points at a thing the user can open. Must have a target. |
Folders can nest indefinitely. Leaves can't have children — they're terminal nodes.
The five leaf kinds
type | Opens | target is | connector |
|---|---|---|---|
screen | A designed screen. | The screen's read query (customers_get), picked from the designed screens. | The connector that owns it. Blank = the app's. |
query | The same grid view, picked from the raw queries — a query with no designed screen opens as a plain table. | A SELECT query name. | The connector that owns the query. Blank = the app's. |
endpoint | The HttpRunner — fires an API connector endpoint. | An endpoint name. | The API connector. Blank = the app's. |
dashboard | A dashboard (charts + KPIs). | A dashboard id (from [dashboards.*]). | Must NOT be set (dashboards live in their own flat namespace). |
page | A registered frontend route (a custom feature area, e.g. /nomaflow). | The route path. | Must NOT be set (the target is a route, not a connector resource). |
The schema validator enforces:
- A leaf needs a
target— saving fails without one. - A
dashboardorpageleaf with aconnectoris rejected (misconfiguration). - A folder with
target/connector/paramsis rejected (those fields only make sense on leaves).
Save and reload
The Save button validates the whole MenusFile (unique ids, parents exist, no cycles), writes menus.toml and triggers a hot reload. New menus apply immediately — no process restart.
The validation is strict on three things:
| Check | Why |
|---|---|
Every parent reference must point at an existing item. | A dangling parent would orphan the subtree. |
| No cycles (a parent chain that loops). | An infinite-loop guard. |
No duplicate id within the same menu. | Children reference parents by id; duplicates break the link. |
Cross-menu duplicates are fine — [menus.crm.security] and [menus.nomasx1.security] coexist without conflict.
How a connector becomes an app
A connector is listed in the application picker of the sidebar only when both conditions are true:
- A menu exists —
[menus.<connector>]is set up in Liberty Next → Build → Menus. - Show In Switcher on the connector — set in Liberty Next → Build → Connectors → <connector> → Settings (on by default).
Miss either one and the connector exists but is not listed. The picker itself appears only when there is more than one application. Setting up the menu first and then ticking show_in_switcher is the usual order.
Note: the Connectors page's own Apps / Data sources grouping is based on menu existence alone — connectors with a menu but show_in_switcher = false still show under Apps there. That grouping is an internal Settings-UI affordance; the user-facing picker is what Show In Switcher gates.
The next page covers the wiring from both sides.
Permission pruning
When the user opens the app, GET /api/menus returns the tree filtered to what the user can run:
- A leaf is kept when the user may run what it opens (
sql:<connector>:<target>forscreen/query,api:<connector>:<target>forendpoint), or when a role explicitly allows itsmenu:<app>:<id>— see Permissions and roles. - A
menu:ordashboard:deny removes it. - A folder with no surviving children is collapsed away.
- Items with a
rolesfilter are kept only when the user's roles intersect the list.
A user sees only the parts of the menu they can actually use — no greyed-out items, no clicks on dead-end links.
What you actually do — quick map
| Goal | Read |
|---|---|
| Make a connector show up as an app in the application picker. | Make a connector an app. |
| Build the tree — folders, leaves, drag/reorder, indent. | Build the tree. |
| Pick the right leaf type (screen / endpoint / dashboard / route). | Item types. |
| Restrict items to specific roles. | Permissions and roles. |
| Add icons + per-language labels. | Translations and icons. |
What's next
- Make a connector an app — wire
show_in_switcher,homeand the menu. - Concepts → Menus — the deep reference.