Succès et erreurs de formulaire

La soumission est validée et la requête revient. Ce qui se passe alors à l'écran relève d'une décision produit, pas d'une décision technique : un ticket de support veut un numéro de référence, une inscription à une newsletter veut rester en place pour accepter une autre adresse, un tunnel d'achat veut passer à la suite.

onSuccess et onError rendent cette décision déclarative :

forms:
  - id: 1
    name: contact
    title: Contact Sales
    submitTo: { table: leads }
    fields:
      - { kind: table-field, column: email, required: true }
    onSuccess:
      type: successPage
      title: Thank you
      message: We received your message and will reply within one business day.
    onError:
      type: message
      message: Something went wrong saving your request. Please try again.

Types de onSuccess

onSuccess est une union discriminée par type. Chaque type porte ses propres propriétés.

type	Propriétés	Comportement
successPage	title, message, buttonLabel, buttonHref, actions[], showSummary	Remplace le formulaire par un écran de succès.
redirect	url (obligatoire), delaySeconds	Navigue ailleurs. delaySeconds vaut 2 par défaut ; 0 navigue immédiatement.
reset	message, preserveFields[]	Vide le formulaire pour une nouvelle saisie, en conservant les champs listés.
toast	message (obligatoire), variant (success | info)	Affiche une notification passagère et laisse le formulaire rempli en place.
message	message (obligatoire)	Remplace le formulaire par un message en ligne.

Omettez onSuccess et le formulaire retombe sur un toast success affichant « Submitted. » — un défaut raisonnable, rarement celui qu'on veut en production.

reset est le type indiqué pour un formulaire sur une seule page qu'un contributeur remplit à répétition. Sur une mise en page multi-step, il vide bien les réponses mais ne ramène pas le contributeur à la première étape : préférez-y successPage assorti d'une action reset.

Actions de la page de succès

Une successPage peut proposer une suite au contributeur. Chaque entrée d'actions[] est rendue sous forme de bouton :

onSuccess:
  type: successPage
  title: Ticket received
  message: Our team has been notified.
  showSummary: true
  actions:
    - { label: Submit another, action: reset }
    - { label: Back to help centre, action: navigate, url: /help }

Propriété	Description	Défaut
label	Texte du bouton. Prend en charge les clés $t:.	Obligatoire.
action	reset restitue le formulaire vide ; navigate envoie le contributeur vers url.	Obligatoire.
url	Cible de navigation. Obligatoire pour navigate, ignorée par reset.	—

showSummary: true récapitule les valeurs soumises sous le message. Le récapitulatif ignore les champs masqués et applique les permissions de lecture par champ : il ne montre jamais au contributeur une donnée qu'il n'avait pas le droit de relire.

Variables de gabarit

Le texte de succès et la cible de redirection peuvent citer la soumission qui vient d'avoir lieu. Trois variables sont substituées au moment de l'envoi, aussi bien dans title et message que dans url :

Variable	Se résout en
$submission.id	L'identifiant de la ligne de registre. Vide si submitTo.storeSubmission vaut false.
$record.id	L'identifiant de la ligne dans la table liée. Vide si le formulaire n'a pas de submitTo.table.
$record.<column>	Une colonne de la ligne insérée — mais uniquement une colonne fournie par le contributeur.

onSuccess:
  type: redirect
  url: /thank-you?ref=$submission.id
  delaySeconds: 0

Les valeurs substituées dans une url sont encodées en pourcentage : une adresse e-mail survit donc intacte à la chaîne de requête. La restriction sur $record.<column> est délibérée : les colonnes calculées côté serveur et les colonnes privilégiées ne sont jamais exposées via une URL de redirection, si tentant que soit le raccourci.

onError

onError couvre les échecs portant sur la soumission entière — l'écriture a été refusée, la requête n'a pas abouti.

Propriété	Description	Défaut
type	toast, message (en ligne) ou errorPage (page entière).	Obligatoire.
message	Corps du message. Prend en charge les clés $t:.	Obligatoire.
title	Titre, utilisé par errorPage.	—
variant	error ou warning. N'a de sens que pour type: toast.	error

Omis, il retombe sur un toast affichant « Submission failed. »

Les erreurs de validation par champ empruntent un autre canal. Une adresse e-mail invalide ou une valeur obligatoire manquante revient sous forme de liste fieldErrors et s'affiche en ligne contre la saisie fautive — onError se déclenche en parallèle comme synthèse du formulaire, et non à sa place.

Pages associées

• Soumissions — l'écriture double qui doit être validée avant que onSuccess s'exécute.
• Champs de formulaire — les permissions de lecture par champ que showSummary respecte.
• Formulaires multi-étapes — ce que « après la dernière étape » signifie pour ces types.
• Présentation des formulaires — la place de onSuccess et onError dans le schéma complet.