Colonnes
L'onglet Colonnes est l'endroit où l'on définit les métadonnées par colonne : comment la colonne s'affiche dans la grille, comment elle apparaît dans le formulaire de dialogue, si elle filtre, si elle est obligatoire, si elle fait partie de la clé primaire de la ligne. On configure chaque colonne une fois — les deux surfaces (grille et dialogue) utilisent la même configuration.
L'onglet Colonnes en un coup d'œil
La liste affiche une ligne par entrée ColumnHint. Cliquer sur une ligne pour accéder à son éditeur complet — le résumé en ligne couvre les champs les plus utilisés, l'éditeur complet couvre chaque indicateur.
Champ par champ
Chaque indication de colonne porte la même structure. Détailler une colonne révèle cinq groupes de champs.
Identité
| Champ | Notes |
|---|---|
name | La colonne du résultat à laquelle s'applique cette indication. Correspondance insensible à la casse contre les colonnes de la requête de lecture. Normalisée en MAJUSCULES à l'enregistrement. |
dd | Entrée de dictionnaire dont hériter label / format / rule. Vide utilise le name de la colonne comme clé. Mettre à "" (chaîne vide entre guillemets) pour se désinscrire totalement du dictionnaire. |
Le système de dictionnaire (dictionary.toml) est le vocabulaire centralisé de Liberty — une entrée définit une fois le titre d'affichage, le format, la règle et la recherche d'un champ ; chaque écran qui a une colonne avec ce nom en hérite. Voir Concepts → Dictionnaire.
Affichage dans la grille
| Champ | Notes |
|---|---|
label | Titre d'affichage dans l'en-tête de la grille et libellé du champ dans le dialogue. Retombe sur le label du dictionnaire, puis sur le name de la colonne. |
hidden | Quand activé, la colonne est masquée par défaut. L'opérateur peut la rendre visible via le menu Colonnes de la grille. |
wrap | Quand activé, un texte long passe à la ligne dans la grille au lieu d'être tronqué. |
width | Largeur de colonne fixe en pixels. Vide = ajustement automatique. |
align | Alignement du texte — left, right, center. Vide choisit automatiquement selon le type (nombres à droite, texte à gauche). |
format | Comment afficher la valeur — date, number, boolean, currency, etc. Surcharge le format du dictionnaire. Pilote à la fois la cellule de grille et le champ de dialogue. |
Règle d'édition
| Champ | Notes |
|---|---|
rules | Comment afficher et valider la colonne. BOOLEAN affiche une case à cocher, ENUM une liste déroulante, LOOKUP un sélecteur avec recherche. Vide hérite du dictionnaire. |
rules_values | La valeur de la règle — BOOLEAN → le marqueur vrai (Y / 1 / true) ; ENUM → l'identifiant d'énumération ; LOOKUP → l'identifiant de recherche ; SEQUENCE / NN → l'identifiant de séquence. |
default | Valeur pré-remplie à l'ajout d'une nouvelle ligne. |
required | Activé, le champ porte un astérisque et Enregistrer reste bloqué tant qu'il est vide. |
disabled | Activé, la colonne est en lecture seule — l'opérateur voit la valeur sans pouvoir la modifier. |
disable_on_add / disable_on_edit | Lecture seule uniquement à l'ajout d'une ligne, ou uniquement une fois la ligne créée — le second pour les clés qui ne doivent plus changer. |
required_when / disabled_when | Obligatoire ou en lecture seule uniquement tant que des conditions sur d'autres champs sont remplies. Un champ obligatoire ne bloque l'enregistrement que s'il est visible. |
default_when | Une valeur imposée (et verrouillée, sauf si lock est désactivé) tant qu'une condition est remplie. |
rules_when | Une autre règle (lookup, énumération, booléen) tant qu'une condition est remplie. |
write_when | La colonne n'est écrite que tant qu'une condition est remplie. |
lookup_param_binds | Restreindre la requête d'une règle LOOKUP en liant des paramètres supplémentaires. Utilisé quand la recherche dépend de la valeur d'un autre champ (ex. choisir un rôle restreint par l'application courante de la ligne). Voir Liaison de paramètres. |
Clé primaire
| Champ | Notes |
|---|---|
key | Marque cette colonne comme partie de la clé primaire de la ligne. Pilote : – La correspondance mise à jour-ou-insertion de l'import Excel. – En ajout, une colonne clé présente une saisie libre au lieu de sa liste de lookup (une nouvelle clé se saisit, elle ne se choisit pas). – La liaison :NAME_ORIGINAL de la requête _put (la convention de l'Assistant CRUD). |
Une clé n'est pas verrouillée d'office à la modification d'une ligne : cocher disable_on_edit (onglet Edit) sur les colonnes clés qui ne doivent plus changer une fois la ligne créée. Marquer chaque colonne qui identifie une ligne de façon unique. Les clés multi-colonnes sont prises en charge — activer l'indicateur sur chacune. Quand key_columns de l'écran est vide (le cas habituel), le runtime retombe sur les colonnes dont l'indicateur key est activé.
Filtrage
| Champ | Notes |
|---|---|
filter | Quand activé, la colonne apparaît dans le panneau de filtres du tableau. L'utilisateur choisit une valeur pour restreindre la grille ; sur une colonne à liste de valeurs (une énumération), plusieurs valeurs à la fois, et un code saisi hors de la liste est accepté. Une colonne à lookup garde un choix unique. Une colonne de date (format date, datetime, timestamp, ou type date dans la base) se filtre par une période. |
filter_period | Sur une colonne de date avec filter, la période proposée à l'ouverture de l'écran : today, yesterday, last7, last30, thisMonth, lastMonth, thisQuarter, thisYear, lastYear, last12. Vide ou all : aucune période, toutes les lignes. Le premier chargement automatique de l'écran l'applique déjà. |
filter_from | Filtre en cascade — restreint les options de cette colonne en fonction de la valeur d'un autre filtre. Sélectionne une colonne source (déjà filtrée) et une column sur le résultat de la requête de recherche que la source met en correspondance. |
visible_when | Dans la grille, masque la colonne quand un filtre prend une valeur hors de la condition ; dans le dialogue, n'affiche le champ que tant que les valeurs du formulaire remplissent la condition. |
Les conditions sont détaillées dans Conditions de formulaire, avec des exemples dans Champs conditionnels.
Une colonne typique
Pour une colonne STATUS sur un écran clients, la configuration ressemble habituellement à :
| Champ | Valeur |
|---|---|
name | STATUS |
dd | (vide — utilise STATUS comme clé du dictionnaire) |
label | (vide — hérite du dictionnaire) |
format | (vide — hérite) |
rules | ENUM |
rules_values | STATUS_CODES (un identifiant d'énumération déclaré dans le dictionnaire) |
default | OPEN |
required | ✓ |
filter | ✓ |
Cela affiche une liste déroulante dans le dialogue (alimentée par l'énumération STATUS_CODES), pré-remplit les nouvelles lignes avec OPEN, exige une valeur et ajoute une puce de filtre à la grille.
Hériter du dictionnaire
Le comportement par défaut — quand la plupart des champs sont vides — est d'hériter du dictionnaire. La chaîne :
ColumnHint.label → entrée DD.label → nom de colonne
ColumnHint.format → entrée DD.format → choisi par le moteur selon le type
ColumnHint.rules → entrée DD.rule
ColumnHint.rules_values → entrée DD.rule_values
Cela signifie qu'une colonne nommée USR_ID sur un écran lit automatiquement son libellé, son format, sa règle et l'argument de cette règle depuis l'entrée de dictionnaire USR_ID (ou de l'entrée indiquée dans dd). L'écran ne surcharge que quand cet écran a besoin d'un comportement différent du reste.
L'onglet Colonnes est donc majoritairement vide pour les installations bien dictionnarisées — des entrées n'apparaissent que quand il y a quelque chose à surcharger.
Filtrage et filtres en cascade
Quand une colonne a filter = true, une puce pour celle-ci apparaît dans le panneau de filtres de la grille. L'utilisateur choisit une valeur, la grille réexécute la requête de lecture avec cette valeur liée au paramètre :placeholder correspondant. La requête est responsable d'accepter la liaison.
Une période sur une colonne de date
Sur une colonne de date, le panneau de filtres présente une période et non une date unique : le même sélecteur que sur les tableaux de bord, avec ses préréglages (Aujourd'hui, Hier, 7 derniers jours, 30 derniers jours, Ce mois-ci, Mois dernier, Ce trimestre, Cette année, Année dernière, 12 derniers mois, Toutes les dates) et un calendrier sur deux mois pour une période libre. L'exécution transmet les deux bornes sous la forme <COL>_from et <COL>_to, et le serveur borne lui-même la colonne : la requête de lecture n'a besoin d'aucun paramètre pour elles. Une période qui se termine sur un jour conserve toutes les lignes de ce jour, quelle que soit leur heure.
Un lien ou une navigation qui transmet une date à une colonne de date ouvre l'écran sur ce seul jour.
Les filtres en cascade restreignent les options d'un filtre selon un autre. Le cas classique : une liste déroulante Rôle qui n'affiche que les rôles pour l'Application actuellement sélectionnée :
| Champ | Valeur sur ROLE_ID |
|---|---|
rules | LOOKUP |
rules_values | get_roles |
filter | ✓ |
filter_from.source | APPS_ID (la colonne source du filtre parent) |
filter_from.column | APP_ID (la colonne du résultat de la requête de recherche qui correspond à la source) |
Quand l'utilisateur choisit une application, la recherche de rôles se réexécute avec l'identifiant d'application lié — l'utilisateur ne voit que les rôles de cette application.
Ordre des colonnes
L'ordre de la liste ColumnHint = l'ordre d'affichage dans la grille. Les colonnes que la requête de lecture retourne mais qui ne sont pas listées ici conservent leur ordre de découverte et suivent celles qui sont indiquées.
Pour réorganiser :
| Objectif | Action |
|---|---|
| Monter / descendre une colonne. | Glisser sa ligne dans la liste (la poignée de glissement est sur le bord gauche de la ligne). |
| Masquer une colonne entièrement. | Mettre hidden = true. L'opérateur peut quand même la rendre visible depuis le menu Colonnes de la grille. |
| Retirer une colonne de la grille et du dialogue. | Supprimer son indication ET s'assurer qu'elle n'est sur les champs d'aucun onglet du dialogue. (Ou modifier la requête de lecture pour ne pas la retourner.) |
Pièges courants
| Erreur | Symptôme | Correction |
|---|---|---|
dd = "USR_ID" mais pas d'entrée de dictionnaire nommée USR_ID. | Le libellé et le format retombent textuellement sur le nom de colonne. | Ajouter l'entrée de dictionnaire, ou mettre dd = "" pour se désinscrire et configurer label/format en ligne. |
rules = LOOKUP mais rules_values vide. | La liste déroulante est vide. | Mettre rules_values à un identifiant de recherche du dictionnaire. |
filter_from renseigné mais la colonne n'a pas filter. | La cascade ne fait rien — le filtre source ne se déclenche jamais. | Activer filter = true ET renseigner filter_from. |
required = true sur une colonne que la requête de lecture ne retourne pas. | Le dialogue enregistre avec NULL ; si la BD a une contrainte NOT NULL, l'écriture échoue. | Ajouter la colonne à la requête de lecture, ou retirer required de l'indication. |
key = true sur une colonne non unique. | L'import Excel traite les valeurs en double comme des mises à jour de la même ligne. | Vérifier que les colonnes clés identifient véritablement une ligne de façon unique. |
format = currency mais la valeur est en centimes (entier). | La grille affiche 1,234.00 pour 123456. | Le format attend la valeur dans l'unité à afficher — diviser par 100 dans la requête, ou utiliser une étape Python avant l'affichage. |
Étapes suivantes
- Constructeur de dialogue — les champs configurés ici deviennent des cartes glissables-déposables sur le canevas.
- Champs conditionnels — faire apparaître / rendre obligatoire / verrouiller une colonne uniquement sous certaines conditions de formulaire.
- Concepts → Dictionnaire — le vocabulaire partagé dont les colonnes héritent.