Linked entities

A linked entity field is a field referencing another entity that must be registered in the EntityRegistry. A target entity could for example be a User object, in which case the Java type of the field would also be User.

You define a linked entity field by specifying the entity name as type, prefixed with an @. The entity name is the key under which the entity is available in the EntityRegistry.

Single value field

Suppose you have the UserModule in your application. UserModule provides several entities, one of which being User.

The following employee document defines a manager field which is the User that manages the employee.

document-definition:
  name: employee
  content:
    - id: firstname
      type: string
    - id: lastname
      type: string
    - id: manager
      type: '@user'
      attributes:
        options-query: "deleted = false" (1)

1	Only show active users in the dropdown

In YAML you have to wrap the @entity type specifier in single or double quotes to ensure it is treated as a string and to avoid parsing errors.

Storage

When storing a document only a reference (usually the id) to a target entity will be saved. The referenced entity itself will be fetched when reading the document.

Visualization

Dynamic documents integrate seamlessly with EntityModule constructs.

A single value linked entity will usually be visualized as a drop-down. However when determining the actual control to render, the default entity configuration of the target entity will be taken into account. If you configured the default ViewElementMode.CONTROL for a single User to be a radio-button list, that will be used instead.

Multi-value field

You can allow multiple values of a linked entity, by appending an indexer ([]) to your field type. A multi-value linked entity by default visualizes as a checkbox group.

Example multi-value user reference (managers)

document-definition:
  name: employee
  content:
    - id: firstname
      type: string
    - id: lastname
      type: string
    - id: managers
      type: '@user[]' (1)
      attributes:
        options-query: "email like '%@google.com%' and deleted = false" (2)

1	With `@user[]`, you reference a list of user entities.
2	The checkbox group will be filtered, by using the specified query. It will only list users belonging to the google.com domain and are not deleted.