Dictionnaire

Le dictionnaire est le catalogue partagé des métadonnées par colonne. Un seul fichier (config/dictionary.toml) en contient trois types :

• les entrées — métadonnées par colonne : libellé, format, règle, traductions par langue ;
• les enums — énumérations nommées avec libellés traduisibles ;
• les lookups — pointeurs vers une requête qui résout un code → libellé.

Quand une requête déclare une colonne avec une indication dd, le connecteur SQL résout son libellé, son format et sa règle au moment où il renvoie le résultat, dans la langue de la requête. La grille React affiche directement le libellé localisé, ✓ / ✗ pour les booléens, le libellé de l'énumération, ou — via services/lookups.useLookupBatch — le libellé du lookup après un seul fetch par session.

---

Vue d'ensemble

---

Entrées

Métadonnées par colonne. Chaque entrée fixe :

Champ	Description
label	Libellé anglais par défaut.
l	Libellés par langue ({ fr = "...", de = "..." }).
format	Format interprété par l'interface : date, datetime, amount, percent, string, number, boolean, ….
rules	Règle d'affichage : BOOLEAN, ENUM, LOOKUP — ou une règle côté formulaire (voir plus bas).
rules_values / default	Configuration optionnelle propre à la règle (par exemple true_value pour un booléen, valeur par défaut sur la création d'une ligne).

[entries.USER_STATUS]
label   = "Status"
format  = "string"
rules   = "ENUM"

[entries.USER_STATUS.l]
fr = "Statut"
de = "Status"

Une entrée peut être déclarée au niveau global (partagée par tous les connecteurs) ou sous [connectors.<conn>.entries.<clé>] (spécifique à un connecteur — utile quand le même nom de colonne porte un sens différent selon la source). La résolution teste d'abord la version par connecteur, puis se rabat sur la version globale.

Une indication dd = "USER_STATUS" sur la colonne de la requête applique l'entrée à cette colonne. dd = "" désactive — la colonne reste sans libellé localisé. Un label indiqué directement sur la colonne surcharge celui du dictionnaire.

---

Enums

Une table statique code → libellé avec traductions.

[enums.USER_STATUS]
label = "User status"
values = [
  { value = "Y", label = "Active",   l = { fr = "Actif" } },
  { value = "N", label = "Inactive", l = { fr = "Inactif" } },
]

Résolus au moment du résultat. La cellule affiche le libellé de la langue active, le filtre de colonne propose un sélecteur multi-valeurs alimenté par la même liste, et le widget de formulaire est un SearchSelect.

---

Lookups

Une référence vers une requête dont les colonnes value / label résolvent la cellule.

[lookups.CITY]
description = "Cities"
connector   = "myapp"            # retombe sur le connecteur appelant si non précisé
query       = "cities_get"
value       = "ID"
label       = "NAME"
group       = "REGION"           # regroupement secondaire optionnel

Une colonne marquée rules = "LOOKUP" qui pointe sur un id de lookup est résolue :

• côté grille : un seul fetch partagé par session via useLookupBatch — la cellule affiche code — libellé ;
• côté formulaire : un SearchSelect alimenté par useLookupTables, restreint à l'appel selon les lookup_param_binds éventuels.

---

Règles d'affichage et règles côté formulaire

Règle	Champ d'application	Effet
BOOLEAN	Affichage	La cellule affiche ✓ ou ✗. rules_values.true_value précise quelle valeur brute compte comme vrai (défaut "Y").
ENUM	Affichage	La cellule affiche le libellé localisé. Le filtre de colonne et le widget de formulaire lisent les valeurs depuis [enums.<id>].
LOOKUP	Affichage	La cellule affiche code — libellé depuis [lookups.<id>]. Le widget de formulaire est restreint par lookup_param_binds.
SEQUENCE	Formulaire	Renvoie la valeur suivante d'une séquence à la création.
SYSDATE / CURRENT_DATE	Formulaire	Initialise le champ avec la date du jour à la création.
LOGIN	Formulaire	Initialise le champ avec le nom d'utilisateur de l'appelant à la création.
PASSWORD	Formulaire	Marque l'entrée comme mot de passe et active le chiffrement à l'enregistrement.

Les règles d'affichage voyagent sur l'objet Column.rule pour que la grille puisse rendre sans aller-retour supplémentaire. Les règles côté formulaire sont appliquées par ScreenDialog à l'ouverture du formulaire modal — détaillées dans la page Écrans.

---

i18n

Chaque requête HTTP transporte l'en-tête X-Liberty-Lang (la langue active de react-i18next). Le connecteur SQL résout les libellés et les règles dans cette langue ; la grille React affiche directement les libellés traduits. Si une traduction manque, la valeur de label (anglais) est utilisée par défaut.

Le dictionnaire indique sa langue par défaut :

default_language = "en"

---

Conseils & bonnes pratiques

• Déclarer les entrées partagées au niveau global. Une colonne USER_STATUS qui a le même sens partout doit vivre sous [entries.USER_STATUS] une seule fois. La surcharge par connecteur est réservée aux cas où le sens diffère.
• Garder label court. C'est ce qu'affiche l'en-tête de grille. Les titres longs vont dans le champ description de la requête, qui devient le titre du panneau.
• rules = "ENUM" ne doit pas servir de LOOKUP déguisé. Pour une liste de valeurs courte et connue à la configuration, utiliser ENUM. Pour une liste qui vit dans une table et change à l'exécution, utiliser LOOKUP. Le rendu de la cellule est identique ; l'éditeur du formulaire diffère (statique pour ENUM, dynamique pour LOOKUP).
• Une colonne sans dd fonctionne aussi. La grille affiche alors le type brut renvoyé par le curseur. Ajouter dd uniquement quand il y a une vraie raison : libellé localisé, règle booléen / enum / lookup, format non standard.