Menus — vue d'ensemble

Un menu dans Liberty, c'est ce que l'utilisateur voit dans le panneau de navigation à gauche quand il ouvre une de vos applications. Il regroupe écrans, endpoints, tableaux de bord et routes dans un arbre de dossiers et de feuilles.

Trois points à connaître d'emblée :

Fait	Conséquence
Il n'y a aucun objet « application » séparé dans Liberty.	Une « application » est simplement un connecteur qui a un menu attaché et dont l'indicateur show_in_switcher est actif. Les deux conditions sont requises pour que sa tuile apparaisse dans le sélecteur d'applications en haut.
Les menus sont stockés sous forme de liste plate d'éléments reliés par parent.	L'arbre est assemblé par le backend — plus facile à éditer à la main, conversion propre vers TOML et retour, les opérations de glisser-déposer ne modifient qu'une seule liste.
Chaque clé de menu est un nom de connecteur ([menus.<connector>]).	Le connecteur nommé crm porte le menu sous [menus.crm] ; l'écran customers sur crm est atteint depuis une feuille avec target = "customers_get".

La page qui gère les menus est Paramètres → Menus.

---

La page Menus en un coup d'œil

Trois zones :

Zone	Ce qu'elle porte
Barre de portée en haut	Une pastille par application (un connecteur qui a un menu). Cliquer une pastille → son arbre se charge en dessous. Le bouton ＋ Ajouter un menu pour un connecteur enregistre un nouveau connecteur sous Menus. Annuler / Enregistrer à droite valident ou annulent les modifications de la page.
Arbre (colonne de gauche)	L'arbre du menu de l'application sélectionnée. Cliquer une ligne pour la sélectionner et la modifier. Au survol, des icônes d'action apparaissent sur le bord droit de la ligne — Monter / Descendre, Indenter / Désindenter, Ajouter un enfant, Supprimer. Un champ de filtre réduit la liste.
Inspecteur (colonne de droite)	L'éditeur complet de l'élément sélectionné — un formulaire générique sur le schéma MenuItem. Les champs s'adaptent au type sélectionné (un dossier affiche moins de champs qu'une feuille).

---

Ce que porte un menu

La forme du schéma au plus haut niveau :

Champ	Notes
label	Le nom d'affichage de l'application. Retombe sur le nom du connecteur si absent. Affiché dans le sélecteur d'applications en haut.
items	Une liste plate d'éléments de menu, reliés par leur champ parent.

Chaque élément :

Champ	Requis	Rôle
id	oui	Unique dans ce menu. Référencé par le parent des enfants.
parent	non	Choisir un dossier, ou laisser vide pour un élément de premier niveau.
label	oui	Le texte affiché dans la barre latérale.
l	non	Libellés par langue — l.fr, l.de, etc.
icon	non	Un nom d'icône Lucide (shield, users, chart-bar, …).
type	non	Vide = dossier. Sinon query, endpoint, dashboard ou page (voir Types d'éléments).
connector	non	Connecteur qui héberge la cible. Vide = le connecteur de l'application (la clé du menu).
target	conditionnel	Requis sur chaque feuille ; ignoré sur les dossiers.
params	non	Paramètres fixes transmis à la cible à l'ouverture de l'élément.
roles	non	Restreint à ces rôles. Vide = visible dès que l'utilisateur peut exécuter la cible.

---

Dossier ou feuille

Le champ type décide :

Réglage	Comportement
type vide	L'élément est un dossier — il regroupe des enfants. Pas de target, pas de connector, pas de params. Un dossier est masqué quand aucun de ses descendants n'est visible (le runtime replie les dossiers vides).
type renseigné	L'élément est une feuille — il pointe vers quelque chose que l'utilisateur peut ouvrir. Doit avoir un target.

Les dossiers peuvent être imbriqués sans limite. Les feuilles ne peuvent pas avoir d'enfants — ce sont des nœuds terminaux.

---

Les quatre types de feuilles

type	Ouvre	target est	connector
query	Un écran (TableView) — utilise l'écran associé à cette requête.	Un nom de requête SELECT (customers_get).	Le connecteur qui possède la requête. Vide = celui de l'application.
endpoint	Le HttpRunner — déclenche un endpoint de connecteur API.	Un nom d'endpoint.	Le connecteur API. Vide = celui de l'application.
dashboard	Un tableau de bord (graphiques + KPI).	Un id de tableau de bord (depuis [dashboards.*]).	NE doit PAS être renseigné (les tableaux de bord résident dans leur propre espace de noms plat).
page	Une route frontend enregistrée (une fonctionnalité personnalisée, par exemple /nomaflow).	Le chemin de la route.	NE doit PAS être renseigné (la cible est une route, pas une ressource de connecteur).

Le validateur du schéma impose :

• Une feuille a besoin d'un target — l'enregistrement échoue sans cela.
• Une feuille dashboard ou page avec un connector est rejetée (mauvaise configuration).
• Un dossier avec target / connector / params est rejeté (ces champs n'ont de sens que sur les feuilles).

---

Enregistrement et rechargement

Le bouton Enregistrer valide tout le MenusFile (ids uniques, parents existants, pas de cycles), écrit menus.toml et déclenche un rechargement à chaud. Les nouveaux menus apparaissent immédiatement dans le sélecteur d'applications en haut — pas de redémarrage de processus.

La validation est stricte sur trois points :

Vérification	Pourquoi
Chaque référence parent doit pointer vers un élément existant.	Un parent fantôme rendrait orpheline la sous-arborescence.
Pas de cycles (une chaîne de parents qui boucle).	Protection contre les boucles infinies.
Pas de id en doublon dans le même menu.	Les enfants référencent les parents par id ; les doublons cassent le lien.

Les doublons entre menus différents sont autorisés — [menus.crm.security] et [menus.nomasx1.security] coexistent sans conflit.

---

Comment un connecteur devient une application

Un connecteur n'apparaît dans le sélecteur d'applications en haut que lorsque les deux conditions sont réunies :

1. Un menu existe — [menus.<connector>] est configuré dans Paramètres → Menus.
2. show_in_switcher = true sur le connecteur — à activer dans Paramètres → Connecteurs → <connecteur> → Paramètres.

Si l'une des deux manque, le connecteur existe mais ne s'affiche pas dans le sélecteur. L'ordre habituel : configurer le menu d'abord, puis cocher show_in_switcher.

À noter : le regroupement Applications / Sources de données sur la page Connecteurs se base uniquement sur l'existence d'un menu — un connecteur avec un menu mais show_in_switcher = false reste classé sous Applications à cet endroit. Ce regroupement est un confort interne à l'interface Paramètres ; le sélecteur d'applications côté utilisateur est ce que show_in_switcher gouverne.

La page suivante détaille le câblage des deux côtés.

---

Élagage par les permissions

Quand l'utilisateur ouvre l'application, GET /api/menus renvoie l'arbre filtré à ce que l'utilisateur peut exécuter :

• La permission sous-jacente de chaque feuille (sql:<connector>:<target> pour query, api:<connector>:<target> pour endpoint, voir Permissions et rôles) est vérifiée.
• Les éléments pour lesquels l'utilisateur n'a pas la permission sont retirés.
• Un dossier sans enfant survivant est replié.
• Les éléments avec un filtre roles ne sont conservés que si les rôles de l'utilisateur croisent la liste.

Un utilisateur ne voit que les parties du menu qu'il peut réellement utiliser — pas d'éléments grisés, pas de clics sur des liens en impasse.

---

Ce qu'on fait concrètement — carte rapide

Objectif	À lire
Faire apparaître un connecteur comme application dans le sélecteur en haut.	Transformer un connecteur en application.
Construire l'arbre — dossiers, feuilles, glisser-déposer, indentation.	Construire l'arbre.
Choisir le bon type de feuille (écran / endpoint / tableau de bord / route).	Types d'éléments.
Restreindre les éléments à certains rôles.	Permissions et rôles.
Ajouter icônes et libellés par langue.	Traductions et icônes.

---

La suite

• Transformer un connecteur en application — câbler show_in_switcher, home et le menu.
• Concepts → Menus — la référence détaillée.