Collapse

Collapse organise des contenus liés en sections développables. Les panneaux peuvent être maintenus manuellement ou générés en répétant un modèle sur les enregistrements d'un modèle métier ou d'une API.

1. Choisir le mode de contenu

Mode	Quand l'utiliser	Source
Static	Le nombre et la structure des panneaux sont fixes	Enfants CollapsePanel
Data Source	Les panneaux représentent des enregistrements de même nature	Une Data Source et un Item Template

Pour une ancienne page JSON sans Content Mode, le panneau de propriétés affiche automatiquement Static et le Runtime conserve ce mode ; aucune migration n’est nécessaire.

Ce guide s’appuie sur trois exemples complémentaires. Les captures et les étapes ci-dessous suffisent pour les reproduire ; aucun accès à l’application Spark Sample n’est nécessaire :

• Onboarding Checklist utilise explicitement Content Mode = Static. Ses quatre panneaux contiennent des formulaires en lecture seule différents et illustrent la structure statique, l’ouverture initiale et les fonctions du composant.
• Frequently Asked Questions utilise Content Mode = Data Source, lit /spark/api/sample/collapse/faqs et répète un FAQ Item Template. Cet exemple couvre Test, les correspondances de champs, la pagination, Current Record et les données d’aperçu de développement.
• Support Answers with Custom Content réutilise la même source, mais répète un Form personnalisé en lecture seule dans chaque panneau dynamique. Il illustre le canevas du corps du modèle et les liaisons record.*.

2. Mode statique

1. Faites glisser Collapse depuis Containers.
2. Conservez Content Mode = Static.
3. Ajoutez et réorganisez les éléments de Collapse Panels.
4. Configurez Title, Description, Icon, l'ouverture initiale, Disabled et Trigger Area.
5. Placez un Form, un Panel ou un autre contenu dans chaque panneau.

Le composant externe contrôle Single Panel Mode, Show Border, Transparent Style, Size et Arrow Position. Header est la zone de déclenchement recommandée : toute la ligne d’en-tête, y compris l’espace vide, ouvre ou ferme le panneau. Choisissez Icon si seule la flèche doit déclencher l’action. Un panneau Disabled reste modifiable en Design Mode.

3. Mode alimenté par des données

3.1 Source de données

1. Sélectionnez Content Mode = Data Source.
2. Choisissez une Row Unique Key, par exemple id ou code. Elle doit être présente et unique dans chaque enregistrement.
3. Définissez Items Per Request et Empty State Text.
4. Configurez un modèle ou une Custom URL avec Method, Rows Path, Total Path et Record Fields.
5. Cliquez sur Test. Le test utilise la même construction de requête et la même lecture de réponse que l'aperçu et l'exécution. Il signale aussi les clés absentes ou dupliquées.

Réponse recommandée :

{
  "success": true,
  "data": {
    "total": 6,
    "current": 1,
    "pageSize": 4,
    "records": [{
      "id": "invite-team",
      "category": "Getting started",
      "question": "When should I invite the wider team?",
      "answer": "Invite the team after access rules are ready.",
      "disabled": false,
      "defaultExpanded": true
    }]
  }
}

Utilisez data.records comme Rows Path et data.total comme Total Path.

3.2 Item Template

Le fonctionnement est identique à CardSet : cliquez sur le bouton d'édition de Item Template, choisissez un modèle dans la galerie, puis configurez ses paramètres dans la même fenêtre.

Utilisez Content pour associer le titre, la description, le contenu, la catégorie ou le badge. Utilisez Behavior pour les champs facultatifs Icon, Visible, Disabled et Default Expanded. Les trois modèles partagent le même contrat de comportement.

Modèle	Usage	Correspondances principales
FAQ	Centre d'aide	Title, Answer, Category, Answer Format
Record Summary	Enregistrements métier	Title, Description, Content, Badge
Custom Content	Mise en page spécifique	En-tête, comportement et référence vers un Content de page

Live Preview permet de changer de Preview Record ou de recharger une vraie donnée. Save valide le brouillon ; Cancel, la fermeture et Escape ne modifient pas le modèle actuel.

3.3 Composer avec Content

Content est une ressource locale à la page et réutilisable, pas un Form ni un canevas caché dans Collapse. Page Resources regroupe Popups et Contents. L’ouverture d’un Content fait glisser depuis la droite un grand tiroir de conception, tout en conservant la palette et le panneau de propriétés. Fermez-le depuis l’en-tête, cliquez à l’extérieur, utilisez Back to page ou appuyez sur Échap.

Pour Custom Content, sélectionnez un Content existant, utilisez Create Content, puis Edit Content pour l’ouvrir. Unlink Content retire seulement la référence du Collapse. Un même Content peut être réutilisé ; une modification s’applique partout. Un Content encore référencé ne peut pas être supprimé. Ses contrôles lisent directement record.*, sans mapping de paramètres. Les anciennes structures Item Template panels sont automatiquement promues en Content au premier chargement ou enregistrement.

3.4 Aperçu de conception et Runtime

• Design Preview et Runtime utilisent le même moteur de rendu.
• L'aperçu charge une page ; en l'absence de données, des Sample Records clairement identifiés sont affichés.
• Le chargement initial utilise des squelettes ; les états vide et erreur sont explicites ; Retry relance la requête.
• Runtime affiche Load more s'il reste des données et n'exécute qu'une requête de chargement à la fois.
• Un rechargement conserve les clés développées encore présentes.
• Runtime ignore les clés invalides ; Test les signale comme erreurs de configuration.

4. Interactions

Le mode Static propose Collapse onChange et CollapsePanel onClick. Le mode Data Source propose Collapse onChange et Item Template onClick.

Pour un élément dynamique, Spark écrit d'abord Current Record, exécute Item Template onClick, puis Collapse onChange. Les actions peuvent lire record.* et :

collapse.activeKeys
collapse.expandedCount
collapse.changedKey
collapse.changedIndex
collapse.changedNumber
collapse.changedRecord
collapse.expanded
collapse.accordion
collapse.contentMode

Exemple de Toast : FAQ: [[record.question]].

5. Fonctions

Fonction	Comportement
expandAll	Développe les éléments actifs ; Single Panel Mode garde le premier
collapseAll	Réduit tous les éléments
resetPanels	Restaure l'ouverture par défaut
reloadCollapse	Recharge les données et réconcilie les clés développées
setCollapseData(data)	Remplace les données par un tableau fourni par une action

6. Contexte de requête et Java

Test, Design Preview et Runtime envoient automatiquement :

X-Spark-Page-Environment: DEV | TEST | PROD
X-Spark-Page-Render-Mode: DESIGN_PREVIEW | RUNTIME

Ne les ajoutez pas manuellement. Voir Contexte des requêtes de page. L'exemple utilise /spark/api/sample/collapse/faqs et résout les en-têtes avec SparkPageRequestHeaders.resolve(environment, renderMode). Le service peut renvoyer des données déterministes lorsque le mode vaut DESIGN_PREVIEW.

7. Reproduire les exemples

7.1 Liste de contrôle statique

1. Ajoutez Collapse, conservez Static et désactivez Single Panel Mode.
2. Ajoutez quatre CollapsePanels, chacun contenant un Form en lecture seule différent.
3. Activez Expanded by Default sur le premier élément.
4. Ajoutez trois boutons appelant expandAll, collapseAll et resetPanels.

7.2 FAQ dynamique

1. Sélectionnez Data Source, Single Panel Mode et Transparent Style.
2. Définissez la clé sur id et Items Per Request sur 4.
3. Utilisez /spark/api/sample/collapse/faqs, POST, data.records et data.total.
4. Cliquez sur Test, puis choisissez le modèle FAQ.
5. Associez question, answer, category, disabled et defaultExpanded.
6. Ajoutez FAQ: [[record.question]] à onChange.

7.3 Détails avec Custom Content

1. Ajoutez un autre Collapse alimenté par les données et réutilisez /spark/api/sample/collapse/faqs avec les mêmes chemins de réponse.
2. Choisissez Custom Content, puis associez Title à question et Description à summary.
3. Cliquez sur Create Content, nommez la ressource Support answer content, puis modifiez-la dans le grand tiroir de conception.
4. Ajoutez dans Content un Form en lecture seule avec Controls Per Row 2, Label 4 et Content 8.
5. Ajoutez des champs liés à [[record.category]], [[record.environment]] et [[record.renderMode]].
6. Ajoutez un TextArea en lecture seule sur toute la ligne, lié à [[record.answer]].
7. Vérifiez que l’en-tête et le Form changent quand Preview Record change.

8. Dépannage

Test signale une Row Unique Key dupliquée

Utilisez un identifiant métier stable, jamais l’index de ligne. La clé doit rester identique après pagination, tri et rechargement.

Design Preview affiche Sample Record

La source est absente, inaccessible ou en erreur. Utilisez Test pour corriger l’URL, les chemins de réponse ou la requête backend.

L’aperçu ne change pas après la modification du modèle

Enregistrez la fenêtre du modèle et vérifiez les correspondances dans Record Fields ou dans la réponse réelle.

Lire l’enregistrement courant dans Content

Utilisez record.* dans les valeurs ou les expressions Interaction. Ne figez pas une valeur copiée depuis Preview Record.

Les panneaux ouverts disparaissent après Load more

Vérifiez qu’un même enregistrement métier conserve la même Row Unique Key. Spark ne peut préserver que les clés stables.

9. Recommandations de conception

• Conservez environ 3 à 8 panneaux visibles par groupe ; au-delà, ajoutez des catégories ou une recherche.
• Privilégiez Single Panel Mode pour les FAQ et les longues explications ; autorisez plusieurs panneaux pour les comparaisons.
• Le Title doit expliquer seul le contenu développé ; Description ne doit pas le répéter.
• Accompagnez Disabled d’une explication lisible au lieu de dépendre uniquement du gris.
• Le backend doit fournir une clé unique stable et une structure de pagination constante.
• Déclarez les correspondances dynamiques dans Record Fields pour faciliter la sélection, le test et la maintenance.
• Évitez plusieurs niveaux de Collapse ; utilisez plutôt des titres, Tab ou une page distincte.