Input Reference Set Selector

Last modified: February 13, 2024

1 Introduction

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

An input 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. An input reference set selector can be used to select the groups the customer belongs to.

What you can do with an input 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 an input reference set selector between Customer (parent) and Group where the owner is 'default' (as in, the Customer refers to the Group)

You can put an input 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 an input 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 an input 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 input reference set selector, the path to the attribute to be displayed (association, related entity, and attribute) is shown inside the input reference set selector, displayed between square brackets, and colored blue.

For example, using the domain model above, the following input 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.

2 Properties

An example of input reference set selector properties is represented in the image below:

Reference set selector properties consist of the following sections:

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 Editability Section

Editability determines whether an end-user can change the value in an input widget.

For more information on properties of this section, see the Editability Section section of Properties Common in the Page Editor.

2.5 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.6 General Properties

2.6.1 Select Page

The select page property determines which page is displayed when the input reference selector is clicked. This page can be used to select associated objects from the list of selectable objects. This page should contain a data grid, template grid or list view connected to the same entity as the input reference set selector.

If an input reference set selector is never editable, a select page is not required.

See the Show a Page section of On Click Event and Events Section. Note that select pages must have a pop-up layout.

2.7 Label Section

A label describes the purpose of a widget to the end-user.

For more information on properties of this section, see the Label Section section in Properties Common in the Page Editor.

2.8 Selectable Objects Section

The properties in the Selectable objects section determine the objects from which the end user can make a selection. You can add an XPath constraint, or use a Constrained by path.

For more information, see the XPath section of Reference Selector.

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