Collapse

Collapse organizes related content into expandable sections. It can contain manually maintained panels or repeat one item template over records returned by a model or backend endpoint.

1. Choose a content mode

Mode	Use it when	Content source
Static	The number and structure of panels are fixed	Add and arrange CollapsePanel children
Data Source	Panels represent records of the same kind	Configure one Data Source and one Item Template

For existing page JSON without Content Mode, the property panel displays Static automatically and Runtime continues to use Static; no migration is required.

This guide uses three complementary examples. The screenshots and steps below contain everything needed to reproduce them; access to the Spark Sample application is not required:

• Onboarding Checklist explicitly uses Content Mode = Static. Its four panels contain different read-only forms and demonstrate static structure, default expansion, and component functions.
• Frequently Asked Questions uses Content Mode = Data Source, reads /spark/api/sample/collapse/faqs, and repeats an FAQ Item Template. It demonstrates Test, field mappings, paging, Current Record, and development-preview data.
• Support Answers with Custom Content reuses the same source but repeats a custom read-only Form inside each dynamic panel. It demonstrates the template body canvas and record.* bindings.

2. Static mode

1. Drag Collapse from Containers onto the page.
2. Keep Content Mode = Static.
3. Add and reorder items in Collapse Panels.
4. Configure each panel's Title, Description, Icon, default expansion, disabled state, and trigger area.
5. Place a Form, Panel, or other content inside each panel.

The outer component controls Single Panel Mode, Show Border, Transparent Style, Size, and Arrow Position. Header is the recommended Trigger Area: the entire header row, including its empty space, expands or collapses the panel. Choose Icon when only the arrow should trigger it. A Disabled panel remains selectable in Design Mode.

3. Data-driven mode

3.1 Configure the data source

1. Set Content Mode = Data Source.
2. Choose a Row Unique Key, such as id or code. It must exist and be unique in every record.
3. Set Items Per Request and Empty State Text.
4. Configure a model source or Custom URL.
5. For a Custom URL, provide URL, Method, Rows Path, Total Path, and Record Fields.
6. Click Test. Test uses the same request and response parsing as Design Preview and Runtime, and reports missing or duplicate row keys.

Recommended response:

{
  "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
    }]
  }
}

Use data.records for Rows Path and data.total for Total Path.

3.2 Choose an Item Template

Item Template follows the same workflow as CardSet. Click its edit button to open a template gallery, choose a template, then configure its field parameters in the same dialog.

Use Content for title, description, body, category, or badge mappings. Use Behavior for optional Icon, Visible, Disabled, and Default Expanded mappings. All three templates share the same behavior contract.

Template	Best for	Main mappings
FAQ	Help centers	Title, Answer, Category, Answer Format
Record Summary	Business records	Title, Description, Content, Badge
Custom Content	A layout not covered by presets	Header and behavior mappings plus a page Content reference

Live Preview can switch Preview Record or reload real preview data. Save commits the draft; Cancel, close, and Escape leave the current template unchanged.

3.3 Build custom layouts with Content

Content is a reusable, page-local content resource, not a Form or a hidden Collapse sub-canvas. Page Resources groups Popups and Contents. Opening a Content slides a wide design drawer in from the right while keeping the component palette and property panel available. Close it from the title bar, click outside, choose Back to page, or press Escape.

For Custom Content, select an existing Content, choose Create Content, or open the linked resource with Edit Content. Unlink Content removes only this Collapse reference. One Content can serve multiple consumers, so one edit updates every reference. A Content that is still referenced cannot be deleted.

Child controls repeat for every record and can directly read record.id, record.question, and other record.* paths; no parameter mapping is needed in the first version. The third sample uses Support answer content and binds a two-column read-only Form to [[record.category]], [[record.environment]], [[record.renderMode]], and [[record.answer]]. An exact binding preserves its original type; a binding embedded in text is interpolated as text.

Pages saved with the former inline Item Template panels structure are automatically promoted to Content when first loaded or saved.

3.4 Design Preview and Runtime

• Design Preview and Runtime use the same renderer.
• Preview requests one page. If no live data is available, clearly marked Sample Records are shown.
• Initial loading uses skeletons; empty and error states are explicit; errors offer Retry.
• Runtime exposes Load more when more records exist and runs only one load request at a time.
• Reload keeps expanded keys that still exist.
• Runtime skips invalid row keys; Test reports them as configuration errors.

4. Interactions

Static mode supports Collapse onChange and CollapsePanel onClick. Data Source mode supports Collapse onChange and Item Template onClick.

For a dynamic item, Spark first writes Current Record, then runs Item Template onClick, and finally Collapse onChange. Actions can read record.* and:

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

Example Toast: FAQ: [[record.question]].

5. Component functions

Function	Behavior
expandAll	Expands all enabled items; Single Panel Mode keeps the first
collapseAll	Collapses all items
resetPanels	Restores static or record-mapped default expansion
reloadCollapse	Reloads dynamic records and reconciles expanded keys
setCollapseData(data)	Replaces dynamic records with an array supplied by an earlier action

6. Request context and Java sample

Test, Design Preview, and Runtime automatically send:

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

Do not add these headers manually. See Page request context and backend debugging.

The Spark Sample endpoint is /spark/api/sample/collapse/faqs:

@PostMapping
public ApiResult<ProTablePageResult<CollapseFaqDTO>> queryByPost(
        @RequestBody(required = false) CollapseFaqQueryRequest 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, faqService.query(request, context),
            "SPARK-SAMPLE-COLLAPSE-0001");
}

A backend can return deterministic preview data when context.getRenderMode() == DESIGN_PREVIEW, while Runtime queries real business data.

7. Reproduce the samples

7.1 Static onboarding checklist

1. Add Collapse, keep Static, and turn off Single Panel Mode.
2. Add four CollapsePanels and place a different read-only Form in each one.
3. Enable Expanded by Default for the first item.
4. Add three buttons that call expandAll, collapseAll, and resetPanels.

7.2 Dynamic FAQ

1. Select Data Source, Single Panel Mode, and Transparent Style.
2. Set Row Unique Key to id and Items Per Request to 4.
3. Use /spark/api/sample/collapse/faqs, POST, data.records, and data.total.
4. Click Test.
5. Choose the FAQ Item Template.
6. Map question, answer, category, disabled, and defaultExpanded.
7. Add FAQ: [[record.question]] to Collapse onChange.

7.3 Custom Content record details

1. Add another data-driven Collapse and reuse /spark/api/sample/collapse/faqs with the same response paths.
2. Choose Custom Content. Map Title to question and Description to summary.
3. Select Create Content, name the resource Support answer content, and edit it in the wide design drawer.
4. Add a read-only Form to Content with Controls Per Row 2, Label 4, and Content 8.
5. Add read-only fields bound to [[record.category]], [[record.environment]], and [[record.renderMode]].
6. Add a full-row read-only TextArea bound to [[record.answer]].
7. Return to the Collapse and verify that both the header and Form change when the preview record changes.

8. Troubleshooting

Test reports a duplicate Row Unique Key

Return a stable business ID, not a row index. The key must remain unchanged across paging, sorting, and reloads.

Design Preview shows Sample Record

The source is missing, unreachable, or failed. Use Test to correct the URL, response paths, or backend request.

The preview does not change after editing the template

Save the template dialog and verify that each mapping exists in Record Fields or the real response.

Read the current record inside Content

Use record.* in child values or Interaction expressions. Do not hard-code values copied from a preview record.

Expanded items disappear after Load more

Confirm that the same business record keeps the same Row Unique Key. Spark can preserve only keys that remain stable.

9. Design recommendations

• Keep a group to about 3–8 visible panels. For more items, provide categories or search.
• Prefer Single Panel Mode for FAQs and long explanations; allow multiple panels when users must compare sections.
• Make each Title explain its expanded content independently, and do not repeat it in Description.
• Pair Disabled with a readable explanation instead of relying on gray styling alone.
• Return a stable unique key from the backend and keep the paging response structure consistent.
• Declare dynamic mappings in Record Fields so they remain selectable, testable, and maintainable.
• Avoid deeply nested Collapse components. Beyond one level, use headings, Tab, or a separate page.