Skip to main content
View as Markdown

Champs de formulaire

Le tableau fields d'un formulaire est une liste ordonnée de définitions de champs affichés de haut en bas. Chaque champ est l'un de cinq types (kinds), distingués par une propriété kind. Les champs liés à une table héritent de leur type et de leur validation d'une colonne de table ; les champs autonomes sont typés en ligne ; les champs de calcul, de section et de signature couvrent les valeurs calculées, les séparateurs et les signatures.

forms:
  - id: 1
    name: signup
    title: Create your account
    submitTo: { table: users }
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: newsletter, inputType: checkbox, label: Subscribe to updates }

Types de champs

Type Description
table-field Lié à une colonne de submitTo.table. Le type, la validation et la persistance proviennent du schéma de table ; le formulaire ne surcharge que l'affichage.
standalone Typé en ligne via inputType ; non persisté directement dans une colonne. À utiliser pour les formulaires qui n'acheminent que vers des automatisations ou le registre.
calculation Valeur calculée en lecture seule dérivée d'autres champs via une formule {{fieldName}}. N'affiche aucune saisie.
section Séparateur visuel avec un titre et une description optionnels. N'affiche aucune saisie.
signature Capture une signature manuscrite ou saisie au clavier.

Propriétés communes des champs

Chaque type de champ portant une saisie (table-field, standalone, calculation, signature) partage une base commune.

Propriété Description
label Libellé affiché au contributeur. Prend en charge les clés i18n $t:.
placeholder Texte indicatif affiché lorsque le champ est vide.
helpText Texte d'aide affiché sous le champ.
required Booléen. Lorsque true, le champ doit avoir une valeur. Pour une obligation conditionnelle, utilisez requiredWhen.
readOnly Booléen. Affiche le champ en lecture seule.
hidden Booléen. Masque le champ de l'interface mais le soumet quand même (valeur côté serveur uniquement).
defaultValue Valeur littérale, ou une référence $query.{name} / $user.{prop} résolue au moment du rendu.
visibleWhen Règle de visibilité conditionnelle. Voir Logique conditionnelle.
requiredWhen Règle d'obligation conditionnelle (même forme que visibleWhen).
disabledWhen Règle de désactivation conditionnelle (même forme que visibleWhen).
permissions Permission read par champ. Lorsque le rôle demandeur est exclu, la valeur est masquée des exports admin et du détail par soumission.

Champs liés à une table

Un kind: table-field référence une column sur la submitTo.table du formulaire. Le type de champ, la validation et la persistance proviennent tous du schéma de table — le formulaire ne fournit que les aspects d'affichage plus, pour les colonnes de pièce jointe, les options de téléversement.

Propriété Description
column Nom de la colonne sur submitTo.table. Obligatoire.
accept Types MIME ou extensions séparés par des virgules pour les colonnes de pièce jointe.
maxFileSize Taille maximale (octets) par fichier téléversé (colonnes de pièce jointe).
maxFiles Nombre maximal de fichiers pour les colonnes multiple-attachments.
dropZone Affiche une zone de glisser-déposer à côté du sélecteur de fichiers. 
fields:
  - kind: table-field
    column: subject
    label: What can we help with?
    placeholder: Briefly describe the issue
  - kind: table-field
    column: priority
    helpText: Urgent issues are triaged first

Les colonnes de pièce jointe (single-attachment, multiple-attachments) affichent automatiquement une saisie de fichier. Voir Téléversements de fichiers pour le pipeline de téléversement et la liaison au bucket.

Champs autonomes

Un champ kind: standalone est typé en ligne via inputType et n'est pas écrit directement dans une colonne de table. Il est idéal pour les formulaires qui acheminent vers une automatisation ou vivent uniquement dans le registre de soumissions.

Propriété Description
name Nom de champ unique au sein du formulaire (^[a-zA-Z][a-zA-Z0-9_-]*, ≤64 caractères). Obligatoire.
inputType Type de contrôle (voir ci-dessous). Obligatoire.
options Choix { value, label } pour select / multi-select / radio.
accept Types MIME acceptés pour la saisie attachment.
maxFiles Nombre maximal de fichiers pour la saisie attachment.
maxFileSize Taille maximale (octets) par fichier téléversé.
dropZone Affiche une zone de glisser-déposer à côté du sélecteur de fichiers.

Valeurs inputType disponibles : short-text, long-text, email, url, phone, number, date, datetime, select, multi-select, checkbox, radio, rating, attachment.

fields:
  - kind: standalone
    name: rating
    inputType: rating
    label: How was your experience?
    required: true
  - kind: standalone
    name: source
    inputType: select
    label: How did you hear about us?
    options:
      - { value: search, label: Search engine }
      - { value: referral, label: Referral }
      - { value: social, label: Social media }

Champs de calcul, de section et de signature

Type Propriétés clés
calculation name, formula (référence d'autres champs via {{name}}), format optionnel (number / currency / percent / text). Lecture seule.
section heading, description optionnels, et une règle visibleWhen pour toute la section. N'affiche aucune saisie.
signature name. Capture une signature manuscrite ou saisie au clavier. 
fields:
  - { kind: standalone, name: quantity, inputType: number, label: Quantity }
  - { kind: standalone, name: unit_price, inputType: number, label: Unit price }
  - kind: calculation
    name: total
    label: Total
    formula: '{{quantity}} * {{unit_price}}'
    format: currency

Préremplissage

Le mappage prefill de premier niveau initialise les valeurs des champs au moment du rendu. Les clés sont des noms de champs de formulaire ; les valeurs sont soit une valeur littérale par défaut, soit une référence :

Référence Se résout en
$query.{name} Un paramètre de chaîne de requête d'URL (par ex. $query.utm_source).
$user.{prop} Une propriété de l'utilisateur authentifié (par ex. $user.email). Silencieusement ignoré sur les formulaires publics sans session.
$parent.{path} Un champ de l'enregistrement parent — valide uniquement pour les formulaires de relation en ligne (voir ci-dessous). 
forms:
  - id: 1
    name: lead-capture
    title: Request a demo
    submitTo: { table: leads }
    prefill:
      utm_source: $query.utm_source
      utm_campaign: $query.utm_campaign
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: utm_source, inputType: short-text, hidden: true }
      - { kind: standalone, name: utm_campaign, inputType: short-text, hidden: true }

Création de relation en ligne

Lorsqu'un formulaire est intégré dans la page de détail d'un enregistrement parent (par ex. un bouton « + Nouveau ticket » sur une page Projet), la source de préremplissage $parent.{path} relie automatiquement le nouvel enfant à son parent. Cela se configure sur le contrôle de formulaire de page via inlinePrefill.

Propriété Description
prefill Mappage nom-de-champ → source-de-préremplissage (même union $query / $user / $parent).
lockPrefill Lorsque true, les champs préremplis sont masqués et ne peuvent pas être surchargés (toujours validés côté serveur). Vaut false par défaut. 
forms:
  - id: 1
    name: new-ticket
    submitTo: { table: tickets }
    fields:
      - { kind: table-field, column: title, required: true }
      - { kind: table-field, column: project_id }
      - { kind: table-field, column: reporter_id }

pages:
  - id: 1
    name: project-detail
    path: /portal/projects/:id
    components:
      - type: form
        formRef: new-ticket
        inlinePrefill:
          prefill:
            project_id: $parent.id # locked to the current project
            reporter_id: $user.id
          lockPrefill: true

À la soumission, le moteur revalide l'existence du parent pour se prémunir contre les références $parent obsolètes. Les colonnes de relation simple et multiple sont toutes deux prises en charge.

Pages associées