Table of Contents

Use entity view parameters

What is an entity view parameter and when to use it ?

The data returned by entity views is based on the filter provided ($filter parameter in the API query). While often simple, it can sometimes become a very complex mix of and and or conditions and function calls. This filter is automatically applied to the items you set as the data source when calling args.SetItemSource, but you cannot read it. If you need to access specific criteria in the Retrieving event, the filter is not the solution and you should consider using parameters.

Entity view parameters are additional parameters for the entity view methods that return an element (GetAsync and FindAsync) or a list of elements (GetListAsync, GetListByKeysAsync and GetPagedListAsync). Actually, during an API call, parameters can only be used on GET method calls returning a list of elements. The GET method taking a key as parameter does not accept parameters.

Note

With database persistence, the expression is evaluated by EF Core. For the filter to work property, it must be completely transpilable in SQL code.

The most common use case for them is when an entity view is not linked to an entity. In this case, the data must manually be loaded in the Retrieving event. In this scenario, using parameters is the simplest way to filter the data.

Where and how to use the parameters?

Entity view parameters can be created in the Parameters tab of an entity view.
They can be used in the entity view Retrieving event rule if the event is not triggered by key access.

The value of a parameter can be obtained using the TryGetParameterValue method:

if (args.Key == null && args.Parameters.TryGetParameterValue("StringParam1", out object? stringParam1))
{
    ...
}

It can also be obtained using the provided typed extension methods:

string stringParam1 = args.Parameters.GetStringParam1();

How to pass the parameters?

By directly accessing the repository

The GetAsync, FindAsync, GetListAsync, GetListByKeysAsync and GetPagedListAsync methods each have a signature containing a parameters parameter:

Task<TEntityView> GetAsync(
  object key,
  EntityViewParameters<TEntityView> parameters)

Task<TEntityView?> FindAsync(
  object key,
  EntityViewParameters<TEntityView> parameters);

Task<IReadOnlyList<TEntityView>> GetListAsync(
  EntityViewParameters<TEntityView> parameters,
  Func<IQueryable<TEntityView>, IQueryable<TEntityView>>? queryCustomization = null)

Task<IReadOnlyList<TEntityView>> GetListByKeysAsync(
  EntityViewParameters<TEntityView> parameters,
  object[] keys);

Task<IPagedList<TEntityView>> GetPagedListAsync(
  int skip,
  int top,
  EntityViewParameters<TEntityView> parameters,
  Func<IQueryable<TEntityView>, IQueryable<TEntityView>>? queryCustomization = null)

Example:

// An implicit operator automatically casts dictionaries to EntityViewParameters<TEntityView>
var items = await repository.GetListAsync(new Dictionary<string, object?>()
{
  ["StringParam1"] = "ParameterValue",
});

The code can also be simplified by using the provided typed parameter class:

var items = await repository.GetListAsync(new MyEntityViewParameters(stringParam1: "ParameterValue"));

By calling the API

Entity view parameters can directly be passed in an API query string:

https://localhost/neos/Northwind/webapi/MyEntityView?top=50&skip=0&stringParam1=ParameterValue
Warning

They can only be used in the GET api returning a list of elements.

In a UI view

The EntityViewParameters property is available in the UI view code. It exposes a typed property for each parameter defined on the entity view the UI view is linked to.

Example:

EntityViewParameters.StringParam1.Value = "ParameterValue";

In a lookup

Currently, the value of the parameters of the entity view associated with a lookup can only be set in the ReferenceRetrieving event of a UI view.

Example:

Arguments.EntityViewParameters.SetParameterValue("StringParam1", "ParameterValue");

How to persist a parameter in custom views?

In the Initialized event rule of the UI view, you can set the following property to persist an entity view parameter in the custom views:

EntityViewParameters.StringParam1.SaveInCustomView = true;

How to display a parameter in filter bar?

In the Initialized event rule of the UI view, you can set the following property to display an entity view parameter in the filter bar:

EntityViewParameters.StringParam1.Filterable = true;

You can also customize the icon shown on the filter chip:

EntityViewParameters.StringParam1.Filterable = true;
EntityViewParameters.StringParam1.FilterIcon = Images.DarkTheme;

If FilterIcon is not set, the framework falls back to the default icon for the parameter data type.

Note

FilterIcon changes the icon displayed on the chip. To change the chip size, configure the filter bar with display-mode="editable-chips" and the size attribute.

How to edit a date range in a single chip?

To edit two date parameters as a single filter chip, link the first parameter to the second one with FilterValue2Parameter:

EntityViewParameters.PeriodStart.Filterable = true;
EntityViewParameters.PeriodStart.FilterValue2Parameter = EntityViewParameters.PeriodEnd;
EntityViewParameters.PeriodStart.FilterComponent = FilterComponent.CalendarMonth;
EntityViewParameters.PeriodEnd.Filterable = false;

With this configuration, the filter bar and the advanced filter treat PeriodStart and PeriodEnd as a single date range:

  • the operator is forced to between,
  • both values are edited together,
  • only the first parameter needs to be exposed as a filter chip.

When the filter component returns a month or a year for a Date parameter, Neos automatically converts the selected value into the corresponding range boundaries before sending the parameters to the server.

There are a few specific features related to UI view properties :

  • For a standalone parameter, the filter operator cannot be changed by the user. By default, it is equal to. However, it is possible to modify it using code (via the FilterDefaultOperator property) to give the user an indication of what will be done on the server side.
  • If FilterValue2Parameter links two Date parameters, the operator is automatically set to between.
  • In advanced filter, conditions on filterable parameters are displayed first in the root group and cannot be hidden. The logical operator of the root group is forced to AND since you cannot use OR with entity view parameters. When FilterValue2Parameter is used, only the first parameter is displayed and the linked second parameter is edited through the same condition.

Can I remove the $filter parameter from the API?

When an entity view is not linked to an entity, using the filter provided to the entity view may not be necessary. In this case, exposing this parameter in the API is useless.
If you turn off the Filterable attribute on each entity view property, the $filter parameter will automatically disappear.
In the current version, when filtering is disabled, sorting is also disabled and the $orderby parameter also disappears.