Groupes de champs

Un formulaire de vingt champs rendu en une seule colonne plate oblige le contributeur à lire chaque saisie avant d'en comprendre une seule. Les mêmes champs sous trois intitulés — « À votre sujet », « Votre expérience », « Pourquoi nous » — deviennent quelque chose qu'on parcourt du regard et qu'on remplit section par section.

fieldGroups déclare ces intitulés. Chaque entrée associe un libellé aux noms des champs qui lui appartiennent :

forms:
  - id: 1
    name: apply
    title: Apply for Senior Engineer
    submitTo: { table: candidates }
    fieldGroups:
      - label: About you
        fields: [first_name, last_name, email]
      - label: Your experience
        fields: [years_of_experience, github_url]
    fields:
      - { kind: table-field, column: first_name, required: true }
      - { kind: table-field, column: last_name, required: true }
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: years_of_experience, inputType: number }
      - { kind: standalone, name: github_url, inputType: url }

Propriétés d'un groupe

Propriété	Description	Défaut
label	Intitulé de section affiché au-dessus des champs du groupe. Au moins un caractère.	Obligatoire.
fields	Noms des champs appartenant à la section, dans l'ordre d'affichage souhaité. Au moins un.	Obligatoire.
visibleWhen	Condition qui régit la section entière. Même forme et mêmes opérateurs que le visibleWhen d'un champ.	Toujours visible.

fieldGroups est lui-même optionnel. Omettez-le et le formulaire affiche fields[] de haut en bas sans aucun intitulé — le bon choix pour un formulaire assez court pour se passer de balisage. Lorsqu'il est présent, le tableau doit déclarer au moins un groupe.

L'ordre vient des groupes

Dès lors que fieldGroups existe, c'est lui qui pilote la mise en page : les sections s'affichent dans l'ordre du tableau, et chaque champ apparaît à la place que lui donne son groupe. Le regroupement peut donc réorganiser un formulaire sans toucher à fields[] — fields[] continue de définir ce que sont les champs, les groupes définissent où ils apparaissent.

Un champ que vous n'avez listé nulle part s'affiche quand même. Il retombe tout en bas, après toutes les sections, dans l'ordre source de fields[]. Regrouper la moitié d'un formulaire est donc valide : les champs nommés reçoivent leurs intitulés, les autres suivent en bloc non libellé.

Sections conditionnelles

visibleWhen conditionne une section entière — le libellé et tous ses champs — à la valeur d'un autre champ, avec la même primitive de condition que les règles au niveau du champ :

fieldGroups:
  - label: Preferences
    fields: [wants_relocation]
  - label: Relocation
    fields: [relocation_country, relocation_date]
    visibleWhen: { field: wants_relocation, operator: eq, value: true }

La règle est évaluée côté serveur. Au premier rendu aucune réponse n'existe encore : une section conditionnelle démarre donc masquée et apparaît dès que son déclencheur est renseigné. À la soumission, la règle est réévaluée, cette fois contre les valeurs soumises, et une section dont la règle est fausse est traitée comme si elle n'avait jamais fait partie du formulaire : ses champs obligatoires ne bloquent pas l'envoi.

Groupes ou étapes

Les deux découpent un formulaire, et les deux acceptent un visibleWhen. La différence tient à ce que le contributeur voit d'un seul coup.

À utiliser	Quand
fieldGroups	Tous les champs restent sur une page et un seul défilement ; les intitulés donnent la structure. Exige layout: single-page (le défaut).
steps	Les champs sont répartis sur plusieurs écrans, avec navigation précédent/suivant et validation par étape. Exige layout: multi-step ou one-question.

Pages associées

• Champs de formulaire — les entrées fields[] qu'un groupe désigne par leur nom.
• Logique conditionnelle — le vocabulaire d'opérateurs dans lequel puise visibleWhen.
• Formulaires multi-étapes — steps[], l'alternative multi-écrans aux groupes.
• Présentation des formulaires — la place de fieldGroups dans le schéma complet.