# Préremplissage des formulaires

Un formulaire qui connaît déjà la réponse ne devrait pas la demander. La campagne qui a amené le visiteur est dans l'URL ; l'adresse e-mail de l'utilisateur connecté est dans la session. Poser quand même la question coûte un champ, et la réponse obtenue vaut moins que celle qu'on avait déjà.

`prefill` associe des noms de champs à l'origine de leur valeur initiale :

```yaml
forms:
  - id: 1
    name: lead-capture
    title: Request a demo
    submitTo: { table: leads }
    prefill:
      utm_source: $query.utm_source
      utm_campaign: $query.utm_campaign
      plan: Starter
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: plan, inputType: short-text }
      - { kind: standalone, name: utm_source, inputType: short-text, hidden: true }
      - { kind: standalone, name: utm_campaign, inputType: short-text, hidden: true }
```

## Sources de préremplissage

Chaque valeur de la table est soit une référence, soit un littéral. Les références sont résolues côté serveur pendant le rendu du formulaire.

| Source                  | Se résout en                                                                                 | Si la résolution échoue                     |
| ----------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `$query.<name>`         | Le paramètre de chaîne de requête nommé, dans l'URL de la requête qui a rendu le formulaire. | Entrée supprimée ; le champ s'affiche vide. |
| `$user.<prop>`          | Une propriété de l'utilisateur connecté — `$user.email`, `$user.id`.                         | Entrée supprimée ; le champ s'affiche vide. |
| Chaîne, nombre, booléen | Elle-même, telle quelle — une valeur par défaut que le contributeur peut remplacer.          | —                                           |

Une référence non résolue est retirée de la table, jamais affichée. Le contributeur voit une saisie vide, et le littéral `$query.utm_campaign` ne fuit jamais dans le HTML.

## Champs masqués préremplis

Un préremplissage sur un champ `hidden: true` est tout l'intérêt de la fonctionnalité pour le travail d'attribution. Le champ est rendu sous forme d'`<input type="hidden">` porteur de la valeur résolue : la campagne d'où vient le visiteur entre dans l'enregistrement sans jamais apparaître à l'écran, et sans script de suivi écrit à la main.

```yaml
prefill:
  campaign: $query.ref
fields:
  - { kind: table-field, column: email, required: true }
  - { kind: table-field, column: campaign, hidden: true }
```

`/forms/lead-capture?ref=partner-x` stocke désormais `partner-x` dans la colonne `campaign` de l'enregistrement.

## `$user` exige une session

`$user.<prop>` ne se résout que si la requête porte une session authentifiée, ce qui suppose en pratique que le formulaire en exige une. Sur un formulaire public, la référence est simplement abandonnée et le champ s'affiche vide — sans erreur, sans fuite d'état de session.

Cette tolérance est propre à la table `prefill`. Un `defaultValue: $user.email` posé sur un champ d'un formulaire public relève de l'erreur de configuration plutôt que du haussement d'épaules à l'exécution : il est rejeté au décodage de la configuration, avec un message nommant le formulaire et le champ fautif. Exigez l'authentification, ou déplacez la référence dans `prefill`.

:::callout
**`$parent` et `$record` ne se résolvent pas ici.** Le schéma les accepte, mais la table `prefill` de premier niveau est résolue contre la requête — chaîne de requête et session — et ignore tout d'un enregistrement hôte. Tout jeton qu'elle ne reconnaît pas passe tel quel comme chaîne littérale : `$parent.id` dans `forms[].prefill` affiche donc les caractères `$parent.id` dans le champ. Le préremplissage depuis un enregistrement parent appartient au contrôle de formulaire de la page, sous `inlinePrefill`, là où un enregistrement hôte existe réellement.
:::

## `prefill` ou `defaultValue`

Les deux alimentent une valeur initiale, et les deux acceptent les références `$query` / `$user`. Le choix porte sur l'endroit où vit le câblage.

| À utiliser     | Quand                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `prefill`      | Attribution et amorçage depuis la session — le câblage relève du formulaire, et se lit mieux regroupé en un bloc. |
| `defaultValue` | Une valeur qui fait partie de la définition même du champ, comme une quantité de départ fixe.                     |

## Pages associées

- [Champs de formulaire](/fr/docs/form-fields) — `defaultValue`, `hidden`, et les champs qu'une clé de préremplissage désigne.
- [Contrôles de formulaire](/fr/docs/form-controls) — `inlinePrefill`, où `$parent` et `$record` se résolvent.
- [Contrôle d'accès](/fr/docs/form-access) — le niveau `require` qui rend `$user` résolvable.
- [Présentation des formulaires](/fr/docs/forms-overview) — la place de `prefill` dans le schéma complet.