Reference Selector

Last update: Edit

1 Introduction

A reference selector is used to display and, optionally, allow the end-user to select the value of a one-to-one or one-to-many association by selecting the associated object.

A reference selector must be placed in a data widget. The object(s) retrieved by that widget must be at the many end of a one-to-many association, or at either end of a one-to-one association.

For example, if you have an employee they will work for one company. A company can have many employees. The entities Employee and Company have a one-to-many association, Employee_Company, which you can select by choosing a Company from the Employee through the reference selector.

In the reference selector, the name of the attribute of the associated objects which will be displayed is shown inside the reference selector, between square brackets, and colored blue.

For example, the following reference allows the end-user to see, and set, the association Employee_Company by selecting the CompanyName for the current Employee.

2 Properties

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

Reference 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 for Widgets.

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 for Widgets.

The attribute path specifies which attribute of an associated entity is shown in the reference selector. The path must follow one association of type reference 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.

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 for Widgets.

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

The formatting section applies only to the way that numeric attributes are displayed. These are attributes of the following data types:

  • Decimal
  • Integer
  • Long
For more information on formatting numbers, see the Numeric Formatting section of Properties Common for Widgets.

2.7 General Section

2.7.1 Select Using

The reference selector allows the end user to select objects by using either a drop-down or a pop-up page. If you choose to select using a page, the drop-down functionality will be replaced with a button to the right of the widget that will open a selection pop-up.

Value Description
Drop-down (default) Select the reference using a drop-down.
Page Select the reference using a pop-up page.
  • The advantage of selecting using a drop-down is that it is very efficient – the end-user can choose with fewer keystrokes as all the information is on the same page.
  • The advantage of selecting using a page is that the end-user can search the objects, and more information about each object can be displayed – if there are a lot of objects (say, more than 20) to select from, we suggest selecting is done using a page.

Select Using Drop-down

The drop-down reference selector is similar to a drop down for an enumeration, except that it allows users to choose from a list of objects which can be associated with the current object, rather than a list of values from an enumeration.

The reference selector displays an attribute from the objects which can be linked to the current entity via an association. The chosen attribute should be unique for each object which can be associated, otherwise the end-user will have difficulty choosing the correct one. For example, you should display a company name (which will hopefully be unique) rather than the company region (which will probably not be unique to a company).

Select Using Page

Select using a page, links a button to the right of the widget with a pop-up page which is used to make the selection. You must choose the page to be displayed using the Select Page property.

2.7.2 Empty Option Caption

This property specifies the caption for the empty option in the drop-down reference selector shown to the end-user. This is a translatable text.

Filling out the caption for an empty option improves the user experience of your application. It also helps end-users using screen-reader to operate the application easily.

2.7.3 Select Page

The select page property determines which page is opened when the select page button is used.

This page can be used to select an associated object from the list of all possible objects. This page should contain a data grid, template grid or list view connected to the same entity as the input reference set selector.

It is recommended that you generate a new page to show by right-clicking the widget and selecting Generate select page…. You can then edit the resulting page, if required.

Generate a select page by right-clicking the widget

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

Page title

You can override the title of the page you open to, for example, indicate where you are opening it from.

This is activated by checking the Override page title check box.

2.7.4 Go-To Page

The go-to page gives end users quick access to a more detailed overview of the currently selected object.

This property determines which page is shown to the user. The page should contain a data view with the data source Type set to Context and the same Entity (path) as the one that is selected by the reference selector.

It is recommended that you generate a new go-to page by right-clicking the widget and selecting Generate go-to page…. You can then edit the resulting page, if required.

Page title

You can override the title of the page you open to, for example, indicate where you are opening it from.

This is activated by checking the Override page title check box.

2.8 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 for Widgets.

2.9 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 which of the three ways to define the selectable objects is used:

  • Database (default)
  • XPath
  • Microflow

2.9.1 Database

Database is the default source for the selectable objects. By default, all database objects of the correct entity type will be selectable.

Constraints

You can limit the objects presented to the end-user by adding constraints. You will be guided through making constraints in the Edit Constraints dialog box:

Edit constraints dialog box

See the constraints section of Database Source for more information.

Sort Order

The sort order specifies the order in which the items in the reference selector are shown. You can sort on multiple attributes in both directions (ascending and descending). If (default) sort order is specified, the reference selector sorts on the displayed attribute.

2.9.2 XPath

If the source is XPath, the list of objects is also taken from the database, but the objects which are displayed are chosen by an XPath Constraint.

XPath Constraint

The XPath constraint limits the list of objects that can be selected.

For example, the XPath constraint [InStock = true()] on a reference selector for products will ensure that only products that are in stock are selectable.

See XPath Constraints for more information on XPath constraints.

Constrained By

A reference selector can be constrained by one or more paths. This is typically used to make one reference selector dependent on another. The best way to explain this is through an example.

Imagine you have an ordering system where the products are sorted into categories – for example, food products and drink products. On a page where you can edit an order line, a product selector can be constrained by a category selector. After selecting a category (food, for example), the product selector is constrained by this category and shows only products in the category.

Example Domain model

In the domain model the order line has many-to-one associations to both category and product. These associations can be be edited using reference selectors. A third association, from product to category, describes the relation between those two entities – that is, that every product has an associated category.

On the form, you have two reference selectors: one for Category and one for Product.

Without a constraint, the reference set selector will offer all the products:

List of all products, food and drink

However, because of the structure of the domain model, you can add a constraint which means that only the products of the previously selected category will be chosen. This is set by the Constrained by property.

Now the end-user will only see products in the selected category:

List of just products in the drink category

Sort Order

The sort order specifies the order in which the items in the reference selector are shown. You can sort on multiple attributes in both directions (ascending and descending). If (default) sort order is specified, the reference selector sorts on the displayed attribute.

2.9.3 Microflow

If the source microflow is selected, a microflow is called, and returns the list of objects that the reference selector will show.

Microflow

Microflow specifies the microflow which is run to return the list of objects.

Microflow Settings

In microflow settings you can specify what parameters are passed to the microflow, depending on the parameters specified in the microflow itself.

2.10 Validation Section

Here, you can specify predefined or custom validation which must be applied to the widget value before the data can be used. You can also customize the message which the end-user will get if the data does not pass the validation.

For more information on input widget validation, see the Validation section of Properties Common for Widgets.

2.11 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 for Widgets.

3 Read More