Reference Set Selector

Last modified: February 13, 2024

1 Introduction

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).

The domain model for a reference set selector between Customer (parent) and Group where the owner is 'default' (as in, the Customer refers to the Group)

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.

The domain model for a reference set selector between Customer (parent) and Group where the owner is 'both' (as in, the Customer and Group refer to each other)

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

2 Properties

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.

  1. The control bar contains the buttons needed to search, add, and remove associations. For more information see Control Bar.

  2. 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.

  3. 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.

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. Design properties may vary depending on the type of the widget. For example, for the text widget you can change its font weight, color, alignment, and letter case.

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’.

Default: 5

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.

Default: False

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.

Default: True

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.

Default: True

2.5.8 Show Paging Bar

With this property, you can change the way the paging bar is shown.

Value Description
Yes (with total count) The paging bar is shown, including the Go to last page button and the total count of objects.
Yes (without total count) The paging bar is shown (except for the Go to last page button). Also, the total count of objects is not shown, as page numbers are shown instead.
No The paging buttons are not shown.

Default: Yes (with total count)

2.5.9 Selection Mode

The selection mode determines whether and how the user can select items in the reference set selector.

Value Description
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.10 Select First

Specifies whether the first item should be selected by default when the reference set selector is first shown.

Possible values:

  • No (default)
  • Yes

2.5.11 Default Button Trigger

The default button can be triggered by a single or a double click a row.

Value Description
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)
  • XPath

For more information, see the Selectable Objects Section section of Reference 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.

3 Read More