Form

Form collecte, valide et envoie un ensemble cohérent de champs. Il convient aux demandes, inscriptions, réglages, fiches d'édition et étapes de workflow. Le composant gère les sections, la mise en page, l'état de validation et le périmètre d'envoi.

Ce guide explique comment organiser les champs, régler la grille, ajouter les validations, configurer Reset / Validate / Submit et traiter le contexte de page côté Java.

1. Capacités et configuration du Form

La configuration se répartit sur quatre niveaux :

1. Form gère la mise en page, le mode, le chargement, l'envoi, les brouillons et l'état public.
2. Form Section regroupe les champs par sujet métier et peut représenter une collection répétable.
3. Field définit le libellé, la Field Key, la valeur initiale, l'occupation de la ligne, les conditions et les validations.
4. Button Set / Interaction orchestre Reset, Validate, Submit et les fonctions du composant.

1.1 Vue d'ensemble des propriétés et fonctions

Zone	Principales propriétés ou fonctions	Utilité
Structure	ID / Name, Form Sections, Fields, Button Set	Définir le périmètre du Form, les groupes métier et les données envoyées
Mise en page	Controls Per Row, Form column split, Layout, Label Alignment, Full row	Régler la densité, la largeur des libellés et les champs pleine ligne
Mode	Create, Edit, View, Warn about unsaved changes	Gérer la création, l'édition, la lecture seule et la sortie avec modifications
Adaptateur de données	Load / Create / Update URL, Response Data Path, Record ID, Revision	Charger un enregistrement et connecter les API avec verrouillage optimiste
Envoi	Full values, Changed values only, Custom URL	Envoyer toutes les valeurs ou uniquement les changements
Validation	Required, Length, Pattern, Number, Custom Validator, Remote validation	Afficher les erreurs locales, distantes et renvoyées par le serveur
Conditions	Visible / Disabled / Required When, Dependencies, Clear When Hidden	Réagir aux autres champs, au Page Context ou au mode courant
Groupe répétable	Collection Key, Minimum / Maximum Items, Add / Delete	Modifier des tableaux d'objets, par exemple des contacts ou des lignes
Brouillons	Browser / Remote storage, Draft Key, Autosave Delay, revision	Enregistrer, restaurer ou supprimer un travail inachevé
Actions et état	reset, validate, submit, saveDraft, restoreDraft, discardDraft ; forms.*	Orchestrer les actions et lire valid, dirty ou submitting
Génération	Business Object, JSON Schema, OpenAPI	Produire une structure de champs modifiable depuis un modèle

1.2 Structure et périmètre d'envoi

Form constitue à la fois une frontière d'état et une frontière d'envoi. Une page peut contenir plusieurs Forms ; chacun ne gère que ses propres Sections, Fields et Button Set.

• Form Section exprime un groupe métier, pas un simple espace visuel.
• Field Key est le nom stable dans l'état du Form et le JSON envoyé ; il doit correspondre au DTO backend.
• Button Set place les actions, tandis qu'Interaction décide si un bouton exécute Reset, Validate ou Submit.
• Submit Form collecte uniquement les champs enregistrés dans le Form ciblé, sans ajouter un autre Form, le Page Context ou le Tree Current Record.

Sur une page contenant un Form de recherche et un Form d'édition, attribuez deux ID et ciblez explicitement le bon Form dans chaque action.

1.3 Mise en page et comportement adaptatif

Controls Per Row fixe le nombre maximal de champs par ligne et donc la largeur de grille disponible. Form column split répartit cette zone entre Label et Content : avec deux contrôles par ligne, la somme vaut 12 ; avec un contrôle, elle vaut 24.

Layout propose Horizontal, Vertical et Inline. Label Alignment ne s'applique qu'aux libellés du mode Horizontal. Full row / Start on new row réserve une ligne aux champs longs tout en conservant l'alignement du premier libellé. Sur un écran étroit, les champs s'empilent selon l'ordre de lecture sans créer un second Form mobile.

1.4 Modes, chargement et envoi

Mode	Comportement	Interface habituelle
Create	Part des valeurs initiales et crée un enregistrement	Create URL, généralement POST
Edit	Charge puis modifie un enregistrement	Load URL + Update URL, généralement PUT / PATCH
View	Réutilise la présentation libellé/valeur en lecture seule	Load URL, sans actions d'édition

L'adaptateur lit l'enregistrement via Response Data Path et conserve Record ID Field ainsi que Revision Field pour l'identité et le verrouillage optimiste. Les valeurs chargées deviennent la référence de Reset et de Changed values only. Custom URL convient à un envoi simple ; l'adaptateur complet est préférable pour charger, modifier, détecter les conflits ou restaurer un brouillon.

1.5 Validation, erreurs de champ et conditions

Les règles locales Required, Length, Pattern, Number et Custom Validator fournissent un retour immédiat. Remote validation interroge le backend pour un e-mail, un identifiant ou un code métier avec un déclencheur et un délai configurables. Lors de l'envoi, le backend peut retourner fieldErrors ; Form rattache chaque message au Field Key concerné.

Visible When, Disabled When et Required When lisent state.*, context.*, record.* ou form.*. Dependencies déclare les Field Keys qui provoquent un nouveau calcul, tandis que Clear When Hidden supprime une ancienne valeur devenue invisible. Ces fonctions améliorent l'interface, mais ne remplacent jamais validation et autorisation côté serveur.

1.6 Groupes répétables et brouillons

Une Form Section répétable devient le modèle d'une ligne. Collection Key correspond à un tableau d'objets dans le JSON ; Minimum / Maximum Items limitent le nombre de lignes et Runtime propose Add / Delete. Les chemins d'erreur conservent l'index pour identifier précisément la ligne fautive.

Un brouillon enregistre l'état non soumis, pas la fiche métier définitive. Browser storage convient à un usage personnel sur un appareil ; Remote service utilise Load / Save URL, Draft Key et revision pour le multiappareil. Un conflit de revision doit demander une restauration ou un rechargement, sans écrasement silencieux.

1.7 Actions et état public

Opération	Comportement
reset	Restaure la référence chargée ou les valeurs initiales et efface les erreurs
validate	Valide le Form et interrompt la suite en cas d'échec
submit	Valide, construit le payload, envoie la requête et traite les erreurs de champ
saveDraft / restoreDraft / discardDraft	Enregistre, restaure ou abandonne le brouillon

Les expressions peuvent lire forms.<formId>.valid, dirty, submitting, submitError, lastSubmit et mode. Ces états sont en lecture seule. Une étape de workflow peut par exemple exécuter Submit Form, puis nextStep uniquement en cas de succès.

1.8 Génération et coopération avec le backend

Generate fields crée des Sections et Fields depuis un Business Object, JSON Schema ou OpenAPI Schema. Le résultat reste modifiable ; vérifiez ensuite les libellés, champs sensibles, options, permissions, disposition et interfaces.

Les requêtes de chargement, validation distante, brouillon et envoi reçoivent automatiquement X-Spark-Page-Environment et X-Spark-Page-Render-Mode. Le backend peut fournir des données de test en DESIGN_PREVIEW et exécuter le cas métier réel en RUNTIME. Ce contexte ne remplace ni l'authentification, ni l'isolation du tenant, ni l'autorisation.

1.9 Choisir un parcours

Objectif	Point de départ	Sections utiles
Création simple	Create + Sections + validation locale + Custom URL	2 à 8
Modifier une fiche	Edit + Load / Update URL + Record ID / Revision	9, 10 et 14
Affichage seul	View + Load URL	10
Champs dynamiques	Conditions + Dependencies	11 et 12
Contacts ou lignes	Repeatable Group	13
Saisie longue	Draft + avertissement de sortie	15
Génération depuis un modèle	Generate fields	16

1.10 Champs disponibles dans Form

Choisissez d’abord le champ selon la forme des données, puis configurez la mise en page, la validation et Interaction. La palette propose actuellement les 22 composants ci-dessous. Les anciens Select, MultiSelect et MultiRowInput restent masqués uniquement pour la compatibilité des pages existantes.

Catégorie	Composants	Données adaptées
Saisie de base	Input, Address, Text Area	Texte court, adresse et texte long
Sélection et personnes	Select, Radio Button, Checkbox, Switch, Cascade Select, Tree Select, Transfer, User Select, Department Select	Enums, hiérarchies, ensembles, utilisateurs et départements
Dates et nombres	Date Picker, Time Picker, Calendar, Rate, Slider	Dates, heures, notes, nombres et plages
Éditeurs	Rich Text, Code Editor, JSON Editor	Contenu formaté, scripts et JSON
Fichiers et données structurées	Upload, Multi-Row Input	Métadonnées de fichier et tableaux d’objets

Chaque guide détaille les usages, propriétés, valeurs soumises, conditions et Interaction. Basez le choix sur le contrat de données backend, pas uniquement sur l’apparence.

2. Exemple : demande d'intégration d'un collaborateur

La page Form de Spark Sample comporte deux sections, une disposition sur deux colonnes, un champ de justification sur toute la ligne et trois actions.

Screen
└── Form: Employee Onboarding Form
    ├── Employee details
    │   ├── Full name / Work email / Department
    │   └── Employment type / Start date
    ├── Equipment and access
    │   ├── Laptop budget / Administrator access
    │   └── Request justification (ligne entière)
    └── Reset / Validate / Submit request

3. Ajouter le Form et ses sections

1. Ajoutez Form dans Screen, Panel, Grid Column, Tab, Step ou Content.
2. Sélectionnez-le et ajoutez des éléments dans Form Sections.
3. Dans chaque section, ajoutez Field, Select, RadioBox, DatePicker, Switch ou TextArea sous Fields.
4. Ajoutez les actions dans le Button Set du Form.
5. Attribuez des ID et Name stables, enregistrez, puis vérifiez le mode Conception et le Runtime.

Utilisez les sections pour des regroupements métier, par exemple Informations, Accès, Pièces jointes et Confirmation.

4. Mise en page

Controls Per Row fixe le nombre maximal de champs ordinaires par ligne. 2 est un bon point de départ sur PC ; 1 convient aux textes longs ; 3 ou 4 sont réservés aux filtres compacts. Sur un écran étroit, les champs s'empilent dans l'ordre de lecture.

La grille interne comporte 24 colonnes, mais le partage est calculé dans la zone de chaque champ. Avec deux contrôles par ligne, chaque champ dispose de 12 colonnes :

Label 4 + Content 8 = 12

Avec un contrôle par ligne, utilisez un total de 24, par exemple 6 + 18. La réglette Form column split modifie les deux valeurs ensemble.

Activez Start on new row / Full row pour un TextArea long. Son libellé conserve le ratio du Form et reste aligné sur le premier libellé de la ligne précédente.

Layout	Usage
Horizontal	Libellé et champ côte à côte
Vertical	Libellé au-dessus, adapté aux zones étroites
Inline	Champs et boutons sur une ligne, pour les filtres courts

5. Champs de l'exemple

Champ	Composant	Réglages clés
Full name	Field	Required ; Length 2–60
Work email	Field	Required ; Pattern e-mail
Department	Select	quatre options statiques
Employment type	RadioBox	trois options
Start date	DatePicker	YYYY-MM-DD
Laptop budget	Number Field	plage 500–5000, suffixe USD
Administrator access	Switch	Default Checked désactivé
Request justification	TextArea	ligne entière, hauteur 4–8, Length 20–500

Le Name / Field Key devient la propriété JSON envoyée au backend. Chaque champ éditable doit avoir une clé unique.

6. Validation

Utilisez Required pour l'absence de valeur, Length pour les limites de texte, Pattern pour le format, Number pour une plage numérique et Custom Validator pour une règle métier. En cas d'erreur, Spark indique le champ concerné et arrête l'envoi.

La validation du navigateur améliore l'expérience ; le backend doit conserver des contrôles équivalents.

7. Reset, Validate et Submit

Pour Reset, ajoutez Call Component Function à onClick :

Component: employee_onboarding_form
Function: reset

Reset restaure les valeurs initiales et efface les messages de validation. Pour Validate, ajoutez Validate Form et sélectionnez ce même Form.

Pour Submit :

Form: employee_onboarding_form
Submission Mode: Custom URL
URL: /spark/api/sample/form/requests
Method: POST

Spark valide le Form, collecte uniquement ses champs enregistrés, envoie le JSON, puis affiche le displayText du backend ou exécute les actions de succès. Le Page Context et les autres Forms ne sont pas ajoutés au payload.

8. Backend Java et contexte de page

@PostMapping
public ApiResult<FormRequestReceiptDTO> submit(
        @RequestBody FormRequestSubmission request,
        @RequestHeader(value = SparkPageRequestHeaders.ENVIRONMENT,
                required = false) String environment,
        @RequestHeader(value = SparkPageRequestHeaders.RENDER_MODE,
                required = false) String renderMode) {
    SparkPageRequestContext context =
            SparkPageRequestHeaders.resolve(environment, renderMode);
    return SparkApiResultHelper.success(
            Locale.FRENCH,
            requestService.submit(request, context),
            "SPARK-SAMPLE-FORM-0001");
}

En DESIGN_PREVIEW, le service peut renvoyer un reçu stable sans persistance ; en RUNTIME, il exécute le vrai cas d'usage. Spark ajoute automatiquement X-Spark-Page-Environment et X-Spark-Page-Render-Mode. Ne les répétez pas dans chaque Interaction. Consultez Contexte des requêtes de page.

9. Exemple avancé : édition du profil

Ce second exemple charge une fiche, valide l’adresse e-mail à distance, affiche conditionnellement le motif d’accès administrateur, gère une liste de contacts, enregistre un brouillon et n’envoie que les changements.

La définition reproductible se trouve dans form-capabilities-page.json; le backend est fourni par FormCapabilityController et FormCapabilitySampleService.

10. Modes et état public

Dans Form capabilities, choisissez Create, Edit ou View. Edit charge Load URL et enregistre avec Update URL ; View conserve la mise en page en lecture seule. Activez l’avertissement de modifications non enregistrées.

forms.employee_profile_form.valid
forms.employee_profile_form.dirty
forms.employee_profile_form.submitting
forms.employee_profile_form.submitError
forms.employee_profile_form.lastSubmit
forms.employee_profile_form.mode

Dans le Form courant, les raccourcis form.dirty et form.submitting sont disponibles. Ces valeurs sont en lecture seule.

11. Champs conditionnels

Visible When: state.adminAccess === true
Required When: state.adminAccess === true
Dependencies: adminAccess
Clear When Hidden: on

Visible, Disabled et Required acceptent des expressions sur state.*, context.*, record.* et form.*. Dependencies contient les Field Keys stables séparées par des virgules. Clear When Hidden évite d’envoyer une ancienne valeur devenue invisible.

12. Validation distante et erreurs serveur

Ajoutez Remote validation à Work email :

Validation URL: /spark/api/sample/form/validate-email
Method: POST
Debounce: 400
Valid Response Path: data.valid
Message Response Path: data.message
Trigger: blur

Une nouvelle saisie annule la requête précédente. Pour la validation lors de l’enregistrement, retournez des erreurs indexées par Field Key :

{
  "success": false,
  "displayText": "Vérifiez les champs signalés.",
  "fieldErrors": {
    "workEmail": ["Cette adresse est déjà utilisée."],
    "adminAccessReason": ["Expliquez pourquoi cet accès est nécessaire."]
  }
}

SparkFieldValidationException conserve les messages Lattice jusqu’à la localisation au niveau Web.

13. Groupes répétables

Activez Repeatable Group sur une section :

Collection Key: emergencyContacts
Minimum Items: 1
Maximum Items: 3
Add Button Text: Add contact

Les champs de la section deviennent le modèle d’une ligne. Runtime ajoute les actions Add/Delete et envoie un tableau sous Collection Key. View masque ces actions.

14. Adaptateur de données et changements

Load URL: /spark/api/sample/form/records/employee-1001
Create URL: /spark/api/sample/form/records
Update URL: /spark/api/sample/form/records/[[state.id]]
Response Data Path: data
Submission Payload: Changed values only
Record ID Field: id
Revision Field: revision

En Edit, Spark établit une base après chargement et envoie recordId, revision et une liste changes de type add/replace/remove. Create envoie toujours toutes les valeurs. Le backend doit répondre 409 si la révision est périmée.

15. Brouillons

Utilisez Browser storage pour un brouillon personnel, ou Remote service pour un usage inter-appareils. Configurez Draft Key, Autosave Delay, Load URL et Save URL. Les fonctions saveDraft, restoreDraft et discardDraft peuvent être liées à des boutons. Un brouillon distant doit retourner une nouvelle revision ; une ancienne revision reçoit HTTP 409.

16. Générer depuis un modèle ou un schéma

Dans Form capabilities → Generate fields, choisissez Business Object, JSON Schema ou OpenAPI, puis Append ou Replace. Un tableau d’objets devient un Repeatable Group. Le résultat est une métadonnée de page ordinaire et modifiable ; Runtime n’exécute jamais du JSON de composant ou un script arbitraire renvoyé par le backend.

Vérifiez ensuite les libellés, données sensibles, options, permissions, URL et validations serveur.

17. Dépannage

• Libellés non alignés : avec deux contrôles par ligne, utilisez un total de 12, par exemple 4 + 8.
• Champ conditionnel figé : ajoutez le Field Key contrôleur dans Dependencies ; n’utilisez pas le libellé d’affichage.
• Erreurs seulement en haut : retournez fieldErrors au niveau racine avec les Field Keys exactes.
• Conflits de brouillon répétés : renvoyez et réutilisez la nouvelle revision après chaque sauvegarde.
• Aucune création réelle en conception : branchez le backend sur DESIGN_PREVIEW et utilisez un reçu de prévisualisation ou un sandbox.