Step

Step décompose une tâche longue, dont l'ordre est clairement défini, en plusieurs étapes. Chaque étape possède un titre, un état et une zone de contenu pouvant accueillir des Forms, des champs, des instructions et des boutons d'action.

Après avoir lu ce guide, vous saurez :

• ajouter un conteneur Step et plusieurs StepItems ;
• configurer une présentation horizontale, verticale, de navigation ou compacte ;
• utiliser la numérotation et les icônes d'état automatiques, ou une série cohérente d'icônes métier ;
• combiner des formulaires et des boutons dans chaque étape ;
• avancer, revenir, accéder à une étape et réinitialiser le parcours avec les fonctions du composant ;
• valider un formulaire avant le changement et lire l'étape courante dans onChange.

Step, Tab et Progress répondent à des besoins différents. Step représente des tâches à effectuer dans un ordre imposé ou recommandé. Tab organise des contenus parallèles concernant un même objet. Progress indique uniquement un taux d'avancement et ne contient pas le contenu de chaque étape.

1. Exemple : assistant de lancement de campagne

La page Step de Spark Sample présente un assistant de lancement en quatre étapes :

Étape	Contenu	Point illustré
Campaign details	Nom, responsable, date de lancement et résumé	Form à deux colonnes, validation obligatoire, TextArea sur toute la ligne
Audience & budget	Audience, canaux, budget et objectif de conversion	Retour, suite et champs numériques
Review	Récapitulatif en lecture seule des deux premières étapes	État de page partagé entre les étapes et retour de soumission
Submitted	Numéro de campagne et message de fin	État terminé et réinitialisation de l'assistant

Cet exemple ne dépend d'aucun endpoint backend. Les boutons changent d'étape au moyen de l'API du composant Step, ce qui permet de comprendre directement la structure et les Interactions. Pour envoyer réellement les données, ajoutez Send Request à l'interaction du bouton de l'étape Review.

2. Ajouter un conteneur Step

1. Ouvrez la page cible dans Page Designer.
2. Développez Containers dans la palette de composants.
3. Faites glisser Step dans Screen ou dans une zone acceptant les conteneurs.
4. Sélectionnez Step, puis ajoutez des StepItems dans Steps.
5. Sélectionnez chaque StepItem et renseignez son Title.
6. Ajoutez un Form, un Panel ou des champs dans sa zone de contenu.

Step et StepItem forment une structure à deux niveaux :

Step
├── Campaign details
│   └── Form + Next button
├── Audience & budget
│   └── Form + Back / Next buttons
├── Review
│   └── Read-only Form + Back / Submit buttons
└── Submitted
    └── Result Form + Reset button

La liste des enfants accepte le glisser-déposer. La réorganisation des StepItems met également à jour leur numéro et l'ordre de navigation avant/arrière.

3. Configurer le conteneur Step

Sélectionnez le Step externe pour régler les propriétés suivantes :

Propriété	Valeurs	Description
Initial Step	Entier à partir de 1	Étape affichée à l'ouverture ; une valeur hors limites est ramenée à la première ou à la dernière étape
Direction	horizontal, vertical	Dispose les en-têtes horizontalement ou verticalement
Step Style	default, navigation, inline	Flux standard, navigation ou style compact en ligne
Marker Size	small, medium, large	Taille commune des numéros ou icônes ; Medium par défaut
Label Placement	horizontal, vertical	Place le titre à droite ou sous l'icône
Progress Dots	Activé / Désactivé	Remplace les numéros ou icônes par des points ; les titres passent en disposition verticale
Allow Step Click	Activé / Désactivé	Autorise l'utilisateur final à changer d'étape en cliquant sur son en-tête
Show Step Content	Activé / Désactivé	Affiche la zone de contenu du StepItem courant
Responsive	Activé / Désactivé	Adopte une disposition verticale lisible sur écran étroit
Current Step Status	process, wait, finish, error	État par défaut de l'étape courante
Current Step Progress	0 à 100	Progression facultative dans l'étape courante, surtout pour Default + Process

3.1 Styles de Step

• Default : adapté aux assistants de formulaire classiques ; le lien entre état et ordre y est le plus clair.
• Navigation : l'en-tête ressemble à une navigation de processus ; utile lorsque l'utilisateur peut revenir aux étapes terminées.
• Inline : présentation compacte pour les espaces réduits et les titres courts. Avec une Direction verticale, le style revient automatiquement à Default afin de préserver la lisibilité.

Si le parcours doit être suivi dans l'ordre, désactivez Allow Step Click et conservez uniquement les boutons Back, Next et Submit dans le contenu.

4. Configurer un StepItem

Sélectionnez un StepItem pour régler :

Propriété	Description
Title	Titre principal obligatoire ; 2 à 5 mots sont recommandés
Subtitle	Information complémentaire, par exemple la phase, la durée estimée ou le responsable
Description	Brève explication du contenu de l'étape
Status	auto, wait, process, finish, error
Disabled	Interdit le clic et la navigation vers cette étape par une fonction du composant
Icon	Facultatif. Choisissez une icône système et ses couleurs de premier plan/arrière-plan, ou importez une image personnalisée avec le sélecteur d'icônes commun

Avec Status défini sur auto, le système déduit l'état de la position courante : les étapes précédentes sont Finish, les suivantes Wait, et l'élément courant utilise Current Step Status du Step. Ne remplacez l'état d'un StepItem que si une erreur, une attente ou un état terminé particulier doit rester visible.

4.1 Numéros, états et icônes métier

Sans Icon, Step affiche 1, 2, 3…, la présentation recommandée pour les assistants et les processus d'approbation. Une étape terminée remplace automatiquement son numéro par une coche. Les états courant, en attente et en erreur reçoivent aussi automatiquement leurs couleurs et repères ; aucun fond rouge, jaune ou vert n'est à configurer étape par étape.

Ajoutez des icônes uniquement lorsqu'elles permettent d'identifier clairement les phases métier, par exemple User, Document, Payment, Review, Send ou Milestone. Configurez-les de manière homogène pour l'ensemble du groupe ; ne mélangez pas étapes numérotées et étapes avec icône. Le sélecteur propose la recherche, un aperçu, les couleurs de premier plan et d'arrière-plan, ainsi qu'une option sans fond. Le panneau de propriétés affiche le nom et l'identifiant de l'icône sélectionnée.

Marker Size est réglé sur le Step externe afin de conserver une taille uniforme. N'importez pas des images de tailles différentes pour accentuer artificiellement une étape.

Modifier différentes étapes dans le Designer

Dans Design Mode, cliquez sur un numéro ou un titre de la barre d'étapes pour changer l'étape en cours d'édition. La zone située dessous affiche les Form, Panel, champs et boutons du StepItem concerné ; le panneau de propriétés se synchronise avec lui.

Allow Step Click et Disabled définissent le comportement de la page enregistrée à l'exécution. Ils n'empêchent pas l'auteur d'ouvrir l'étape dans le Designer. Vous pouvez aussi développer Steps → StepItem → Form dans la structure de page et sélectionner directement le Form ou un champ d'une étape ultérieure.

Utilisez Disabled lorsque les conditions d'une étape ne sont pas encore remplies. Next et Previous ignorent automatiquement les étapes désactivées. Si une étape ne s'applique pas du tout à l'utilisateur courant, masquez-la avec la condition d'affichage commune au lieu de seulement la désactiver.

5. Organiser les formulaires dans les étapes

Ajoutez d'abord un Form au StepItem, puis placez-y les champs et le ButtonSet :

1. Form contrôle de façon centralisée Controls Per Row, Layout, Label Alignment et le rapport label/contenu.
2. Form prend en charge la validation des champs ; Step gère uniquement la navigation dans le processus.
3. Chaque étape intermédiaire possède un bouton Next explicite ; à partir de la deuxième, ajoutez aussi Back.
4. Utilisez la dernière étape métier pour Review et Submit, puis affichez une étape de résultat distincte après l'envoi.

Le Form de l'exemple utilise Controls Per Row = 2 et Label 4 / Content 8. Campaign summary active Display Full Row : son Label occupe toujours 4 colonnes et reste aligné avec Launch date, tandis que Content utilise automatiquement l'espace restant de la ligne.

Quand plusieurs étapes lisent la même valeur, utilisez le même Name de champ. Par exemple, le champ modifiable et le champ en lecture seule de Review portent tous deux le nom campaignName, afin que Review affiche la dernière valeur saisie à la première étape.

6. Configurer la suite, le retour et la réinitialisation

Step expose quatre fonctions de composant :

Fonction	Paramètre	Comportement
nextStep	Aucun	Passe à l'étape disponible suivante en ignorant les éléments Disabled
previousStep	Aucun	Revient à l'étape disponible précédente en ignorant les éléments Disabled
goToStep	stepNumber	Accède à une étape précise ; la numérotation commence à 1
resetSteps	Aucun	Revient à Initial Step

Pour le bouton Next de la première étape :

1. Sélectionnez le bouton et ouvrez Interaction.
2. Sous onClick, ajoutez d'abord Trigger Form Validation et sélectionnez campaign_details_form comme Form.
3. Ajoutez une action Component API.
4. Sélectionnez campaign_steps comme Target Component.
5. Sélectionnez nextStep comme Function.

Les actions s'exécutent de haut en bas. Si la validation échoue, nextStep ne s'exécute pas. L'assistant avance uniquement après une validation réussie.

Le bouton Back appelle seulement previousStep. Sur la page de fin, le bouton « Create another campaign » appelle resetSteps.

7. Configurer les interactions de changement d'étape

Step accepte deux niveaux d'interaction :

1. onChange sur le Step externe.
2. onClick sur un StepItem.

Avant le changement, l'étape cible est enregistrée dans le contexte step :

step.id
step.index
step.number
step.previousIndex
step.previousNumber
step.name
step.description
step.status

index commence à 0 pour faciliter les calculs d'expression. number commence à 1, comme dans le panneau de propriétés et dans le numéro visible par l'utilisateur.

Lors d'un clic sur un en-tête, le onClick du StepItem s'exécute d'abord. Après le changement effectif, le onChange du Step externe s'exécute. Les navigations Next, Previous, Go to et Reset exécutent le onChange externe sans être interprétées comme un clic utilisateur sur un StepItem. Une étape Disabled ne change pas et n'exécute aucune interaction.

Par exemple, ajoutez un Toast au onChange de Step :

Now viewing step [[step.number]]: [[step.name]]

8. Scénario 1 : rester sur l’étape courante après un échec de validation backend

Step Validation Gate comporte deux étapes. Le code initial TRY-AGAIN est refusé et l’étape 1 reste active. Après remplacement par APPROVE-2026, la réponse réussit et l’étape 2 s’ouvre.

1. Créez Submit request et Accepted, conservez Initial Step à 1 et désactivez Allow Step Click.
2. Dans un Form validation_gate_form, ajoutez requestTitle et approvalCode.
3. Sur Submit and continue, placez d’abord Submit Form avec l’URL personnalisée /spark/api/sample/step/validation-gate.
4. Ajoutez ensuite la fonction validation_gate_steps.nextStep.

Une erreur HTTP ou success: false interrompt la chaîne : nextStep n’est donc pas exécuté. Ne placez jamais le changement d’étape avant la soumission.

if (!StringUtils.equals("APPROVE-2026", StringUtils.trim(request.getApprovalCode()))) {
    throw new LatticeRuntimeException(Message.code("SPARK-SAMPLE-STEP-0003"));
}

La référence complète se trouve dans StepWorkflowSampleController, StepWorkflowSampleService et step-validation-gate-page.json.

9. Scénario 2 : ouvrir l’étape du responsable courant selon l’état backend

Step Handoff représente deux intervenants successifs. Avery Chen a terminé l’étape 1 et Morgan Lee traite l’étape 2. Au chargement, Page onLoad lit l’état du workflow et ouvre l’étape 2. Allow Step Click permet toujours de consulter l’étape 1 en lecture seule.

1. Créez Requester submission et Manager review. Gardez Initial Step à 1, activez Allow Step Click et rendez le premier Form terminé non modifiable.
2. Dans Page onLoad, envoyez GET /spark/api/sample/step/handoff/status avec caseId=CAM-2048.
3. Liez activeStep à workflow.activeStep.
4. Ajoutez ensuite handoff_steps.goToStep et liez stepNumber à workflow.activeStep.

Page onLoad
├── Send Request: GET /spark/api/sample/step/handoff/status
│   └── activeStep → workflow.activeStep
└── handoff_steps.goToStep([[workflow.activeStep]])

Le chargement reste visible jusqu’à la fin de onLoad, ce qui évite un saut visuel. Si la requête échoue, Initial Step reste actif. Le backend doit calculer l’état et les droits de l’utilisateur connecté : activeStep règle l’affichage, pas l’autorisation.

10. Envoyer les données au backend

L'exemple n'a aucune dépendance backend afin de rester simple à découvrir. Dans une application réelle, configurez le bouton Submit de Review dans cet ordre :

1. Trigger Form Validation.
2. Send Request ou Submit Form.
3. Toast de réussite.
4. Appel de nextStep pour afficher la page de fin.

Les requêtes de page transportent automatiquement l'environnement courant et le mode de rendu. N'ajoutez pas manuellement les en-têtes de protocole dans Step. Consultez Contexte des requêtes de page et débogage backend pour le protocole complet.

Si Send Request échoue, arrêtez les actions suivantes et conservez l'étape courante afin que l'utilisateur puisse corriger les données et réessayer. N'affichez pas la page de fin avant d'avoir reçu le résultat de la soumission.

11. Reproduire le Spark Sample

1. Ajoutez Step et choisissez Horizontal, Default, Vertical Label, Responsive et Allow Step Click.
2. Définissez Marker Size sur Medium et conservez les numéros par défaut.
3. Ajoutez les quatre StepItems Campaign details, Audience & budget, Review et Submitted, sans Icon.
4. Ajoutez un Form horizontal à deux colonnes dans les trois premières étapes, puis un Form en lecture seule à une colonne dans la dernière.
5. Les boutons Next des deux premières étapes valident le Form courant avant d'appeler nextStep.
6. Les boutons Back des étapes deux et trois appellent previousStep.
7. Le bouton Submit de Review affiche un Toast de réussite, puis appelle nextStep.
8. Le bouton de réinitialisation de Submitted appelle resetSteps.
9. Enregistrez la page et parcourez le flux complet une fois dans Preview et une fois à l'exécution.

Les scénarios avancés complets sont disponibles dans step-validation-gate-page.json et step-handoff-page.json.

12. Résolution des problèmes

12.1 Next ne change pas d'étape

Vérifiez que :

• Target Component désigne le Step externe ;
• Function vaut nextStep ;
• les étapes restantes ne sont pas toutes Disabled ou masquées ;
• une action Trigger Form Validation précédente ne bloque pas sur un champ obligatoire vide ;
• la page est enregistrée et l'exécution utilise le versionId courant.

12.2 Cliquer sur un en-tête ne produit aucun effet

Vérifiez que Allow Step Click est activé et que le StepItem cible n'est pas Disabled. La désactivation du clic direct est normale dans un parcours contrôlé ; utilisez alors les boutons du contenu.

12.3 Review n'affiche pas les valeurs saisies

Les champs modifiables et les champs en lecture seule de Review doivent utiliser le même Name stable. Display Name modifie uniquement le titre visible et ne permet pas de partager l'état de page.

12.4 L'état d'une étape ne correspond pas aux attentes

Conservez normalement le Status du StepItem sur auto. Une valeur Finish ou Error configurée manuellement remplace la déduction automatique. Revenez à Auto pour que l'état suive de nouveau l'étape courante.

12.5 La page n’ouvre pas l’étape renvoyée par le backend

Vérifiez Page onLoad, la liaison vers workflow.activeStep, le paramètre goToStep.stepNumber et la valeur entière commençant à 1. Une requête en échec interrompt volontairement le saut.

12.6 Les étapes sont trop serrées sur mobile

Activez Responsive et évitez les Title, Subtitle et Description trop longs. Si la lecture reste difficile, utilisez une Direction verticale ou réduisez le texte affiché.

13. Recommandations de conception

• Limitez généralement un assistant à 3–7 étapes. Au-delà de 7, envisagez plusieurs pages ou groupes.
• Utilisez un résultat ou une phase métier comme titre, par exemple Details, Audience ou Review, et évitez les phrases longues.
• Indiquez la destination dans les boutons Next, par exemple « Next: Review », plutôt qu'un vague « Continue ».
• Désactivez Allow Step Click lorsque le saut d'étape est interdit et n'avancez qu'après validation réussie.
• Prévoyez Review avant la soumission et une page de fin distincte après celle-ci ; ne vous limitez pas à un Toast temporaire.
• Fournissez une explication lisible pour les états Error, Disabled et terminé au lieu de dépendre uniquement de la couleur.