Dictionnaire
Cette page documente la couche de métadonnées du dictionnaire — libellés, formats, règles BOOLEAN / ENUM / LOOKUP et valeurs par défaut côté formulaire (LOGIN, SYSDATE, SEQUENCE, PASSWORD). Pour des parcours orientés tâche — configurer les colonnes d'un écran, échafauder une séquence ou une recherche — voir Construire → Écrans → Colonnes et Construire → Requêtes → Séquences et recherches.
Le dictionnaire est la couche de métadonnées partagée qui transforme un nom de colonne brut en interface lisible. Une requête de connecteur retourne des colonnes que la base connaît sous leur identifiant (customer_status, due_date, invoice_amount) ; le dictionnaire y attache :
- Un libellé localisé ("Statut client", "Date d'échéance", "Montant facture").
- Une règle d'affichage (bascule
BOOLEAN, chipENUM,LOOKUPsur un autre connecteur). - Un format de nombre / date ("€ 1 234,56", "dd/MM/yyyy").
- Des valeurs par défaut côté formulaire pour les écrans d'écriture (remplissage automatique avec l'utilisateur courant, la date courante, une séquence générée, un mot de passe haché).
Défini une seule fois dans Paramètres → Dictionnaire, référencé par chaque écran, graphique et tableau de bord qui consomme la colonne correspondante. Modifier le libellé ici et chaque consommateur le répercute au prochain rendu.
Vue d'ensemble
Paramètres → Dictionnaire
La page comporte deux onglets : Colonnes (une entrée par colonne logique) et Recherches (jeux de valeurs nommés que les colonnes référencent).
Onglet Colonnes
Cliquer sur + Nouvelle colonne ou sur n'importe quelle ligne pour ouvrir l'éditeur de colonne.
L'éditeur de colonne
| Champ | Effet |
|---|---|
| Nom | La clé du dictionnaire — court, snake_case (customer_status). Les indices de colonnes des connecteurs référencent ce nom pour récupérer les métadonnées. |
| Libellé | Une table par langue des libellés d'affichage. L'éditeur affiche une saisie par langue chargée. Retombe sur le Nom si une langue manque. |
| Description | Optionnel. Apparaît comme infobulle sur les saisies de formulaire et les en-têtes de colonne. |
| Type | string / int / float / decimal / bool / date / datetime / time. Détermine le widget par défaut sur les écrans (saisie texte vs sélecteur de date vs case à cocher). |
| Format | Pour les nombres et les dates — une chaîne de format (1 234,56 €, dd/MM/yyyy). La cellule de grille et la saisie de formulaire s'affichent avec ce format. |
| Règle | — (pas de rendu particulier) / BOOLEAN / ENUM / LOOKUP / PASSWORD. Voir Règles d'affichage. |
| Lookup | Visible uniquement quand Règle vaut LOOKUP. Liste déroulante des recherches définies sur l'onglet Recherches. |
| Valeurs Enum | Visibles uniquement quand Règle vaut ENUM. Une liste réordonnable de lignes { valeur, libellé(s), couleur }. |
| Valeurs par défaut côté formulaire | Optionnel. Voir Valeurs par défaut côté formulaire. |
| Obligatoire | Marque le champ comme obligatoire par défaut sur chaque formulaire. Les surcharges par écran peuvent toujours relâcher cette contrainte. |
| Lecture seule | Marque le champ comme en lecture seule par défaut sur chaque formulaire. |
Un Enregistrer reconstruit le registre du dictionnaire ; les consommateurs (écrans, graphiques) se re-rendent avec les nouvelles métadonnées à leur prochain rafraîchissement.
Règles d'affichage
Le champ Règle change la façon dont une colonne est rendue dans une cellule de grille, dans une saisie de formulaire et dans un chip de filtre.
BOOLEAN
Une colonne bool s'affiche en chip / bascule. La saisie de formulaire est un interrupteur. Le filtre est une pastille à trois états (Tous / Oui / Non).
L'éditeur propose :
| Champ | Effet |
|---|---|
| Libellé Vrai | Par défaut "Oui" — table par langue. |
| Libellé Faux | Par défaut "Non". |
| Couleur Vrai / Couleur Faux | Fond des pastilles dans la grille. |
ENUM
Un petit jeu de valeurs statique déclaré sur la colonne elle-même. À utiliser quand les valeurs sont connues à la conception et ne changent jamais à l'exécution (par exemple low / medium / high).
| Champ par valeur | Effet |
|---|---|
| Valeur | La valeur littérale enregistrée en base. |
| Libellé | Libellé d'affichage par langue. |
| Couleur | Fond de la pastille. |
| Ordre | Poignée de glissement pour réordonner. |
S'affiche en chip coloré dans les grilles, en liste déroulante sur les formulaires, en multi-sélection dans les filtres.
LOOKUP
Un jeu de valeurs dynamique récupéré depuis une autre requête de connecteur. À utiliser quand les valeurs se trouvent dans une table et peuvent évoluer dans le temps (statuts gérés par un opérateur, listes de pays, etc.).
La colonne pointe sur une entrée Recherche ; la recherche elle-même est définie sur l'onglet Recherches — voir ci-dessous.
PASSWORD
Masque la valeur dans les grilles (••••••••) et affiche une saisie de type mot de passe sur les formulaires. Combiné à la valeur par défaut côté formulaire PASSWORD, met en place un chemin d'écriture haché en Argon2 sûr par construction.
Onglet Recherches
Une recherche est une requête nommée qui retourne des lignes { valeur, libellé }. Les colonnes en Règle = LOOKUP + qui pointent sur une recherche rendent leurs valeurs sous forme de chips étiquetés.
| Champ | Effet |
|---|---|
| Nom | Identifiant référencé par les entrées de colonne (customer-statuses). |
| Connecteur / Requête | Le connecteur SQL et la requête de lecture nommée qui retournent les valeurs. |
| Colonne valeur | Colonne du résultat qui porte la valeur enregistrée (ce que la base stocke sur chaque ligne). |
| Colonne libellé | Colonne du résultat qui porte le libellé d'affichage. Localisée par le dictionnaire quand la requête joint une table de traductions. |
| Colonne couleur | Optionnel. Pilote la couleur de fond du chip dans les grilles. |
| Filtrer depuis | Dépendances optionnelles — voir filtres en cascade. |
| Cache | Aucun / Par session / Par requête. Pilote l'agressivité de la mise en cache de la recherche. Par défaut Par session. |
Un bouton Tester en haut exécute la requête sous-jacente et affiche les paires { valeur, libellé } résolues — utile pour confirmer que les colonnes sont bien alignées.
Valeurs par défaut côté formulaire
Le champ Valeurs par défaut côté formulaire de l'éditeur de colonne permet à une colonne de se remplir automatiquement à l'insertion / mise à jour sans que l'utilisateur saisisse la valeur. Quatre jetons spéciaux sont reconnus :
| Jeton | Effet au moment de l'enregistrement |
|---|---|
| SEQUENCE | Récupère la valeur suivante d'une séquence en base — utile pour les identifiants générés quand la base n'auto-incrémente pas. |
| SYSDATE | Fixe la valeur au timestamp courant du serveur. |
| LOGIN | Fixe la valeur à l'identifiant de l'utilisateur appelant (le sub du JWT). |
| PASSWORD | Hache la valeur en clair du champ avec Argon2 avant l'enregistrement. Combiné à Règle = PASSWORD, produit un chemin d'écriture sûr par construction. |
Les valeurs par défaut côté formulaire s'exécutent côté serveur au moment de l'enregistrement — le client ne les voit jamais. Une colonne d'audit auto-remplie avec LOGIN ne peut pas être altérée depuis le navigateur.
Règles d'affichage vs règles côté formulaire
Les deux concepts se confondent facilement. Le tableau :
| Aspect | Règle d'affichage | Règle côté formulaire |
|---|---|---|
| Lieu d'exécution | Côté client (rendu). | Côté serveur (gestionnaire d'enregistrement). |
| Ce qu'elle change | L'apparence de la valeur. | La valeur elle-même. |
| Exemples | BOOLEAN → chip ; ENUM → pastille colorée ; LOOKUP → chip étiqueté depuis une table. | LOGIN → nom de l'appelant ; SYSDATE → now() ; PASSWORD → hachage Argon2. |
| Visible par l'utilisateur ? | Oui. | Non — la valeur est calculée à l'enregistrement. |
Les deux peuvent s'appliquer à la même colonne. Une colonne d'audit typique Créé par a Règle = LOOKUP (sur une table d'utilisateurs, pour afficher le nom d'affichage) et Valeur par défaut côté formulaire = LOGIN (pour que la valeur soit fixée automatiquement à l'insertion).
Localisation
Chaque champ texte de l'éditeur de colonne — Libellé, Description, Libellé Vrai / Libellé Faux, Libellé Enum — est une table par langue. L'éditeur affiche une saisie par langue chargée ; les langues manquantes retombent sur la chaîne de résolution décrite sous i18n.
Les opérateurs ajoutent des langues depuis Paramètres → Langues ; les nouvelles langues apparaissent alors comme colonnes supplémentaires dans l'éditeur de dictionnaire.
Permissions
L'onglet Dictionnaire est verrouillé par settings:dictionary. Les recherches héritent de la permission de leur requête SQL sous-jacente — un appelant qui ne peut pas exécuter sql:billing:statuses-list ne voit pas les valeurs de la recherche ; la liste déroulante apparaît vide.
Conseils et bonnes pratiques
- Définir une entrée de dictionnaire par colonne logique, pas par colonne de base. Si
customer_statusetsupplier_statuspartagent la même recherche, une seule entrée de dictionnaire couvre les deux — faire pointer les deux indices de connecteur dessus. - Garder les libellés courts. Les libellés longs se tronquent dans les en-têtes de grille. Le champ Description est le bon endroit pour les explications.
- Utiliser
ENUMquand les valeurs sont connues à la conception,LOOKUPquand elles ne le sont pas. Une énumérationpriority(low/medium/high) tient en ligne ; une liste de pays a sa place dans une recherche. - Mettre en cache les recherches Par session. Le cache par requête ajoute une requête à chaque ouverture d'écran ; Aucun est rarement nécessaire.
- Colonnes d'audit :
LOOKUP+LOGIN/SYSDATE. Le motif le plus propre — lisible à l'affichage, auto-rempli à l'enregistrement.
Sous le capot
Les définitions du dictionnaire sont enregistrées dans liberty-apps/config/dictionary.toml. Les opérateurs ne modifient pas ce fichier à la main en exploitation normale ; l'éditeur de dictionnaire est l'interface de référence. L'onglet TOML brut de Paramètres → Dictionnaire est l'échappatoire quand un manque de l'éditeur bloque une modification avancée.
Pour aller plus loin
- Connecteurs — où les indices de colonnes lient une colonne SQL découverte à une entrée de dictionnaire.
- Écrans — comment les métadonnées de colonne façonnent la grille et le dialogue d'édition.
- Conditions de formulaire — règles de visibilité / obligatoire / désactivé conditionnelles par-dessus les règles du dictionnaire.
- Applications et Plugins → i18n — ajouter des langues.