References frequently asked questions

Display a property of a reference

Add the reference to the entity view

In order to access the properties of a reference in a UI view, it is necessary to add the reference property to the entity view.

To do this, add a new property in the entity view and feed the Source field with the name of the reference on the entity. The Related EntityView Name property is used to indicate the entity view that will be used to expose the data of the referenced entity. This entity view must be related to the referenced entity and its properties will be available for display.

OrderView \ Properties

Name = Customer
Source = Customer
Caption = Customer
Related EntityView Name = CustomerView

Add the property of the reference to a UI view

Now that the reference is available in the entity view, you can use it to access to the properties of the related entity view defined in the previous step.

In the UI view, you can had a new property with a name in the following format ReferenceName.PropertyName.

If you go back to the order UI, you can now display the name of the customer by adding the following property :

OrderUI \ Properties


Name = Customer.ContactName
Caption = Customer name

Display the property in a data grid

To display this new property in a data grid, you need to update its grid options. First, check the Visible property and then set the Position property of the column.

OrderUI \ Properties

Name = Customer.ContactName
Caption = Customer name
Grid options \ Visible = true
Grid options \ Position = 3

Display the property in a form field

As with any other property, the property name is used to map the form field to the property.

OrderUI \ Template

<form-field property-name="Customer" />               <!-- The field of the Customer reference with its lookup -->
<form-field property-name="Customer.ContactName" />   <!-- The field of the Customer's name-->

When the user changes the customer of the order, the second form field will be updated with the name of the selected customer.

Editing a property of a reference

In order to modify a property of a reference, it is necessary to set Editable properties to true on the reference of the entity view.

Important

UI views: Only required references can have editable properties. A generation error will occur if a UI view uses an entity view containing an optional reference with editable properties.

API only: Optional references with editable properties are supported for API-only scenarios (e.g., data import, integrations). See Optional editable references (API only).

On the UI view, to use editable properties, you need to add a subview on the editable reference.
You also need to add reference in properties (for example, if you want to use lookup on the reference)

On creation, a new record of the reference is automatically created.

Example :

On sales order, you want to modify the customer associated.

In OrderView :

you set Editable Properties to true on OrderView.Customer.

In OrderUI :

Add sub view Customer associated to CustomerUI.
Add UI view property Party (from entity view properties).

...
<form-field property-name="Customer" /> <!-- use property -->
<ui-view relation-property-name ="Customer" /> <!-- use sub view -->
...

How to load a reference only when it becomes visible

Since Neos 2.4, you can disable the automatic loading of a non-embedded reference and manually trigger the loading at the desired time.
By default, auto-loading occurs when the active row changes or when the data is loaded/refreshed.

To disable auto-loading, simply uncheck the Auto load option on the subview corresponding to the reference.
To load the data manually, call:

await SubViews.[SubViewName].EnsureDataLoadedAsync();

This call can be placed, for example, in the code of an action that displays the reference, or in the setter of a Computed bound to the selected-index of a tabs component.

Refer to the TechnicalDemos cluster menu entry:
Sub UI views > References > Subview on non auto loaded reference for an example.

Table of Contents