CardSet Component

CardSet is used to render multiple records from the same data source into a responsive card collection. It is suitable for pages that require quick browsing of entity summaries, such as product catalogs, application lists, asset catalogs, and knowledge entries.

After reading this manual, you can complete the following configuration:

• Load data using Business Object or Custom URL
• Define or import reusable Response Fields for Custom URLs
• Choose Standard, Cover or Compact cards from the visual template library
• Map return record fields to title, description, image, status and metadata
• Configure Fixed Filters, Query Fields and Query Form
• Set the number of columns for desktop, tablet and mobile devices
• Choose the page turning method between Pagination and Load More
• Use Current Record to configure entire card clicks and card operations

CardSet is a data-driven repeating collection and is not used to manually maintain static cards one by one. For tabular data, please use DataList or ProTable.

1. Preparation before use

1.1 Select data source

CardSet supports the following data sources:

Data source	Applicable scenarios
Model Data Source	Data comes from Spark Business Object and requires DQL, model fields or Query Form
Custom URL	Data comes from application API, external service or custom aggregation interface

Before using the Model Data Source, the Business Object, Field, Query, and QUERY scenario Data Form should be completed in Objects Designer.

The Custom URL should provide a pageable collection of records. Recommended response format:

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 12,
    "records": [],
    "total": 0
  }
}

1.2 Example of this article

This article uses the Spark Sample product catalog interface:

POST https://spark.hiforce.ai/spark/api/sample/cardset/products

The interface returns 23 pieces of English product data, including:

Field	Purpose
id	Record unique key
code	Card auxiliary title
name	Card title
description	Card description
imageUrl	Cover image
status	status label
category	Product classification
price	Product price
stock	Current stock
updatedAt	Update time

2. Add CardSet

1. Open the target page and enter Page Designer.
2. Expand Containers in the left component panel.
3. Drag the CardSet into the page container.
4. Select CardSet, first configure Data Source in the property panel on the right, and then configure Card Template.
5. Set a stable name for the control, such as productCardSet.

CardSet no longer requires guessing a Java CardTemplate class name. Template appearance and field mapping are unified in the visual configuration dialog box.

3. Configure Data Source

3.1 Custom URL example

Select Custom URL in Data Source and configure:

Properties	Values
URL	/spark/api/sample/cardset/products
Request Method	POST
Rows Path	data.records
Total Path	data.total
Current Page Path	data.current
Page Size Path	data.pageSize

The Custom URL itself cannot provide model metadata like the Business Object, so the Response Fields also need to be configured in the same Data Source dialog. The example configuration in this article is as follows:

Field Path	Label	Data Type
id	ID	NUMBER
code	Code	TEXT
name	Name	TEXT
description	Description	TEXT
imageUrl	Image URL	URL
status	Status	TEXT
category	Category	TEXT
price	Price	NUMBER
stock	Stock	NUMBER
updatedAt	Updated At	DATETIME

Response Fields have two configuration methods:

1. Click the plus sign to manually add Field Path, Label and Data Type.
2. After filling in the URL, request method and response path, click Test & Import to import from the real response.

Test & Import reads up to 20 records and merges the fields that appear within them. Nested objects will generate point paths in the form of owner.name; arrays are only registered as ARRAY, and unstable paths with array subscripts will not be generated. The import will retain the Label, Data Type and order that have been manually modified, and will only append new fields and will not automatically delete old fields. When the interface returns an empty array or the request fails, the existing configuration will not change.

Response Fields are field contracts saved to the page configuration and do not save the sample values ​​returned by the interface. Opening the Data Source dialog box will not automatically call the background.

CardSet sends the current page, number per page, fixed filter, quick query, and Query Form values. POST request example:

{
  "current": 1,
  "pageSize": 12,
  "conditions": [
    {"field": "status", "operator": "EQ", "value": "ACTIVE"}
  ],
  "queryFormValues": {}
}

Custom URL requests also automatically carry a unified page context header:

Header	Enumeration value	Description
X-Spark-Page-Environment	DEV, TEST, PROD	The current page environment; the preview in the designer is fixed to use DEV
X-Spark-Page-Render-Mode	DESIGN_PREVIEW, RUNTIME	Page Designer, Preview opened by the designer and real record preview are DESIGN_PREVIEW; normal running page is RUNTIME

For example, the development environment run page sends DEV + RUNTIME, and the real record preview in the Card Template dialog box sends DEV + DESIGN_PREVIEW. This is a unified specification for all Page Designer and Page Runtime backend requests, not just CardSet. The backend should handle stable enumeration and do not infer scenarios through Referer; cross-domain Custom URLs also need to allow these two headers in Access-Control-Allow-Headers of CORS.

3.2 Model Data Source

After selecting Model Data Source:

1. Select Business Object.
2. Select DQL Query as needed.
3. Bind the DQL parameters in Request Parameters.
4. The field drop-down list of Card Template will directly use the field metadata of the current Business Object.

The paging, DQL parameters and query conditions of the Model Data Source are uniformly handled by the Spark runtime.

4. Select Card Template

Click the edit icon on the right side of Card Template to open the wide configuration dialog box. The top template library will directly display three thumbnail previews:

Template	Applicable scenarios
Standard	Common business entities, balanced structure of title, description, status and metadata
Cover	Merchandising, media and asset catalogs featuring 16:9 cover images
Compact	Operation and maintenance or management workbench, reducing description area and increasing information density

After selecting a template, the preview on the right will change immediately. There is no need to save or enter the run page to judge the appearance of the template. The bottom of the template library is divided into three tabs according to theme: Content, Query and Layout & paging; the preview on the right is always retained, and Desktop, Tablet, and Mobile are used to switch the preview width.

The configuration area and preview area can be scrolled independently. Card fields, Metadata and Status tones in Content all use independent grouping; Query fields and Fixed filters also use configuration tables with column headers. When there are many configurations, you should continue to scroll down in the current Tab, and the bottom configuration will not be cut off by the dialog box.

5. Configure field mapping

Enter the Content Tab to configure Card fields, Metadata and Status Tones. The right side of each Card field is marked with the card area it is in, such as Heading, Corner, Above title, or Body; Title is marked with a red required mark.

This article's Cover example uses the following mapping:

Card Area	Fields
Eyebrow Field	code
Title Field	name
Description Field	description
Image Field	imageUrl
Status Field	status

The Title Field is the most important identification field and should always be configured. When other fields are empty, no blank space will be retained in the corresponding area.

5.1 Field source and custom path

Field drop-down lists are provided by Data Source:

• Model Data Source uses Business Object field metadata.
• Custom URL uses saved Response Fields.

Label (path) is displayed when selecting a field and you can search by label or path. When you really need to bind an unregistered dynamic field, select Add custom path and fill it in manually. Regular fields should be added to Response Fields first to avoid repeated maintenance of string paths in different CardSets or ProTables.

Nested objects use dotted paths, for example:

owner.name
pricing.amount

Title Field is required to save CardSet. When other optional mappings are empty, the corresponding card area will not be rendered.

5.2 Refresh real preview

After the data source and field mapping are saved, click the refresh icon next to the Live Preview title on the right. The designer will read a record with pageSize=1 and send X-Spark-Page-Environment: DEV and X-Spark-Page-Render-Mode: DESIGN_PREVIEW.

Refresh only updates the display value of the card on the right, and does not add, delete or modify Response Fields. Preserves the current preview and field configuration when the request fails.

5.3 Configure Metadata

Metadata is used to display short information such as price, inventory, person in charge or update time. Click Add row to add a new row. The configuration table displays the Label, Field, and Format column headers permanently:

Properties	Description
Label	The short label shown in the card, e.g. Price
Field Path	Data field, such as price
Format	TEXT, NUMBER, CURRENCY, DATE or DATETIME

Product examples suggest adding:

Label	Field	Format
Category	category	TEXT
Price	price	CURRENCY
Stock	stock	NUMBER

5.4 Configure Status Tones

Status Tones is an optional status color map. The configuration table uses two columns: When status equals and Show tone. For example, ACTIVE is mapped to SUCCESS and DRAFT is mapped to WARNING. When no mapping is configured, CardSet uses built-in semantic colors for common state values ​​and MUTED for unknown values.

6. Configure query

Enter the Query Tab to configure Query Form, Show Filter Bar, Query Fields and Fixed Filters. Query Form and Show Filter Bar are located on the top toolbar, and query fields and fixed conditions are grouped below.

6.1 Query Fields

Query Fields are displayed in the first line of the query area. Configuration table fixed display of Field, Label, Operator and Type column headers.

After you select a field, the designer prepopulates the query configuration with the Label and Data Type of the Response Field or Business Object field; the Label and query type can still be adjusted. OBJECT and ARRAY will not appear in the shortcut query field candidates.

Examples of recommended products:

Field	Label	Operator	Type
name	Search products	LIKE	TEXT
category	Category	EQ	TEXT
status	Status	EQ	TEXT

Date and time types are automatically rendered as Range Pickers. Search, More, and Reset are always to the right of the query bar.

6.2 Fixed Filters

Fixed Filters take effect every time you query, but will not be displayed to the running user. For example, to only display valid products:

Field	Operator	Value
status	EQ	ACTIVE

Turning off Show Filter Bar only hides the user query area and does not disable Fixed Filters.

6.3 Query Form

Query Form is an optional advanced query form. After selecting the Data Form of the QUERY scenario in the drop-down list, click More during runtime to expand the form. When CardSet uses Model Data Source, the drop-down list will give priority to displaying the query form of the current Business Object; when using Custom URL, it will display the QUERY form available in the application.

• Model Data Source should select the QUERY Data Form of the current Business Object.
• Custom URL will send queryFormValues to the backend as it is, and the interface will interpret the meaning of the fields.

7. Configure layout and paging

Enter the Layout & paging Tab to configure responsive column numbers, spacing, paging, and row unique keys. The Responsive columns group will use the three device diagrams of Desktop, Tablet and Mobile to display the current number of columns in real time; the Paging & data group centrally maintains Paging Mode, Page Size and Row Unique Key.

Recommended default values:

Properties	Default Value
Desktop Columns	4
Tablet Columns	2
Mobile Columns	1
Spacing	DEFAULT
Page Size	12
Paging Mode	PAGINATION
Row Unique Key	id

Paging Mode supports:

• PAGINATION: Displays the total number and page number, suitable for managing pages.
• LOAD_MORE: Append the next page of records, suitable for browsing directories.
• NONE: Only the data currently returned by the interface is displayed, and the page turning control is not displayed.

Use the Desktop, Tablet, and Mobile segment controls on the right to check the width of a single card; the number of columns will automatically switch according to the page width during actual operation.

8. Configure interactions

CardSet supports two interaction levels:

1. onClick for the entire card.
2. onClick for an action at the bottom of the card.

8.1 Configure card actions

Card Actions are configured outside the Card Template dialog. Select the CardSet on the canvas, then use the Card Actions child-element section in the right property panel:

1. Click Add child element to create a CardAction.
2. Enter its Title in the add form and confirm. The designer automatically selects the new CardAction.
3. In the CardAction property panel, use the shared Icon picker to select a system icon or upload a custom image.
4. Click Interaction, then add an onClick event and its actions.

To edit an existing action, click its row in the Card Actions list. Use the drag handle on the left to reorder actions. At runtime, the first three actions are displayed at the bottom of each card in that order. Action clicks stop event propagation, so they do not also trigger the card-level click.

8.2 Configure the card-level click

Select the CardSet itself again, click Interaction, and configure its onClick. A card with a card-level click can receive Tab focus and can be activated with Enter or Space.

8.3 Read the current record

Before dispatching either interaction, CardSet writes the clicked card's record to the runtime context as record. The Interaction editor exposes this data source as Current Record, so subsequent actions can read:

record.id
record.code
record.name

These values come from the card clicked at runtime; they are not design-time constants. For the Interaction editor to offer the correct Current Record field candidates, configure Response Fields for a Custom URL or provide Business Object field metadata for a Model Data Source.

8.4 Example: Display card details in a drawer

The View product example configures two actions under the same onClick, in this order:

1. Add Set component value and name it Fill product details. Map Current Record fields such as record.id, record.code, and record.name to the corresponding form controls in the details drawer.
2. Add Open/close dialog/drawer and name it Open product details. Set Target component to Product details (Drawer) and enable Open target.

Write the form values before opening the drawer. The Interaction editor executes the Action tree from top to bottom; reversing these actions can briefly show the previous record or empty values when the drawer opens.

After configuration, clicking View product at the bottom of a card opens the drawer with details for that card.

9. Sample backend implementation

Sample code is located at:

spark-sample/src/main/java/hiforce/spark/sample/cardset/

The product query reuses the paging and conditional processing of the ProTable example. The CardSet controller is responsible for exposing the dedicated URL; the cover image is generated by the local PNG endpoint and does not rely on external image services.

It can be verified after starting locally:

curl -X POST 'http://localhost:18080/spark/api/sample/cardset/products' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-Spark-Page-Environment: DEV' \
  -H 'X-Spark-Page-Render-Mode: DESIGN_PREVIEW' \
  -d '{"current":1,"pageSize":12,"conditions":[{"field":"status","operator":"EQ","value":"ACTIVE"}]}'

The data.requestContext in the sample response will echo the normalized environment and renderMode to verify that the backend actually received and processed the page context. Production business interfaces can use this context to select data or perform audits without requiring an echo.

10. FAQ

The designer only has the template name, no appearance

Make sure you are using the new Card Template editing icon. The template should be displayed with three thumbnails; if the old class name like ResourceInfoCard still appears, refresh the designer metadata and re-add the CardSet.

No card when running

Check in order:

1. Whether the Data Source has been saved.
2. Whether Rows Path points to an array.
3. Whether the Title Field exists in the record.
4. Check whether the request in the browser Network is successful.
5. Whether Fixed Filters exclude all records.

The field drop-down list for Custom URL is empty

Open the Data Source and check whether the Response Fields have been saved. You can add it manually, or you can use Test & Import after confirming that the URL and Rows Path are correct. Refreshing Live Preview is not responsible for generating the field catalog.

Test & Import has no import fields

Check the URL, Request Method, Rows Path, and Browser Network. The interface must return at least one record under the current conditions; legal but empty results will not generate fields, and Response Fields should be maintained manually in this case.

Pictures are not displayed

Image Field must return an image URL that is accessible to the browser. Relative URLs should be based on the current Spark domain name and confirm that the interface does not return an HTML login page.

There is no change in the result after querying

The Custom URL backend must handle conditions and queryFormValues. CardSet is only responsible for sending query semantics and will not perform secondary filtering on the complete data set in the browser.

11. Configuration Checklist

• Data Source can return records and total
• Custom URL configured and saved Response Fields
• Row Unique Key is unique in each record
• The appropriate template has been selected via thumbnail
• Title Field is configured and returns a non-null value
• Cover template has configured accessible Image Field
• Metadata does not exceed the amount of information required for page scanning
• Query Fields and Fixed Filters use fields and operators supported by the backend
• Custom URL backend correctly handles two X-Spark-Page-* Headers
• No overflow in desktop, tablet and mobile previews
• Pagination or Load More can correctly read the next page
• Card clicks and action items can read Current Record