Reference Set Selector

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

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

Properties

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

Reference set selector properties consist of the following sections:

• Common
• Data source
• Design Properties
• Events
• General
• Selectable Objects
• Visibility

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

Common Section

Data Source Section

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.

Design Properties Section

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.

General Section

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

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.

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

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

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.

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

Show Paging Bar

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

Default: Yes (with total count)

Selection Mode

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

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

Default Button Trigger

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

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.

Visibility Section

Read More

• Data view
• Entities
• Associations
• Control Bar