ReferenceRetrieving

Allows you to control the data offered and the value entered for the lookup component.

The rule can, for example, filter the values a user can select in a lookup.

The event rule is executed by filter bar lookups. This is why Item is nullable.

Arguments

The Arguments property provides the following options.

Name	Type	Description
Item	The type of the UI view model	This is the instance of the current item.
Filter	filter	Indicates the filter(s) to apply
Sorts	sort[]	Indicates the sort(s) to apply
InputValue	string?	Indicates the current edit value in the Lookup component even if it is not a valid value
EntityViewParameters	EntityViewParameters	Indicates the parameter value(s) to apply
Trigger	ReferenceRetrievingTrigger (LookupSuggestions, LookupUIView, LookupValidation, TrySet)	Indicates the trigger of the rule (e.g. to add a filter only in the lookup suggestions, not in the lookup modal.)

How to add a filter

The filter applied to the API call of the reference's entity view is accessible through the Arguments.Filter property.

Example of a ReferenceRetrieving rule

A UI view contains a lookup for choosing a car brand and a second one for choosing the car model. The following code shows how to filter the data of the second lookup after the user selects a brand.

if (Item != null && Item.Brand != null)
{    
    Arguments.Filter.Add(new Filter("Brand", FilterOperator.Equal, Item.Brand));
}

Warning

This rule should only be used to filter the proposed records depending on other values selected in the UI. If you need to filter data based on the context of the application (for example hiding clients that are not linked to the company of the user), you must do so on the server side.

How to add a filter only in the lookup suggestions dropdown

The ReferenceRetrieving rule is calling when:

• loading data in the lookup suggestions dropdown (LookupSuggestions)
• loading data in the lookup modal UI view (LookupUIView)
• validating lookup value (LookupValidation)
• setting a lookup value from code with a TrySet...Async method (TrySet)

With the Trigger property of the arguments, you can know what triggered the rule and thus perform a specific action, such as adding a filter only in a certain case.

The following code reuses the previous example but only adds the filter when loading the dropdown suggestions data for the lookup.

if (Arguments.Trigger == ReferenceRetrievingTrigger.LookupSuggestions && Item != null && Item.Brand != null)
{    
    Arguments.Filter.Add(new Filter("Brand", FilterOperator.Equal, Item.Brand));
}

Item versus DatasourceCurrent

To know more on the difference between the Item and DatasourceCurrent properties in an UI view event rule, you can check this article.