DataList Component

DataList displays and operates on Business Object data in a page. It reads fields, query definitions, and actions from the Business Object, making it suitable for model-backed lists such as orders, devices, and customers.

After reading this guide, you will be able to:

• Bind a Business Object and a DQL Query
• Use FX to pass values from input components, Page Context, or URL parameters to DQL
• Configure columns, column links, pagination, and display styles
• Use Fixed Filters to enforce a base data scope that users cannot remove
• Configure first-row quick search with Query Fields and advanced search with Query Form
• Refresh DataList or replace local table data from toolbar buttons
• Configure Business Object Actions as row operations

DataList is a Business Object model list and does not provide a Custom URL data source. To call an arbitrary HTTP API directly, use the Custom URL data source described in the ProTable Component guide. DataList does not host task lists; those will be provided by the dedicated TaskList component.

1. Prerequisites

1.1 Prepare a Business Object

Go to Spark Designer → Objects Designer and confirm that the target Business Object has the following configuration:

1. It is mapped to an available data source and physical table.
2. Fields that need to be displayed are available for list display.
3. Fields used for filtering or querying are marked as searchable, filterable, indexed, or identifier fields.
4. The field used as the unique row identifier is stable and never duplicated, usually id.
5. Any required row operation has a corresponding Object Action defined on the Business Object.

If no candidates appear for Fixed Filters or Query Fields, first check whether the Business Object fields are marked as searchable, filterable, indexed, or identifier fields.

To provide advanced search with Query Form, also create a Data Form for the same Business Object and enable Query under Usage Scenarios. Query Form is optional and does not affect Fixed Filters or Query Fields.

1.2 Create DQL as needed

DQL stores reusable Business Object query conditions. Go to:

Objects Designer → Data → Filters

Click Add DQL to create a query. The system generates the Query Key automatically, so you do not need to maintain it manually.

For example, use an optional fuzzy match on a pet code:

code LIKE :code

Set the code parameter to optional in the parameter definition. At runtime:

• When a value is provided, the query performs a contains match on the code.
• When the parameter is empty, the condition is omitted from the query.
• Pass the user's input directly to a LIKE parameter; you do not need to add % manually.

If a DQL parameter is required, DataList must provide a valid value when it runs the query, otherwise the query fails.

1.3 Confirm the data isolation strategy

Whether a tenant field is required depends on the isolation strategy of the data model and data source:

• An object with a dedicated data source, or one that does not require tenant isolation, can rely on data-source-level isolation without adding a tenant field.
• When multiple tenants share a physical table, define exactly one tenant field in the Business Object mapping.
• DQL is responsible only for business query conditions and cannot override isolation conditions enforced by the model layer.

2. Add DataList

1. Open the target page in Page Designer.
2. Expand the Data group in the component palette.
3. Drag DataList into a container that accepts it.
4. Select DataList and configure the Basic section in the property panel.
5. Give DataList a stable, recognizable component name, such as petList or orderList.

A stable component name makes the target easy to identify later in FX, button interactions, and Component API actions.

3. Configure the model and DQL

3.1 Select a Model

Select a Business Object in the Model property. DataList then loads:

• Displayable fields
• Queryable fields
• Business Object Actions
• Available DQL Queries

After switching the Model, review Columns, Fixed Filters, Query Fields, Query Form, DQL Parameters, and Row Operations again. Fields, forms, or actions from the previous model may not apply to the new model.

3.2 Select a DQL Query

In DQL Query, select a published DQL for the current Business Object. DQL is optional:

• Without a DQL selection, DataList runs the base model query and adds the filters configured on the page.
• With a DQL selection, DataList runs the DQL and continues to add Fixed Filters, Query Fields, and Query Form conditions.

DQL, Fixed Filters, Query Fields, and Query Form are combined with AND.

3.3 Configure DQL Parameters

After selecting a parameterized DQL, DQL Parameters lists its parameter names. These names come from the DQL definition; the page only needs to configure their values.

Click FX next to a parameter, add a variable in Value Resolver, and choose its source. Common sources include:

Source	Use case
Component Value	Read the current value of an Input, Select, Radio, Date Picker, Uploader, or another page component
Page Context	Read Page Context or business parameters
URL Parameter	Read a query parameter from the browser URL
Current Row	Read a field from the current record in a row context
Static Value	Pass fixed text, number, or Boolean values

After adding a variable, reference it in Target Value:

[[petCode]]

A Range component returns two elements. Reference its start and end values separately:

[[queryRange.0]]
[[queryRange.1]]

You can reference multiple variables in one Target Value when a parameter must combine them. If there are many parameters, the DQL Parameters area scrolls within a bounded height instead of continuously pushing the properties below it farther down.

Clicking Add Variable in the FX dialog only adds a variable binding. Configure its source and Target Value, then save the dialog.

4. Configure Columns

Expand Columns and select the Business Object fields to display. Their order is the column order at runtime.

Recommendations:

• Put the name or code that best identifies the record in the first column.
• Arrange quantities, status, time, and other fields in the order users read them.
• Avoid displaying too many low-frequency fields at once. Show details through a column link, row operation, Dialog, or Drawer instead.
• Make sure the value selected as Row Unique Key is unique across all records.

4.1 Configure a Column Link

To open a detail page when users click a column, edit that column's link configuration:

1. Enable the column link.
2. Select the destination in Target Page.
3. Enter the parameter accepted by the destination page in Param Name, usually id.
4. Select the field from the current row in Row Field.

For example, passing the current row's id as the id parameter produces navigation parameters similar to:

?id=<current row id>

5. Configure Pagination

Expand Pagination and set the default page size. At runtime, DataList passes the current page number and page size to the model query.

Recommendations:

• Use 10 to 20 records per page for a typical administration list.
• Increase the page size when there are few fields and enough vertical space.
• Do not load all records through an excessively large page size when the data set is large.

When a query button calls reloadTable, DataList starts again from the first page so that it does not remain on a later page that may no longer exist.

6. Configure fixed filters and the query area

DataList configures invisible data-scope constraints separately from query conditions that users can operate:

Setting	Visible at runtime	Purpose
Fixed Filters	No	Fixed conditions that every query must satisfy
Query Fields	Yes	Quick query controls shown in the first row of the filter bar
Query Form	Yes	Advanced query form shown after clicking More
Show Filter Bar	Not applicable	Controls whether Query Fields, Query Form, and query actions are shown

Unlike TaskList, DataList does not provide default query fields. To show a query area, configure at least one Query Field or select a Query Form, and keep Show Filter Bar enabled.

6.1 Configure Fixed Filters

Fixed Filters are added automatically to every query. They are not shown at runtime and users cannot remove them. They continue to apply even when Show Filter Bar is disabled.

Use them when:

• A page should show only one business type
• Archived or deleted records should always be excluded
• Results must be limited to a project, organization, or parent record from Page Context
• A URL parameter should limit the list to the record currently being viewed

In Fixed Filters, click Add and configure Field, Operator, and Value for each condition. Enter Value directly or click FX to reference Page Context, URL Parameter, Component Value, or a static variable in the shared Value Resolver.

Fixed Filters support these common operators:

Operator	Meaning	Example value
EQ	Equals	OPEN
NEQ	Does not equal	DELETED
LIKE	Contains	PET-01
GE	Greater than or equal to	100
GT	Greater than	100
LE	Less than or equal to	500
LT	Less than	500
BETWEEN	Range	2026-07-01,2026-07-31
IN	Belongs to a set	OPEN,PROCESSING
NOT_IN	Does not belong to a set	DELETED,CLOSED

Separate multiple values for IN and NOT_IN with commas. Use start value,end value for BETWEEN. Empty values do not generate filter conditions.

6.2 Enable or disable Show Filter Bar

Show Filter Bar controls the complete runtime query area:

• Enabled: shows the query area when at least one Query Field or Query Form is configured.
• Disabled: hides Query Fields, Query Form, Search, More, and Reset without affecting Fixed Filters.
• Enabled with no Query Fields or Query Form: does not show an empty query area.

Disable Show Filter Bar when the page has a fixed query scope and users should not narrow the results further.

6.3 Configure Query Fields

Query Fields define the quick query controls in the first row of the filter bar. Open the Query Fields dialog, click Add, and configure each row:

Property	Description
Field	Select a queryable field from the current Business Object; the same field cannot be selected more than once
Operator	Available operators are based on the field's actual type
Placeholder	Placeholder text shown in the runtime control to explain its query purpose

Use the up and down icons to reorder query fields and the delete icon to remove a field. Runtime controls follow this order. Field, Operator, and Placeholder labels appear above their controls in the configuration dialog, and Operator reserves enough space for longer localized names.

Query Fields render controls and restrict operators according to field type:

Field type	Default operator	Available operators	Runtime control
Text, String, Textarea	Contains	Contains, Equals, Not equal	Text input
Number, Decimal, Money	Equals	Equals, Not equal, Greater than or equal, Greater than, Less than or equal, Less than	Number input
Enum, Select, Boolean	Equals	Equals, Not equal, In, Not in	Select; In and Not in use multi-select
Date, DateTime, Timestamp	Range	Range	Date or date-time range picker
User, Department	Equals	Contains, Equals, Not equal	User or department selector

Runtime controls do not repeat visible Labels; Placeholder explains each field's purpose. Date and date-time fields use Range: the start compiles to GE, the end compiles to LE, and both boundaries are inclusive.

6.4 Create and select a Query Form

Query Form is optional and holds advanced conditions that do not fit in the first row. DataList references a Data Form from Objects Designer, not a Task Form.

To create a Query Form:

1. Go to Spark Designer → Objects Designer and open Data Forms.
2. Create or edit a Data Form for the same Business Object as DataList.
3. Enable Query under Usage Scenarios.
4. Keep only the queryable fields users need, and configure suitable titles, Placeholders, and Field Width values.
5. Save the Data Form, return to Page Designer, and select it in DataList's Query Form property.

Query Form preserves the 24-column Field Width grid configured in Data Form. For example, four fields with width 6 remain on one row in the runtime More area; widths of 8, 8, and 8 show three fields per row. To wrap, make the current row total 24 or adjust field order and width in Data Form.

The Query Form dropdown lists only Data Forms that are available for the current Business Object and support the Query scenario. If it is empty, check that the Data Form is bound to the same Business Object, Query is enabled, and the current version has been saved.

After users click the runtime More icon, Query Form appears below the quick query row. Its fields follow these rules:

• Only queryable, visible fields from the current Business Object are rendered.
• Text uses contains matching; ordinary scalar fields use equality matching.
• Date, DateTime, and Timestamp automatically use Range queries.
• Query mode does not enforce Required validation, and empty fields do not participate in the query.
• Uploader, Multi Row Input, Rich Editor, and JSON Editor are not rendered as query controls.

6.5 Search, More, and Reset

• Search: reads current Query Fields and Query Form values and queries again from the first page.
• More icon: appears only when Query Form is configured and expands or collapses the advanced query area.
• Reset icon: clears Query Fields and Query Form values, collapses More, and queries again from the first page.
• Enter: runs the query directly from a text Query Field.

Empty values do not participate in the query. The final query combines these conditions:

Business Object data permissions and isolation conditions
AND DQL Query
AND Fixed Filters
AND Query Fields
AND Query Form

7. Configure Toolbars (optional)

DataList supports a left toolbar and a right toolbar. Toolbars contain list commands and custom components; they are not prerequisites for the built-in query bar. Prefer Query Fields and Query Form for ordinary field queries instead of adding duplicate Search and Reset controls to a Toolbar.

Toolbars are still appropriate when:

• DQL parameters read custom Input, Select, or Date Picker components on the page
• The list provides commands such as Create, Import, or Export
• The page needs an Uploader, Dropdown, or business-specific button
• A Component API action must refresh the list or replace local table data

Select DataList and open Toolbars in the property panel:

1. Click Add in Left Toolbar and choose an Input, Date Picker, Select, or another query component.
2. Click Add in Toolbar and choose a Button, Dropdown, or another action component.
3. Select an added component and configure its Label, Name, and interactions.

Typical layout:

• Left Toolbar: custom DQL parameter controls, Uploader, or other business inputs.
• Toolbar: Create, Import, Export, and other action buttons.

After selecting a toolbar component, continue editing the component itself in the property panel. Give each query component a stable, unique name so that DQL parameters and button interactions can reference it.

7.1 Refresh DataList from a custom DQL query button

Only add a Search button and configure its click interaction when custom Toolbar controls drive DQL Parameters or another custom query:

1. Select the Search button and open Interaction editor.
2. Add a Component API action.
3. For Target Component, select the current DataList, for example petList.
4. For Function, select reloadTable.
5. Save the interaction.

When the button is clicked, DQL Parameters resolve the current component values again, and DataList queries from the first page.

7.2 Update local data with setTableData

When a button calls a custom API first and should display the returned array directly in DataList, call:

setTableData(data)

data must be an array of records. This function replaces the current table data and resets pagination state. For a standard Business Object query, prefer reloadTable so that the model query continues to manage pagination, filters, and the total count consistently.

7.3 Toolbar Uploader and Import button

To upload a file before importing it, use this structure:

1. Add an Uploader to the toolbar and give it a stable name, such as importFiles.
2. Add an Import button.
3. In the Import button's request parameters, use FX to read the Component Value of importFiles.
4. After the request succeeds, call reloadTable on DataList.

Uploaded toolbar attachments are managed through the attachment viewer. The toolbar must not expand the complete attachment list and distort the layout. An Uploader inside a form is a form field and uses different display and submission behavior from a toolbar Uploader.

8. Configure Row Operations

Row Operations execute a Business Object Action on the current record, such as edit, enable, disable, archive, or delete.

8.1 Prerequisite

Define the action and its parameters on the Business Object first. DataList should not replace reusable, validated, or auditable business actions with temporary front-end logic.

8.2 Add a row operation

1. Expand Row Operations.
2. Add an operation.
3. Select a Business Object Action.
4. Configure the operation name and display mode.
5. Bind Action parameters to Current Row fields, static values, or Page Context.
6. Arrange multiple row operations in business order.

For example, a delete action usually binds its record parameter to the current row's id.

8.3 Configure interactions

When editing a row operation's Interaction, you can configure:

• A confirmation message before execution
• Opening a Dialog or Drawer
• Setting Page Context
• Calling another component function
• Refreshing DataList after execution

Dangerous operations should have an explicit confirmation step. After an operation completes, call reloadTable on the current DataList to display the latest data.

9. Advanced properties

Advanced DataList properties include:

Property	Description
Enable Row Number	Display row numbers
Table Size	Set large, middle, or small density
Show Header	Show the header row containing column titles; disabling it hides only column titles, not the DataList title, Toolbar, query area, or data rows
Bordered	Show or hide table borders
Row Unique Key	Unique identifier field for each row; defaults to id

Row Unique Key must be stable and unique. Using a field that may be duplicated or changed, such as a name or status, can break selection state, updates, and rendering.

10. Complete example: fuzzy search by Pet Code with a DQL parameter

Goal: A user enters a Pet Code and clicks Search to run a fuzzy code query. When the input is empty, DataList shows all accessible records.

If code is an ordinary queryable field, the simpler approach is to add code to Query Fields, choose Contains, and set a Placeholder. Runtime then uses the built-in Search and Reset. The example below demonstrates a reusable parameterized DQL or a DQL parameter sourced from a custom Toolbar control.

Step 1: Create the DQL

Create this DQL under Data → Filters for the Business Object:

code LIKE :code

Set the code parameter to optional.

Step 2: Add the query component

Select DataList, open Toolbars, click Add in Left Toolbar, and choose Input:

• Label: Pet Code

Step 3: Bind the DQL parameter

1. Select the DQL Query you created in DataList.
2. Find code in DQL Parameters.
3. Click FX.
4. Add a variable named petCode.
5. Select Component Value as Source.
6. Select the Pet Code component.
7. Click the "+" control to add the variable.

[[petCode]]

Step 4: Configure the Search button

Add a Component API interaction to the Search button:

• Target Component: the current DataList
• Function: reloadTable

Step 5: Verify the result

1. Leave Pet Code empty and click Search. All accessible records should be returned.
2. Enter part of a code and click Search. Records whose code contains the text should be returned.
3. Clear the input and click Search again. Results should no longer be filtered by code.
4. If Fixed Filters, Query Fields, or Query Form are also configured, confirm that the results satisfy all conditions together.

11. Save, preview, and verify at runtime

After completing the configuration, verify it in this order:

1. Save the page.
2. Open Preview and check column widths, toolbar wrapping, Query Fields, the Query Form grid, and pagination.
3. Test DQL parameters both with a value and empty.
4. Test the built-in Search, More, Reset, column links, and row operations.
5. Open the actual Runtime page and repeat the critical queries and operations.
6. Confirm that toolbar alignment, component widths, and interaction results match between Preview and Runtime.

Design mode provides configuration and an approximate preview only. Verify data permissions, real attachment uploads, API calls, and model queries at Runtime.

12. Troubleshooting

12.1 No fields are available after selecting a Model

Check whether the Business Object has a completed table mapping, whether its fields are available for list display or querying, and whether the current version has been saved or published.

12.2 No DQL Parameters appear after selecting a DQL

Only parameters declared as :PARAM_NAME in DQL appear in DQL Parameters. Validate and save the DQL in Objects Designer first, then return to the page and select it again.

12.3 An empty parameter still returns no data

Check whether the DQL parameter is required. To make an empty value mean "do not filter," set the parameter to optional and ensure it controls only the condition that should be omitted.

12.4 A LIKE query returns no results

Pass the user's text directly and do not add % to the FX value. Also check whether the field type supports text contains queries.

12.5 Data does not change after clicking a custom Toolbar Search

Check the following in order:

1. The Search button has a Component API action.
2. Target Component is the correct DataList.
3. Function is reloadTable.
4. The DQL parameter references the correct component through FX.
5. The component name is unique and was not changed after configuration.

12.6 Query Fields do not appear or take effect

Check the following in order:

1. Show Filter Bar is enabled.
2. At least one field has been added under Query Fields.
3. The Business Object field is searchable, filterable, indexed, or an identifier field.
4. The Operator applies to the field type.
5. The built-in Search was clicked; empty values do not participate in the query.

12.7 The Query Form dropdown is empty

Check that the Data Form is bound to the same Business Object as DataList, Usage Scenarios includes Query, and the current development version has been saved. A regular Create, Edit, or View Data Form is not a Query Form candidate.

12.8 The row operation list is empty

Define an Object Action on the Business Object first and confirm that DataList is bound to that same Business Object.

12.9 The page still shows stale data after a row update

Call reloadTable on DataList in the interaction chain after the operation succeeds. If you use setTableData, make sure you pass a complete record array rather than one record or an outer API response object.

12.10 Preview works, but Runtime reports a permission or data isolation error

Check the Business Object version published to the Runtime environment, data source permissions, user data permissions, and model isolation configuration. Do not use front-end DQL parameters to bypass model-level isolation rules.

13. Configuration checklist

• DataList is bound to the correct Business Object
• Columns contain only fields that need to be displayed
• Row Unique Key is stable and unique
• DQL has been validated and parameter requirements match the business need
• DQL Parameters have the correct FX sources and Target Values
• Fixed Filters do not exclude valid records incorrectly
• Show Filter Bar is enabled or disabled as required by the page
• Query Fields have the correct fields, operators, Placeholders, and order
• If advanced search is needed, Query Form is bound to the same Business Object and supports the Query scenario
• The custom Toolbar Search button calls reloadTable on the current DataList
• Column links pass the correct row fields
• Row Operations bind the correct Current Row parameters
• Both Preview and Runtime have been verified

With these settings complete, DataList can serve as a reliable Business Object list entry point and work with page query components, DQL, and business actions.