Skip to main content
View as Markdown

Présentation des formulaires

Les formulaires recueillent les saisies des contributeurs et les acheminent vers une destination utile — dans une table, via une automatisation, dans le registre de soumissions intégré, ou n'importe quelle combinaison des trois. Ils sont déclarés dans le tableau de premier niveau forms, chacun accessible à sa propre URL, intégrable dans une page et adressable depuis un déclencheur d'automatisation.

Un formulaire est le pendant public d'une table : là où une table définit à quoi ressemblent les données, un formulaire définit comment les gens y contribuent. Le même formulaire peut écrire directement dans une entrée tables[], déclencher une automatisation notify-sales, ou simplement atterrir dans le registre form_submissions de la plateforme pour une révision ultérieure.

forms:
  - id: 1
    name: contact
    title: Contact Sales
    path: /contact
    submitTo:
      table: leads
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: message }

Propriétés du formulaire

Chaque entrée du tableau forms accepte les propriétés suivantes.

Propriété Description
id Entier positif unique identifiant le formulaire. Doit être unique dans forms[].
name Identifiant unique en kebab-case (^[a-z][a-z0-9-]*, 1 à 64 caractères). Référencé par les composants de page (formRef) et le déclencheur d'automatisation de formulaire. Doit être unique dans forms[].
title Titre lisible affiché aux contributeurs. Prend en charge les clés i18n $t:.
description Paragraphe d'introduction optionnel affiché au-dessus du premier champ.
path URL publique conviviale optionnelle (par ex. /contact). Lorsqu'elle est définie, le formulaire est servi à cet emplacement et à la route canonique /forms/{name}. Voir Routes publiques.
submitTo Où la soumission est persistée et/ou acheminée : une table, une automatisation, le registre, ou une combinaison. Obligatoire. Voir Cibles de soumission.
fields Liste ordonnée de définitions de champs affichés dans le formulaire. Au moins un requis. Voir Champs de formulaire.
layout Mode de rendu : single-page (par défaut), multi-step ou one-question. Voir Formulaires multi-étapes.
steps Définitions d'étapes pour les mises en page multi-step / one-question. Voir Formulaires multi-étapes.
fieldGroups Séparateurs de section libellés regroupant les champs au sein d'une mise en page sur une seule page.
display Options cosmétiques (colonnes, barre de progression, libellé du bouton de soumission, thème par formulaire). Voir Formulaires multi-étapes.
access Contrôle d'accès : all, authenticated, ou une liste de rôles, avec un redirectTo optionnel. Voir Contrôle d'accès.
availability Fenêtre de soumission (opensAt, closesAt) et plafond de soumissions (maxSubmissions), avec une page de formulaire fermé personnalisée optionnelle.
antiSpam Pot de miel, limites de débit à fenêtre glissante, et un stub de connexion CAPTCHA.
analytics Désactivation par formulaire (enabled: false) excluant le formulaire des analyses agrégées. Activé par défaut.
prefill Mappage champ de formulaire → référence $query.{name} / $user.{prop} / $parent.{path} ou valeur littérale par défaut. Voir Champs de formulaire.
submitter Règles d'enregistrement-et-reprise, de modification-après-soumission et de soumission unique.
onSuccess Comportement post-soumission (page de succès, redirection, réinitialisation, toast, message en ligne). Voir Soumissions.
onError Ce qu'il faut afficher quand une soumission échoue côté serveur (toast, message en ligne, page d'erreur). Voir Soumissions.

Cibles de soumission

L'objet submitTo découple un formulaire de tout modèle de persistance unique. Au moins l'un de table, automation, ou storeSubmission: true (la valeur par défaut) doit être défini — sinon la soumission serait silencieusement rejetée et le schéma rejette la configuration.

Propriété Description
table Persiste la soumission comme un enregistrement dans cette table. Référence un tables[].name ; validé par rapport au tableau tables[] de l'application.
automation Invoque cette automatisation après la validation des écritures. Référence un automations[].name ; validé par rapport au tableau automations[] de l'application.
mapping Mappe les noms de champs de formulaire vers les noms de colonnes de destination. Par défaut l'identité (nom du champ de formulaire = nom de la colonne de table). Une cible de mappage qui n'existe pas sur la table échoue à la validation.
storeSubmission Persiste la soumission dans le registre intégré form_submissions. Vaut true par défaut — définissez false pour vous désinscrire (et alors table ou automation devient obligatoire). 
submitTo:
  table: support_tickets
  automation: page-on-call
  mapping:
    userEmail: email # form field 'userEmail' -> table column 'email'

Routes publiques

Chaque formulaire est accessible à la route canonique /forms/{name} quelle que soit la configuration — un formulaire sans path n'est pas privé, il est simplement uniquement accessible à cet emplacement. Lorsque path est défini, le formulaire est servi à ce chemin personnalisé et à /forms/{name} simultanément (pas de redirection ; les deux URL affichent le même formulaire).

Règle Description
Route canonique /forms/{name} sert toujours le formulaire (HTTP 200). Un nom inconnu renvoie 404.
Chemin personnalisé Optionnel. Doit commencer par /, 2 à 256 caractères compatibles URL ; statique (pas de segments dynamiques :id).
Préfixes réservés /api/, /admin/, /forms/ et /auth/ sont rejetés afin qu'un formulaire ne puisse pas masquer une route intégrée.
Règle de collision Un forms[].path NE DOIT PAS entrer en collision avec un pages[].path. Les collisions échouent à la validation avec une erreur nommant les deux.
Route d'intégration /forms/{name}/embed sert une coquille HTML minimale pour l'intégration en iframe sur des sites tiers.

Contrôle d'accès

L'objet access réutilise le modèle de permission partagé employé par les tables, les pages, les buckets, les automatisations et les agents.

Propriété Description
require 'all' (tout le monde, y compris anonyme), 'authenticated' (tout utilisateur connecté), ou une liste de rôles (['admin', 'editor']).
redirectTo Chemin optionnel (par ex. /login) vers lequel rediriger les contributeurs refusés, au lieu de renvoyer un 401/403. Doit commencer par /. 
forms:
  - id: 2
    name: member-survey
    title: Member Survey
    access:
      require: authenticated
      redirectTo: /login
    submitTo: { table: survey_responses }
    fields:
      - { kind: standalone, name: rating, inputType: rating, required: true }

Intégrer un formulaire dans une page

Un formulaire de premier niveau peut être affiché en ligne dans une page via le formRef du contrôle de formulaire. Le formulaire est défini une fois et réutilisé n'importe où — les champs, la validation, la logique conditionnelle, la mise en page multi-étapes, les téléversements de fichiers, et onSuccess/onError proviennent tous de app.forms[]. Le contrôle d'accès de la page hôte est croisé avec les propres règles du formulaire au moment du rendu.

pages:
  - id: 1
    name: landing
    path: /
    components:
      - type: form
        formRef: contact # renders the top-level "contact" form inline
        props:
          label: Get in touch # display-only override of the submit label

Voir Contrôles de formulaire pour le côté composant de page de formRef.

Pages associées