Skip to main content

Control - Cascading

The Cascading control allows users to progressively select items from a data source. Each selection updates the subsequent options, displaying only the child items relevant to the current choice. This enables users to quickly navigate to their target selection.

The Cascading control requires a configured data source. Essentially, its data source is a worksheet containing an org view, meaning the current worksheet is related to the data source worksheet.

Common Use Cases​

The Cascading control is ideal for scenarios requiring hierarchical data selection, such as:

  • Region/city selection
  • Product categorization
  • Organizational structure

By properly configuring the data source, it can easily handle data structures of varying complexity to meet diverse needs.

Field Configuration​

In the customer worksheet, displaying the customer's region facilitates statistical analysis by area.

1. Add a Cascading control​

2. Select a data source​

Two data source options:

  • Create a new data source worksheet with an org view.

  • Use an existing worksheet with a pre-configured org view as the data source.

When selecting an existing worksheet as the data source, it must already be related with a properly configured org view of that worksheet to be eligible for selection.

How to configure an org view

Here, we will use the example of creating a new data source worksheet.

3. Configure Cascading field​

Data source​

The automatically created worksheet and its org view have been selected as the data source. The source data worksheet follows the naming format "Data Source-Date Time" and is marked as hidden by default. This means it will not appear in the standard user's left navigation panel within the application.

Once the data source is confirmed, go to configure this data source worksheet.

Selection methods for data items​

Two selection methods are supported:

  • Cascading menu: Displays each level's content horizontally.

  • Tree selection: Displays each level's content vertically.

Default value​

The Cascading field supports setting default values through two methods: selecting other field values or querying worksheets.

Other field values: If the current worksheet contains other cascading fields that use the same data source, you can reference values from these other cascading fields as default values.

Query worksheets: Default values can be set by querying records from either the data source worksheet or other worksheets. The queried worksheets must contain cascading fields that use the same data source.

Other settings​

Data source filtering​

The Cascading field provides flexible configuration options for displaying data items to meet various requirements. It primarily offers three data display modes: All Data, Data Accessible to Users, and Data Matching Filter Conditions.

  1. All data

    When "All" is selected, the cascading field will display all data items from the data source without any restrictions. Users can freely choose from all available options.

  2. Viewable data

    In the data source worksheet, you can configure data viewing permissions for members. When "Viewable" is selected, the system will display only the data items that the current user has permission to view based on their role or access permissions.

  3. Data matching filter conditions

    Users can define custom filter conditions according to business needs. This filtering method helps users quickly locate the required data, improving operational efficiency.

Selection range​

The Cascading control supports configuring the selectable range of data items, allowing users to set both the starting and ending selectable levels separately.

Start Item Selection Range

  • All top-level items: Selection begins from the first level of the data source.

  • Items matching conditions: After setting filter conditions, if a parent item does not meet the criteria, its eligible child items will be displayed directly at the first level for selection.

    • Example: If the filter condition is set to "Name contains 'City'", when selecting a city, the provincial level will no longer appear. Instead, only the qualifying cities will be shown as the starting options.

  • Designated item: You can directly select a fixed data item as the starting point. Other items at the same or higher levels will no longer be selectable.

Ending Item Selection Range

  • Final level: Selection can extend all the way to the last level of the hierarchy.

  • Specified levels backward: Starting from the selectable item, selection is restricted to the specified number of levels.

    • Example: If the "Start Item" is set to "All top-level items" and the "End Item" is configured with "Specified levels backward = 1", only selections up to "City" level are allowed (not "District"). If "Specified levels backward = 2", selections can extend to "District" level.

Mandatory full-level selection​

When "Mandatory full-level selection" is enabled, the selected item must reach the end of the selection chain to be successfully saved. For example, if you select a region as "Henan Province - Zhengzhou City - Jinshui District," this represents a three-level selection chain. With this option enabled, you must select down to the final level (i.e., Jinshui District) to save your choice. If this option is disabled, you may save your selection at just the provincial level or at the provincial/municipal level.

When you choose the "Arbitrary choice" mode, the system allows you to make and save selections at any level. In this mode, you can also set a "Number of selected levels backwards." For instance, if you set it to 1 level, you can only begin selecting from the second level onward when the data chain has more than two levels. If a data item's hierarchy does not meet the specified levels requirement, you can only select its final level.

Example: Suppose you are selecting the region "Henan Province - Zhengzhou City - Jinshui District." If the "Number of selected levels backwards" is set to 1 level, you cannot select "Henan Province" and must choose from "Zhengzhou City" onward. If it is set to 2 levels, you must start selecting from "Jinshui District".For a municipality like Shanghai, which has only two levels (e.g., "Shanghai Municipality - Pudong District"), you may still select the district level.

Display hierarchical path in results​

When enabled, the Cascading field will display the full hierarchical path (e.g., "Henan Province/Zhengzhou City/Jinshui District"). When disabled, only the final level's content will be shown (e.g., "Jinshui District").

Store hierarchical path​

When enabled, the system will store the complete hierarchical path of the selected option at the time of selection and will not automatically synchronize subsequent changes to the path. To obtain the latest hierarchical path, you may recalibrate the cascading field. Storing the path allows users to perform hierarchical data analysis in charts.

Search settings​

Through search settings, configure to search only specified fields, enabling faster and more precise retrieval.