Table of Contents

Entity view properties

The property will be defined to indicate whether the entity property is exposed.

The source is used to link the entity view property to the entity property. If the source is not populated, the property will be considered as unbound.

By default, the properties of the entity view property will inherit those of the entity property but some can be redefined.

Type of entity view property

Like an entity property, an entity view property can be a scalar property or a navigation property (reference property or collection property).

Scalar properties

Scalar properties can be standard properties or expressions.

On standard properties, the source is an entity property name or null. The source is automatically updated when the entity view property is updated (two way binding).

Expressions can only be used when the entity view is bound to an entity. On this type of property, the source is a C# expression based on the entity (one way binding). The entity is accessible in the expression with the variable e. Examples:

  • e.LastName
  • string.Concat(e.LastName, ' ', e.FirstName)
  • e.LastName.ToUpper()
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.

If the source is a navigation property, it is necessary to define in Related EntityView Name property an entity view. The property will be used to determine the child properties exposed by the relationship. This related entity view must belong to the entity of the navigation property.

Note

What are the objectives?

  • Avoiding to make multiple API calls (e.g.: retrieving an order and its detail)
  • Performing a single transaction and avoid inconsistent updates
  • Adding validation rules or server event rules based on the complete object (e.g.: 2 order lines with the same product are forbidden)

Attributes

Filtering

Basic filtering

To allow filtering on properties, you need to enable the Filterable property on each entity view property.

If a UI view has a filter-bar component in its template, the user will then be able to filter the results by the configured properties.

The Filterable property also enables server-side sorting: a UI view column bound to this property can be sorted server-side only when Filterable is enabled and it targets a single scalar value (not a collection, nor a property where any parent element is originating from a collection). When a sortable bound column does not meet these conditions, generation logs M0077 (UIViewPropertySortableRequiresFilterableEntityViewProperty) and the column is generated as non-sortable. To still allow sorting in that case, either make the source property Filterable, or redirect the column's sort to another (filterable) property in code (see the UI view sort property).

Note

The M0077 message is Information by default and Warning in newly created clusters (configurable via GenerationLogLevels).

If you want to filter the result by several properties but with only one input, you can enable the Quick search property on each property you want to filter on.

If the property is a reference, the quick search will recursively apply on scalar properties with quick search of the referenced entity view. If the property is a scalar value and a lookup is defined, the quick search will apply on the "display value" of the lookup.

You can also configure the Quick search filter operator on each property to control how the entered text is matched. The default value is Contains. Supported values are:

  • Contains: the property matches when it contains the entered text.
  • StartsWith: the property matches when it starts with the entered text.
  • Equal: the property matches only when it is equal to the entered text.

If a UI view has a quick-search component in its template, the user will then be able to filter on each configured properties by typing only in the quick search input field.

Example : A CustomerView entity view has the following properties :

  • Code configured as filterable with quick search
  • Name configured as filterable with quick search
  • Country only configured as filterable

If a UI view based on the CustomerView entity view has a quick search input in its template, when the user type in the input field, the results will be all customers for which Code property contains the user input or Name property contains the user input.

Filtering or quick search on nested properties of collection or reference

When an entity view exposes a reference or a collection, you can let the user filter (or quick-search) the root list on a property located further down the graph. You do this by declaring a UI view property whose name is a dotted path to that property.

For example, on an order list you can filter on the product name of the order lines (OrderDetails.Product.ProductName), or even on a value buried several collections deep, such as a note on an order line (OrderDetails.Notes.Note).

What you can traverse

A filter path is a sequence of navigation steps ending on a scalar property:

  • References (1-to-1 navigation) can be chained freely.
  • Collections (1-to-many navigation) can also be traversed. Each collection in the path is turned into a sub-query (an any(...) clause in OData, a correlated EXISTS in SQL).

A path that crosses at least one collection is filter-only: the property can be used in the filter bar and quick search, but it is not displayable as a grid column (there is no single value to show per row). A path made only of references stays both filterable and displayable.

Note

A filter path may traverse up to 5 nested collections. Beyond that, the property is rejected during code generation (neos generate logs an error and the property is not generated as filterable). Only collections count toward this limit; references do not.

How to declare it
  1. On the entity view, expose the navigation properties of the path. A collection that only serves filtering should be declared as filter-only so it is never loaded on GET:
# In the root list entity view (e.g. NPFOrderListView)
- Name: OrderDetails
  Caption: OrderDetails
  ExposedInGet: false
  LoadedOnGet: false
  QuickSearch: true
  RelatedEntityViewName: NPFOrderDetailListView
  Source: OrderDetails
  Type: Collection

The related entity views along the path expose the next step (OrderDetails → Notes → Note), each with QuickSearch: true if you want quick search to reach it.

  1. On the UI view, declare the filter as a property whose Name is the dotted path:
# In the list UI view (e.g. NPFOrderListUI)
- Name: OrderDetails.Notes.Note
  Caption: Order detail note
  Displayable: false
  FilterVisible: true
  FilterPosition: 4

Add a filter-bar (and/or quick-search) component to the UI view template so the user can use it.

Technical demos

There is a working example in technical demos: Nested property filter/Orders (see Technical Demos to run it in development mode).

Open the properties of the UI view NPFOrderListUI:

  • Customer.CustomerName : filterable and displayable — CustomerName is reached through a reference only.
  • Customer.Addresses.FullAddress : filter-only — the path crosses the Addresses collection.
  • OrderDetails.Product.ProductName : filter-only — the path crosses the OrderDetails collection.
  • OrderDetails.Notes.Note : filter-only — the path crosses two collections (OrderDetails, then Notes).
Filter efficiently
  • Keep filter-only collections out of GET. Set ExposedInGet: false and LoadedOnGet: false on collections used only for filtering, so they are never fetched when the list is read — they only contribute a sub-query when the corresponding filter is active.
  • Index the database. Each traversed collection becomes a correlated EXISTS (a semi-join: the database stops at the first matching child and never multiplies the result rows). Make sure the foreign keys of the sub-collections and the filtered columns are indexed.
  • Mind the depth. Every collection adds one nested sub-query, so prefer the shortest path that expresses the need and stay well within the 5-collection bound.
  • References are cheap. A path made only of references translates to simple joins and keeps the property displayable.

Character casing

The character casing of the property applied to the string content. By default, this value is inherited from the entity property.

To find out more about the character casing, please visit this article.

White space handling

The white space handling of the property applies to strings and localizable strings. By default, this value is inherited from the entity property.

To find out more about the white space handling, please visit this article.

Multiline

For String and LocalizableString properties, entity view properties inherit the Multiline behavior from their source entity properties by default.

When Multiline = false, backend validation rejects values containing line breaks (\r, \n). This backend control is new in Neos 3.0. This validation can be temporarily disabled with TextValidation:EnforceMultiLineConstraint in backend configuration.

Neos also validates consistency between an entity view property and its source entity property:

  • If an entity view property is marked as multiline while its source entity property is not, generation logs warning M0068 (PropertyCannotBeMultilineBecauseSourceIsNot).
Important

Treat this warning as actionable technical debt, not as an informational message. Keeping this mismatch can lead to inconsistent behavior between metadata, generated UI, and backend validation.

To find out more, see entity properties and backend application configuration.