A reference set selector is used to allow the end-user to display or select the value(s) of a many-to-many (reference set) association by selecting the associated object(s).
A reference set selector must be placed in a data widget.
For example, you could group customers into groups, and each customer could belong to several groups. Each Group can have many customers. The entities Customer and Group have a many-to-many (reference set) relationship. A reference set selector can be used to select the groups the customer belongs to.
What you can do with a reference set selector depends on the Owner of the association. In the example domain model below, Owner is set to Default (in the association properties ‘Customer’ objects refer to ‘Group’ objects).
You can put a reference set selector in a Customer data view to allow the user to select the Group(s) to which the customer belongs. However, because the Customer is the owner of the association, you cannot put a reference set selector in a Group data view to select the Customer(s) in the Group.
To allow you to both add a Group to a Customer, and add a Customer to a Group, you need to set ownership of the association to Both.
In the reference set selector, the related entity and association used to connect it to the entity in the data view are displayed at the top of the reference set selector, and the names of the attributes of the associated objects which will be displayed are shown inside the reference set selector. Each attribute is displayed in a grid column. The association and related entity and attributes are displayed between square brackets, and colored blue.
For example, using the domain model above, the following reference set selector allows the end-user to associate a Customer with one or more Groups by setting the association Customer_Group. This is done by selecting the Name(s) of the Group(s) associated with the current Customer.
The reference set selector looks a lot like a data grid and consequently shares many properties with it. The main differences are that the reference set selector lacks a search bar and that it has Add and Remove buttons instead of New and Delete. This is because they perform slightly different functions:
- The Add button adds an association to an existing object. You will need to specify the page which opens when you want to add a new association. For more information, see Add Button.
- The Remove button removes the association to an object, but does not change or delete the object itself
You must explicitly commit the object in the data view containing your reference set selector to save the association changes. This can be done, for example, by having a Save button for the object in the data view (as shown for the Customer entity in the picture above).
An example of reference set selector properties is represented in the image below:
Reference set selector properties consist of the following sections:
There are three additional sets of properties which do not appear in the properties of the reference set selector widget.
The control bar contains the buttons needed to search, add, and remove associations. For more information see Control Bar.
The rows of the reference set selector can be sorted using the properties of the sort bar. For more information on using the sort bar, see Sort Bar.
Each attribute is displayed in a column. You can find out more about the properties of these columns in Grid Columns
2.1 Common Section
For more information on properties in this section, see the Common Section section in Properties Common in the Page Editor.
2.2 Data Source Section
This selects which attribute will be used within the widget. You can only select attributes which have the correct data type(s).
For more information on selecting a data source, see the Data Source Section section in Properties Common in the Page Editor.
The attribute path specifies which attribute(s) of an associated entity is shown in the reference set selector. The path must follow one association of type reference set starting in the entity of the data view.
You cannot currently use non-persistable entities in a reference set selector.
2.3 Design Properties Section
The Design Properties allow you to change spacing and alignment of the widget and hide it on phone, tablet, or desktop, if needed.
2.4 Events Section
The on-change property specifies an action that will be executed when leaving the widget, either by using the Tab key or by clicking another widget, after the value has been changed.
For more information on properties of this section, see the Event Actions section of On Click Event & Events Section.
2.5 General Section
2.5.1 Width unit
You can decide how to define the widths of the columns in the reference set selector. The possible values are:
- Pixels – define the width in pixels
- Percentage – define the width as a percentage of the width of the reference set selector widget
2.5.2 Column Widths
The column widths are defined as either percentages or pixels. The value for the columns are separated by semi-colons. For example a narrow column and a wide column could be defined as
20;80. If the widths are defined in percentages, they have to add up to 100.
If column widths are defined as percentages, you can also change the widths of columns by dragging the separating line between columns.
2.5.3 Number of Rows
With this property you can change the number of rows that will be shown in one page. See also the property ‘Show empty rows’.
2.5.4 Show Empty Rows
If you choose to show empty rows there will always be the grid that shows the same number of rows (see ‘Number of rows’) even if there are fewer objects to show on the page.
2.5.5 Tooltip page
A tooltip page is a page that appears when you hover your mouse over a row. The tooltip page must contain a data view on the same entity as the data grid.
The tooltip will only be shown for the columns you specify. The default for each column is that the tooltip will not appear. See Grid Columns for more information.
2.5.6 Show Control Bar
This property indicates whether the control bar will be visible in the end-user interface. The control bar also includes the paging buttons. See Control Bar for more information.
Even if the control bar is invisible there can still be a default button that is triggered by (double) clicking on a row. See the property ‘Default button trigger’ and control bar for more information.
2.5.7 Show Paging Buttons
This property indicates whether the buttons to page through the information in the grid are visible or not. Only hide these buttons if you are sure that there will never be more objects than the number of rows of the grid. Note that hiding the control bar also hides the paging buttons.
2.5.8 Selection Mode
The selection mode determines whether and how the user can select items in the reference set selector.
|No selection||The user cannot select items. Of this is chosen, then you cannot have a Remove button in your reference set selector|
|Single selection (default)||The user can select a single item by clicking on it. Clicking another item will make that item the selection. Clicking a selected item will deselect it.|
|Single selection and maintain||The user can select a single item by clicking on it. The first item is always selected by default. Clicking another item will make that item the selection. Clicking a selected item will not deselect it.|
|Multi-selection||The user can select multiple items by clicking the first one and holding the Ctrl key while clicking on other items. Clicking an item without the Ctrl key will deselect all other selected items and make the clicked item the selection.|
|Simple multi-selection||The user can select multiple items by clicking on them in turn.|
2.5.9 Select first
Specifies whether the first item should be selected by default when the reference set selector is first shown.
- No (default)
2.5.10 Default Button Trigger
The default button can be triggered by a single or a double click a row.
|Single click||A single click triggers the default button. This cannot be used in combination with allowing the user to select rows.|
|Double click (default)||A double click triggers the default button.|
2.6 Selectable Objects Section
The properties in the Selectable objects section determine the objects from which the end user can make a selection.
The Source property sets the way to define the selectable objects:
- Database (default)
For more information, see the Selectable Objects Section section of Reference Selector.
You cannot use a microflow to define selectable objects in a reference set selector.
2.7 Visibility Section
Visibility determines whether a widget is displayed to the end-user as part of the page.
For more information on properties of this section, see the Visibility Section section in Properties Common in the Page Editor.