Views and Menu Items

Dynamic Model can generate UI views for dynamic entities and add the corresponding menu items, so that a runtime-defined entity becomes immediately usable in the application’s UI without writing any Java or XML. It can also override existing views of static entities, which is the way to display dynamic attributes that you have added to those entities.

Views are declared per entity in the model, under the entity’s views list. See YAML Reference for the full list of view fields, and Defining the Model for how the data model itself is defined.

Views for Dynamic Entities

A dynamic entity has no views of its own until you declare them. To make it visible and editable in the UI, add at least a list view, a detail view, or both. Each view has a type of either list or detail, and from these declarations the framework generates the UI views automatically — no descriptor XML is required.

The example below declares a list view for the LoyaltyLevel dynamic entity. The surrounding model also declares a detail view for the same entity, so the entity can be both browsed and edited:

views:
  - type: "list"
    viewId: "LoyaltyLevel.list"
    viewRoute: "loyalty-levels"
    viewTitle:
      en: "Loyalty levels"
      de: "Treuestufen"
    templateParams:
      includeProperties: ["name", "discount"]
      excludeProperties: ["publicSummary"]
    resourceRoles:
      - "employee"
      - "manager"
    menuItem:
      parentMenu: "application"
      insertBefore: "Customer.list"
      title:
        en: "Loyalty levels"
      resourceRoles:
        - "employee"
        - "manager"
    descriptor:
      template: "default"

The descriptor of a dynamic entity view controls how its layout is produced. It can take one of the following forms:

  • Omitted, or template: "default" — the framework builds the view from its built-in default template, which produces a standard list (a data grid with the usual actions) or detail (an editor form) layout. Omitting the descriptor has the same effect as specifying the default template.

  • template: "<resource path>" — the view is rendered from a custom view template resource instead of the default one.

  • source: "<XML>" — you supply the view XML directly. This gives you full control over the layout, the same as writing a regular view descriptor by hand.

Supplying the descriptor as literal XML is the way to define an arbitrary layout that the default template cannot express — for example, custom components, grouping, or additional actions. The XML must be a valid UI view descriptor; a list view descriptor must contain the lookup component (dataGrid by default) and a detail view descriptor must contain the edited entity container (entityDc by default). See the views reference for the exact rules and defaults.

A view declaration for a dynamic entity can also place the view in the application menu by adding a menuItem object. When the model is applied, the menu item appears alongside the generated view. The menuItem in the snippet above demonstrates the typical fields:

  • parentMenu — the ID of the parent menu under which the item is placed. If no menu with this ID exists, a new root menu is created with it.

  • insertBefore — an optional sibling menu item ID; when present, the new item is inserted before that sibling, otherwise it is appended.

  • title — the menu item caption, as a localized value. When omitted, the view title is used.

  • resourceRoles — the role codes whose holders can see and use the menu item.

Overriding Static Entity Views

Adding a dynamic attribute to a static entity does not automatically place it on that entity’s existing views. To display a dynamic attribute on a view that already exists in your application, override that view’s descriptor from the model.

A static entity view declaration references the registered view through viewId and supplies a descriptor.source containing XML that extends the original descriptor. In the XML you add only the components you need — for example, a column for the new dynamic attribute. The example below extends the application’s Customer.list view and adds a taxId column to its customersDataGrid:

- viewId: "Customer.list"
  descriptor:
    source: |
      <?xml version="1.0" encoding="UTF-8" standalone="no"?>
      <view xmlns="http://jmix.io/schema/flowui/view"
            extends="com/company/sample/view/customer/customer-list-view.xml">
          <layout>
              <dataGrid id="customersDataGrid">
                  <columns>
                      <column property="taxId"/>
                  </columns>
              </dataGrid>
          </layout>
      </view>

For static entity view overrides, only descriptor.source is supported — the template, route, title, and menu fields used for dynamic entity views are not allowed here. The override changes only the view’s descriptor: the generated controller subclasses the existing one, so the original route and the view’s existing behavior are preserved.