3.2.3.1. Creating Views

You can create views as follows:

  • Programmatically – by creating a View instance. This way is appropriate for creating views that are used in the business logic.

    View instances, including nested ones, can be created by constructors:

    View view = new View(Order.class)
        .addProperty("date")
        .addProperty("amount")
        .addProperty("customer", new View(Customer.class)
            .addProperty("name")
        );

    The same can be done using ViewBuilder:

    View view = ViewBuilder.of(Order.class)
        .addAll("date", "amount", "customer.name")
        .build();

    ViewBuilder can also be used in DataManager's fluent interface:

    // explicit view builder
dataManager.load(Order.class)
        .view(viewBuilder ->
            viewBuilder.addAll("date", "amount", "customer.name"))
        .list();

// implicit view builder
dataManager.load(Order.class)
        .viewProperties("date", "amount", "customer.name")
        .list();

  • Declaratively in screens - by defining an inline view right in the screen’s XML, see an example in Declarative Creation of Data Components. This is the recommended way for loading data in Generic UI screens for projects based on CUBA 7.2+.

  • Declaratively in the shared repository – by defining a view in the views.xml file of the project. The views.xml file is deployed on the application start, created View instances are cached in ViewRepository. Further on, the required view can be retrieved in any part of the application code by a call to ViewRepository providing the entity class and the view name.

Below is an example of the XML view declaration which provides loading of all local attributes of the Order entity, associated Customer and the Items collection:

<view class="com.sample.sales.entity.Order"
      name="order-with-customer"
      extends="_local">
    <property name="customer" view="_minimal"/>
    <property name="items" view="item-in-order"/>
</view>
Working with the shared views repository

ViewRepository is a Spring bean, accessible to all application blocks. The reference to ViewRepository can be obtained using injection or through the AppBeans static methods. Use ViewRepository.getView() methods to retrieve view instances from the repository.

Three views named _local, _minimal and _base are available in the views repository for each entity by default:

  • _local contains all local entity attributes.

  • _minimal contains the attributes which are included to the name of the entity instance and specified in the @NamePattern annotation. If the @NamePattern annotation is not specified at the entity, this view does not contain any attributes.

  • _base includes all local non-system attributes and attributes defined by @NamePattern (effectively _minimal + _local).

CUBA Studio automatically creates and maintains a single views.xml file in your project. However, you can create multiple view descriptor files as follows:

  • The global module must contain the views.xml file with all view descriptors that should be globally accessible (i.e. on all application tiers) into it. This file should be registered in the cuba.viewsConfig application property of all blocks, i.e. in app.properties of the core module, web-app.properties of the web module, etc. This is what Studio does for you by default.

  • If you have a large number of shared views, you can put them in multiple files, e.g. into standard views.xml and additional foo-views.xml, bar-views.xml. Register all your files in the cuba.viewsConfig application property:

    cuba.viewsConfig = +com/company/sales/views.xml com/company/sales/foo-views.xml com/company/sales/bar-views.xml

  • If there are views which are used only in one application block, they can be defined in the similar file of this block, for example, web-views.xml, and registered in cuba.viewsConfig property of this block only.

If the repository contains a view with certain name for some entity, an attempt to deploy another view with this name for the same entity will be ignored. If you need to replace the existing view in the repository with a new one and guarantee its deployment, specify overwrite = "true" attribute for it.

It is recommended to give descriptive names to the shared views. For example, not just "browse", but "customer-browse". It simplifies the search of views in XML descriptors.