User Guide UI

User Guide Commons Vaadin UI

Views

Views display a set of instances of an entity. The view provides the regular CRUD operations:

  • View details of an entity instance.

  • Modify an entity instance. The user can edit all properties of an object in the user interface.
    All changes are buffered in the user interface components. She can decide to propage the changes to the model or discard them through save or cancel operations.

  • Delete an entity instance.

  • Create an entity instance.

Item View

Entity View

A domain entity shall be displayed and manipulated using the entity view.

A domain entity has an internal object identifier, an external identifier, a human-readable name, a temporal period when the entity is active, and a textual description.

The entity can optionally have a set of tags and a list of comments.

public class MyEntityView extends EntityView<MyEntity> {
    static class MyEntityForm extends EntityForm<MyEntity, MyEntityView> {
        MyEntityForm(@NotNull MyEntityView parent) {
            super(parent);
        }
    }
}

The comments and the tags of an entity are modeled as an one2many immutable owned object relations.

Relationship Components

These components allow the display and handling of relations between objects.

All changes of a relation are done in the buffered values of the user interface.

Changes are only performed on the model if the save action is called. Mandatory relations are enforced with validation rules.

one2one

One2One Component

The component displays a relation from one object to another entity instance.

Referenced Object

The functions are:

  • Display the relation and show key attributes of the referenced item as a composite field. The item is a subclass of entity. The attributes of an entity are displayed

  • Remove the referenced object from the relation. The object is not deleted, only the relation to it.

  • Update the relation to a new referenced item. The user can select an instance from a set of available objects. This set of objects is provided through a provider.

The provider for selectabe instance is provided to the constructor of the one2one control.

Providers support composition with _ProviderView to define selection on the eligible instances.

Owned Object

This mode is not supported through the One2One component. Implement custom controls to display the object and to create a new one.

Custom controls cannot be defined in a generic way. Expected controls for an entity are well-defined in the framework.

One2Many Component

The component displays regular objects or instances for a subclass of entity.

The display view can support multiple selections to remove multiple referenced items from the relation at once.

The selection view can support multiple selections to add multiple items to the relation at once.

Referenced Objects

The component is One2ManyReferencesField. The functions are for referenced objects:

  • Display all objects referenced and show key attributes of the referenced items as a grid. A provided view displays selected properties in columns.

  • Remove a referenced object from the instances which are part of the relation. The object is not deleted, only the relation to it.

  • Add an existing object to the instances which are part of the relation. The user can select an instance from a set of available objects displayed in a view.

The view to display referenced objects shall be provided to the component.

The view to select objects which are added to the relation should be provided to the component. A dialog will open with the view and the cancel or add options.

An example of referenced object is an employee list of companies she is working for.

Owned Objects

The component is One2ManyOwnedField. The functions are for owned objects:

  • Display all objects referenced and show key attributes of the referenced items as a grid. A provided view displays selected properties in columns.

  • Remove a referenced object from the instances which are part of the relation. The object is removed from the relation and deleted.

  • Create an object and add it to the instances which are part of the relation.

The view to display referenced objects shall be provided to the component. The view is an item view with the create method

The provider is a shallow copy of the collection for referenced objects belonging to the relation.

Because the copy is shallow, we should not provide an update operation modifying the shared object. The object is shared between the model and the user interface buffering.

We recommend that owned objects are immutable.

Examples of owned objects are comments and tags of an entity.

Entities should generally not be handled as owned objects. An entity instance should be created through the view handling all objects of this entity type.

Reflections

One key decision is that the user interface library does not require the use of annotations, interfaces, or inheritance in the business model.

Visualized entities are manipulated under different access rights.

  • Readonly or full access

    • Readonly access allows a user to view an entity and associated properties. The update, delete and create operations are disabled.

    • Full access allows a user to view, update, create and delete an entity and associated properties.

  • Editable, immutable, or audited immutable entities

    • Immutable entities or properties support view, create and delete. The update operation is not available. We avoid support for hybrid approach such as clone a new instance and delete an old one. The semantics are often slightly awkward.

    • Audited immutable entities or properties support view, and create. Neither update nor delete operations are available to provide an audit trail. Immutable instances can be added programmatically to provide an exhaustive audit trail.