Manage references in steppers

Reference selection

If a form step contains reference fields, then it is possible to configure the selection of these references.

This selection is performed using one of the following components:

  • An auto-complete field that lists selectable records filtered by a search expression as you type in.

  • A reference selection dialog that shows a collection of selectable records. This second option is better if you need to have a detailed view of the records to select.

Auto-completes fetch records as you type in a search expression. To limit the number of fetched records, configure the Autocomplete Max Results property in the global applications configuration.

To configure reference selection:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the form step containing the references.

  3. In the Properties view, select the References Selection finger tab.
    This tab shows a table with the list of references managed in the step.

  4. Click the refresh Refresh References button in the table toolbar to refresh the list with new references.

  5. Configure the reference settings:

    • Reference Picker Type: select one of the options available:

      • Select None if you do not want the reference to be selectable.

      • Auto-Complete displays an auto-complete component to select the reference.

      • Collection displays the list of selectable records in a reference selection dialog.

    • Picker Filter: this filter restricts the selection options for both the auto-complete and reference selection dialog. It applies, for example, when selecting a Customer entity referenced by a Contact entity, to filter only those customers in the same country as the one in the contact information.

    • Sort Expression: this sort expression orders the data in the selectable records.

  6. If you choose the Collection reference picker type, you must configure the following options:

    • Picker Collection View: select the collection used to show the selectable records in the reference selection dialog.

    • Search Configurations: click this cell to select and order search methods that appear in an optional search step preceding the collection of selectable records. If no search method is selected as Available, then this search step does not appear before the collection.

    • User-Defined Sort: select this checkbox to allow users to customize the sort in the reference selection dialog.

The picker filter allows creating functional dependencies between fields. For example, when creating a product, users must select a Family and then a SubFamily, which are both references. In the stepper definition, you can apply the picker filter to show only the subfamilies linked to the selected family.

Picker filters are not applied during mass updates. For example, when mass-updating records belonging to various families, all available subfamilies would be displayed.

Many-to-many creation

If a child collection step points to a child entity that represents a many-to-many relationship, then it is possible to configure selecting the record at the other side of the many-to-many relationship to create the child records in the many-to-many entity.

For example, a ProductStepper stepper has a child collection step to create ProductMarkets. ProductMarket is an entity representing the many-to-many relationship between Products and Markets. When the user creates ProductMarkets, he wants in fact to select Markets, and have ProductMarkets created. This configuration aims to give this capability.

To configure many-to-many creation:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the collection step that manages an entity representing the many-to-many relationship.

  3. In the Properties view, select the Many-to-Many Relationship finger tab.

  4. Select the Many-to-Many Relationship checkbox, and then configure the many-to-many creation options:

    • Target Foreign Attribute: select the foreign attribute that represents the counterpart in the many-to-many relationship.

    • Picker Collection View: select the collection to use for displaying the selectable records on the opposite side of the many-to-many relationship.

    • Picker Filter: SemQL condition pre-filtering the selectable records on the opposite side of the many-to-many relationship.

    • Search Configurations: select the type of search used to filter the selectable records on the opposite side of the many-to-many relationship.

    • Customized Sort: select this option to sort the selectable records according to the sort expression.

    • Sort Expression: sort expression applied to the data in the selectable records.

    • User-Defined Sort: select this checkbox to allow users to customize the sort expression.

    • Default Display Type: default view type used for the collection that shows the selectable records.

    • Allow Table, Allow List, Allow Grid: select the views available for the collection. These must be supported by the selected picker collection.