Skip to main content

Control - Cascading

The Cascading field allows users to select items step by step from a hierarchical data source. Each selection dynamically updates subsequent options, displaying only child items related to the current selection. This enables users to quickly locate the desired option.

A cascading field requires a data source, which is essentially a worksheet with an org view. The current worksheet must have a relationship with the data source worksheet.

Common Use Cases​

Cascading fields are widely used in scenarios requiring hierarchical selection, such as regions, product categories, or organizational structures. Proper configuration of the data source allows for flexible handling of complex data hierarchies.

Field Configuration​

In the Customer worksheet, we need to mark the customer’s region for statistical purposes.

1. Add a Cascading Field​

Drag a "Cascading" control from the control panel to the desired position.

2. Select Data Source​

Two options:

  • Create a new source worksheet with an org view.
  • Choose an existing worksheet that already contains an org view.

When selecting an existing worksheet, the worksheet must already be configured with an org view linked to the current worksheet.

How to configure org views

For this example, we create a new source worksheet.

3. Configure the Cascading Field​

Data Source​

The automatically created worksheet and its org view have been selected as the data source. Its default name format is DataSource-DateTime. This worksheet is hidden and will not appear in the navigation for regular app members.

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

Selection Mode​

The cascading field supports single-select and multi-select. After saving, the mode can still be switched.

For performance reasons, multi-select allows a maximum of 20 selections.

Option Display​

Two display modes are supported:

  • Cascading Menu: Horizontal display of each level.

  • Tree Selection: Vertical display of each level.

Default Value​

Default values can be set in two ways:

  • Other field values: Reference another cascading field using the same data source in the current worksheet.
  • Query worksheet: 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 Properties​

Filter Data Source​

Cascading options can be filtered to meet business requirements:

  1. All data: Displays all options from the data source.
  2. Viewable data only: Filters options based on user role or permissions.
  3. Filtered data: Uses custom filters to ensure relevant and accurate selection.

Selection Range​

Selectable options can be limited by start and end levels.

Start item range:

  • All top-level: Selection starts from the first hierarchical level.

  • Conditional items: 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.

  • Specified 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.

End item range:

  • Final level: Selection can go to the final level.

  • Specified levels backward: Only selectable up to a set number of levels from the starting item.

    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​

  • If enabled, the selected option must be the last level in the hierarchy to save.

  • If disabled, higher-level selections can also be saved.

  • Optional “Arbitrary choice” mode allows selecting 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 select the region Henan Province / Zhengzhou City / Jinshui District (three levels).

    If "Number of selected levels backwards" is set to 1, the top-level Henan Province cannot be selected; selection starts from Zhengzhou City.

    If "Number of selected levels backwards" is set to 2, selection must begin from Jinshui District.

    For municipalities like Shanghai with only two levels, you can still select the district level.

Display Hierarchical Path​

  • If enabled: Displays full path, e.g., Henan Province / Zhengzhou City / Jinshui District.
  • If disabled: Displays only the last level, e.g., Jinshui District.

Store Hierarchical Path​

If selected, stores the current selected hierarchical path. Updates will not automatically propagate. Recalibration is needed for updated paths. Stored paths can be used in charts for hierarchical grouping.

Search Settings​

By default, all fields in the option are searchable. Configure to restrict which fields are searchable for faster, more accurate retrieval.

Was this document helpful?