Architecture

As the UI layer is built using Vaadin Framework 8, it is component based. Everything you see on the screen is a component, possibly containing other components.

There are two types of components involved in creating the UI: Basic UI components and Application components.

Basic UI components are the components shipped with Vaadin Framework itself or included as add-ons. This includes components such as Button where you mainly listen for events from the user, layout components like Board and user input components such as TextField. The basic UI components are general purpose and can be used in all applications as they are not tied in any way to the application logic.

Application components are components created inside the application itself. An application component differs from a basic UI component in the way that it knows about the application and how the application should work. In many cases you do not think about that you create application components, but in practice all views in your application are components, parts of the views are typically extracted to application components and so on.

In this app starter, there are many application components used. In addition to the main layout and all views, there are smaller components like OrdersGrid and RoleSelect.

Both OrdersGrid and RoleSelect are standalone components which knows how to show certain data to the user. OrdersGrid is the grid used on the Dashboard and the Storefront views, capable of showing the orders which are due today and in the future. RoleSelect is a drop down which shows the available roles in the application. They both connect to the service layer when they need some data and present it to the user in a suitable way.

Some application components are very simple, like RoleSelect. They can be implemented using a few lines of code and naturally fit into one class. Trying to split a component like this into multiple parts would only include complexity and go against the guiding principles for the achitecture.

Some application components on the other hand are very complex. At least views with much functionality tend to fall into this category. To be able to deal with the complexity, the implementation should be split into multiple parts, each with a clear responsibility. This can be done in different ways but in this app starter the first split is done into layout and logic using Vaadin Designer for the layouts.

Vaadin Designer naturally splits out all the layout configuration into the Design HTML file and creates an auto generated companion Java file so the components used in the layout can be accessed from Java. The logic (event listeners, service layer calls etc) is then added to a separate Java file, which typically extends the generated class so it can access the components in the layout.

For some application components, the split between layout and logic is not enough to deal with the complexity. There are a couple of cases in this app starter when this split just did not make the code readable and understandable. The view where you create/edit an order and the CRUD views for users and products will still be hard to read when you have split out the layout code as there is simply quite much logic code. In these cases, the MVP pattern (or a variant thereof) has been utilized so that pure business logic goes into a presenter class and UI related logic goes into a view class (there is no model class as the model is so simple in all the cases).

In the cases the MVP pattern is utilized, the view decides which components to use and how to lay them out (the Design file is considered as part of the view). The view also wires event listeners, configures how fields are bound and what validators to use in the UI (validators are UI level helpers, the real data validation takes place in the service layer).

The presenter is the one aware of the service layer (view is not), deals with what should happen on view events and also handles navigation to/from views.

Application components are built to be standalone and reusable in multiple places. To avoid coupling them to other application components, they provide an API which can be used to configure them and/or they fire events to indicate that something has happened which might be of interest to other components.

References to other components are acquired by utilizing dependency injection. Many components exist only in one place in the view and are then using @ViewScope (only one instance is created per view). These can be injected into any other component in the view without accidentally creating multiple instances. After injection, the component API can be used to e.g. add an event listener.

Some components can appear multiple times on a view, like the ProductInfo component which encapsulates the information about one product in an order (product name, quantity, details) and provides controls for modifying and removing the product. The ProductInfo component is set to prototype scope so that a new instance is created whenever it is injected. We can therefore not inject references into other components the same way as for components using @ViewScope. To get events from the ProductInfo components, a view scoped event bus is used. The ProductInfo component fires an event whenever some information inside it changed and every other component in the view can listen to any event it is interested in. In this case OrderEditPresenter listens for `ProductInfoChangeEvent`s and reacts to them by recalculating the new total price for the order.