Holon Platform Vaadin Flow Module - Reference manual

By default, the Holon Platform Property model is used to represent the backend data model attributes, and the PropertyBox type to represent a data source item, intended as a collection of properties and their values.

So, besides the Datastore reference and the DataTarget definition, the property set to use has to be provided to the DatastoreDataProvider builder methods.

Furthermore, the DatastoreDataProvider API provides methods to use a bean class as item type. The item property set is obtained form the bean class attributes, using the bean property names as property set property names.

By default, the QueryFilter type is used used as data provider filter type, since it is the default property model representation for the Datastore API query restrictions definition.

To use a different data provider filter type, a filter converter function can be configured for the DatastoreDataProvider, to provide the custom filter type to QueryFilter type conversion logic.

In the example below, a String type filter is used and the conversion function creates a QueryFilter which represents the condition "The NAME data model attribute value starts with the given filter value":

Similarly when a bean item type is used:

The DatastoreDataProvider API makes also available methods to customize both the item type and the data provider filter type, providing:

For example, using a MyItem item class and a String filter type:

The queries performed by the Datastore to fetch the data from backend can be configured using the DatastoreDataProvider builder API.

The Holon Platform Vaadin Flow module builder APIs provides covenient methods to setup a Datastore based data provider for UI components which support data binding.

Example for a single select, implemented using a Vaadin ComboBox component:

See Component builders and providers to learn about the available component builders.

The Holon Platform internationalization support relies on the LocalizationContext API, which acts as message resolver, localized data formatter and holder for the current user Locale.

In order for the UI components localization to work, one of the following conditions must be met:

The LocalizationProvider API is used by the UI components and builders to obtain the localization information and to localize the messages to display.

The LocalizationProvider API makes available a set of static methods to seamlessy integrate the messages localization in any part of the application, delegating the actual internationalization logic to the concrete localization provider, if available, which can be either a Holon Platform LocalizationContext or a Vaadin Flow I18NProvider.

The actual localization service to use is automatically detected with the following strategy:

This way, the LocalizationProvider API getLocalization static methods can be used as follows:

If the Locale is not explicitly provided, the LocalizationProvider API localize static methods can be used and the current Locale is obtained with the following strategy:

The Holon Platform LocalizationContext can be used as a standard Vaadin Flow I18NProvider through the LocalizationContextI18NProvider API.

The LocalizationContextI18NProvider provides static methods to build a I18NProvider instance which uses a LocalizationContext as message localizations provider.

A LocalizationContextI18NProvider which uses the current LocalizationContext (if available as a context resource) can be obtained with the create() method:

Each component builder API is composed by a set of specific builders, each related to a specific feature of the component. The feature builders are independent from the specific UI component to build, thus providing a common API which makes component configuration simple and intuitive.

For example, the HasTextConfigurator represents a builder part for UI components which supports a text, and it is included in any builder for UI components with text support.

Similarly, the the HasSizeConfigurator API is included in component builders which supports the component size configuration.

This ensures a consistent and common API to build and configure any UI component.

In the example below, the HasTextConfigurator and the HasSizeConfigurator are used in the same way to configure a label and a button component text and size:

Besides the builders, the Components API provides a set of configurator methods, which can be used to configure existing UI components. The available configurators acts on some base UI components: label, Button and layouts.

A message dialog is a Dialog which can be used to display a simple message to the user.

A confirm dialog is a Dialog which can be used to display a simple message to the user and provides a OK button at the bottom right position.

The OK button can be configured using the dialog builder.

A question dialog is a Dialog which can be used to ask a question to the user and handle the user answer. A QuestionDialogCallback function must be provided to handle the user answer.

Two buttons are displayed at the bottom right position, which by default represents the yes or no answers. The buttons can be configured using the dialog builder.

All the dialog builders provides a set of common Dialog configuration options, including:

The dialog builders allow to add custom components to the Dialog content. The components can be added in two positions:

The PropertyListing API is the default ItemListing implementation which uses the Holon Platform Property model to represent and manage the data items.

For example, given the following property model definition:

A PropertyListing can be created in the following way:

The BeanListing API is the default ItemListing implementation to use a Java Bean class as item type.

For example, given the following bean class definition:

A BeanListing can be created in the following way:

To obtain the item set to display, an item listing needs a data source to be configured. This can be achieved either using the items(…​) or the datasource(…​) builder methods, to provide a static set of items or a backend data connection respectively.

1. Using a static set of items:

The item listing item set can be provided at listing costruction time, using the items(…​) or addItem(…​) builder methods. The provided item instances must be of the same type of the listing item type.

The provided item will be displayed in the same order they are provided at construction time.

Example using a PropertyListing:

Example using a BeanListing:

2. Using a DataProvider:

A Vaadin com.vaadin.flow.data.provider.DataProvider can be used as items data source. This allows to provide a dynamic set of items, for example using a backend service.

The DataProvider data type must be consistent with the listing item type.

Example using a PropertyListing:

Example using a BeanListing:

When a DataProvider is used as data source, the refresh() and refreshItem(T item) can be used to refresh the listing item set:

The Holon Platform Datastore API can be used to implement a listing data source, and maybe it is the most straight and easy way to connect a property model based listing to a backend data source.

This first way to use a Datastore as listing data source is to use the DataProvider adapter, available through the DatastoreDataProvider API.

See the Datastore API integration section to learn how to create and configure a Datastore based DataProvider.

When a Datastore is used, a DataTarget definition is required to declare the data model entity to use as items data source (for example a RDBMS table name, or a collection name in a document based database).

Supposing to use the following DataTarget definition:

A PropertyListing data source can be declared as follows:

But the most straight and easy way to use a Datastore as listing data source is to rely on the listing builder methods available for this purpose. Furthermore, the builder methods allow to avoid to specify the query projection property set again, using the listing property set by default.

The dataSource builder method turns the root listing builder in a Datastore-aware builder, making available a set of additional methods which can be used to configure the Datastore based data provider, for example to add query filters and sorts. The Datastore based data provider configuration methods corresponds to the ones provided by the DatastoreDataProvider API. See Datastore Query configuration for details.

The item listing data source can be set in a frozen state using the item listing API:

The frozen state can be useful when you don’t want to fetch the items just after the listing is displayed in UI, maybe because it involves an onerous backend query. The backend query is only performed when the refresh() method is called, typically by a user explicit action.

The item listing frozen state can be configured either from the buider API or from the ItemListing API:

The ItemListing API supports additional data source items. Additional items can be added using the ItemListing API and they will appear as conventional listing items, even they are not part of the items returned by the concrete data source.

Additional items can be used, for example, to allow the user to add an item to the listing, edit its data and then saving the item in the concrete datastore. At this point, the additional item can be removed, since the saved item will now be returned by the data source query.

The ItemListing API provides method to manage additional items: add an additional item, remove an additional item, remove all additional items and obtain the current additional items.

The item listing builders provides a set of methods to configure the item listing component, most of them coming from the Vaadin Grid component configuration options.

This includes for example setting the page size, setting whether the listing column are resizable and can be reordered, setting the frozen columns and so on.

One ore more item click listener can be added to the listing to handle user clicks on the listing rows. The click event provides the clicked item instance and a reference to the listing on which the click occurred.

Furthermore, a set of additional click information are provided, such as the click count, the modifier keys, the screen coordinates and so on.

The item listing columns are auto-generated by default using the provided listing property set.

If an explicit column renderer is not configured for a column, the default column value rendering strategy uses the Holon Platform StringValuePresenter API to render a column value.

This ensures a consistent behaviour across the application on how the values are displayed and the current LocalizationContext is used, if available, to apply the proper internationalization conventions to format, for example, a numeric value.

See the StringValuePresenter API documentation for details.

Furthermore, for a PropertyListing implementation, the PropertyValuePresenter architecture is used to render the column value, allowing to extend and tune the presentation strategy at higher level, ensuring consistency across the application UI and backend.

See the Property value presentation documentation for details.

For example, suppose we want to add a # prefix to each value of the ID property. We can declare a PropertyValuePresenter and bind it to the ID property in the property presenters registry:

From now on, any PropertyListing instance will use the new presenter to render the ID property column value.

The PropertyListing builder makes available helper methods to render a column using a Component, providing the function to use to obtain the Component instance for each cell, given the current row PropertyBox item.

A PropertyListing column can be rendered using a ViewComponent, leveraging the ViewComponent rendering architecture and thus providing a consistent data rendering strategy across all the application UI components.

See View components and forms for information about ViewComponent purpose and configuration.

The item listing supports a context menu, which can be added to the listing and will open by default when a right click or a long tap is performed by the user on a listing row.

The item listing context menu builder provides a set of methods to:

The item listing supports row details components, which can be opened and closed under each listing row.

To enable the item row details, a function which provides the details content for each row has to be provided. For each row, the listing row item instance is provided as function argument.

The item details contents can be rendered in two ways:

By default, the item details are shown/hidden for each listing row when the user clicks on a row. This behaviour can be disabled using the itemDetailsVisibleOnClick builder method.

In this case, the item details content should be opened or closed programmatically. For this purpose, the setItemDetailsVisible method of the item listing API can be use to show or hide the item details for a specific item.

The item listing header and footer sections can be completely customized, setting the cells contents and joining two or more cells together.

The header and footer sections handlers can be obtainer either using:

The item listing supports both single and multiple row selection modes. When the listing is in multiple selection mode, a checkbox is shown before each listing row to allow user selection. Additionaly, a select all checkbox is available in the listing header first cell.

The item listing selection mode can be enabled either using:

A SelectionListener can be added to the item listing in order to listen to item selection events and obtain the currently selected items.

Furthermore, the item listing API provides a set of methods to select or deselect one or more items programmatically.

The item listing supports an edit mode, which can be enabled using the editable() builder method.

When a listing is editable, a row can be setted in edit mode using the editItem(T item) method of the item listing API. When editItem is called, each cell content is replaced by an input component to allow to change the item property value which corresponds to each column.

The updated row item values can be saved using the saveEditingItem() method of the item listing API, or discarded using the cancelEditing() method. Then the row editor is closed, restoring the default cell contents.

A set of listeners can be added to the listing to control the editing process:

The component to use as input to edit each item property value can be customized using the editorComponent(…​) builder method.

The row editor provides a buffered mode: when enabled, the edited values are setted into the item instance only when the saveEditingItem() method is called, for example using a provided save button. The editorBuffered builder method can be used to enable or disable the buffered mode.

A ViewComponent converts the value it holds to a String in order to display it in UI. For value conversion and formatting the ViewComponent API relies on the Holon Platform StringValuePresenter API.

This ensures a consistent behaviour across the application on how the values are displayed and the current LocalizationContext is used, if available, to apply the proper internationalization conventions to format, for example, a numeric value.

See the StringValuePresenter API documentation for details.

To provide a custom value conversion logic, a value conversion function can be provided at ViewComponent build time:

When a Property value has to be displayed, a ViewComponent can be created and bound to the Property definition, inheriting the property value type as component type and enabling the PropertyValuePresenter based strategy to convert and format the value in a consistent way across the application.

This allows to generalize the property value presentation and make it consistent across all the application UI components which support property value presenters, including Input components (see Input components and forms) and listing components (see List data in grids).

New PropertyValuePresenter can be registered and used transparently to present the value for a specific type or a specific property configuration.

For example, suppose we want to add a # prefix to each value of the MY_PROPERTY property. We can declare a PropertyValuePresenter and bind it to the MY_PROPERTY property in the property presenters registry:

From now on, any ViewComponent instance will use the new presenter to render the MY_PROPERTY property value.

You can use the ViewComponent API adapt static methods to transform any Component into a ViewComponent. The Component will be used as ViewComponent content and a suitable function must be provided to setup the Component instance each time the value changes, for example to display the value using the custom Component instance.

A generic Component can be turn into a ViewComponent either providing:

1. The Component to use a ViewComponent content and a consumer function to setup the Component instance each time the value changes:

2. A function to provided a custom Component instance each time the value changes, to be used as ViewComponent content:

The adapt methods return a builder API consistent with the default ViewComponent builder API, allowing to configure the ViewComponent component.

When the holon-vaadin-flow artifact is in classpath, a default PropertyRenderer is automatically registered to render a Property as a ViewComponent.

So the ViewComponent.class type can be used to render any property as a ViewComponent. In this scenario, the property localizable message is used if available as ViewComponent label.

A set of ViewComponent type components can be grouped and organized using a PropertyViewGroup, using the Holon Platform Property model to bind each ViewComponent to a property definition.

The property definitions will be used as references to get and configure the ViewComponent instances managed by the group and to set the group values to display using a PropertyBox type.

The PropertyViewGroup API provides method to inspect the available properties and the ViewComponent instances bound to each property. Through the ValueHolder API, the group value can be setted and managed (see The ValueHolder interface).

To create a PropertyViewGroup, the property set to use must be provided at build time. Both the PropertyViewGroup API and the Components API (through the Components.view sub interface) can be used to obtain a property view group builder.

By default, the property rendering architecture is used to automatically generate the ViewComponent instances for each property of the group property set (see ViewComponent property renderer).

For example, given the following property model definition:

A PropertyViewGroup can be created in the following way:

To customize this behaviour and provide the ViewComponent to use for one or more property, the PropertyViewGroup builder API provides a set of bind methods, which can be use to explicitly bind a ViewComponent instance to a property.

When the holon-vaadin-flow artifact is in classpath, a default PropertyRenderer is automatically registered to render a Property as an Input.

So the Input.class type can be used to render any property as a Input. In this scenario, the property localizable message is used if available as Input label.

The Input API makes available the create(Property<T> property) method to directly create an Input for a given property.

The property renderers architecture is used consistently across the application UI, so when a renderer is bound to a specific property condition it is used by all the UI components with property rendering support, including input groups/forms (see Organize Input components in groups and forms) and item listing editors (see Editing the listing items).

For example, suppose we want to use a custom MyInput class to render the Input component for the MY_PROPERTY property definition. A custom property renderer can be created and registered:

From now on, the Input component for the MY_PROPERTY property definition will be a MyInput instance.

The Input API provides methods to use an Input with a different type than the value type to handle, providing a suitable com.vaadin.flow.data.converter.Converter to perform the value conversions to the required type.

A Holon Platform PropertyValueConverter can also be use to provide the value conversion logic when the input is bound to a Property definition.

The Input API provides methods to adapt a standard Vaadin HasValue type input component as an Input, including value conversion support using a com.vaadin.flow.data.converter.Converter.

The SingleSelect and MultiSelect APIs are Input extensions which represent selectable input components, i.e. input components which provide a set of items from which the input value can be selected, either supporting single or multiple selection values.

The Input API and the corresponding Components.input API provides methods to create SingleSelect and MultiSelect type input components, providing the selectable value type.

For SingleSelect input types, the input component can be rendered as:

The select input components can be used just like any other value holder type component to set and get the selected item/s (see The ValueHolder interface). The MultiSelect type input, since it allows multiple items selection, uses a java.util.Set to handle the input value.

Besides the Input API, the selectable inputs implements the Selectable API, which allows to manage and obtain the selected items.

The Input API can be extended using custom adapters, i.e. a class/interface to provide additional Input attributes and/or functionalities.

An adapter can be registered at Input build time using the withAdapter method, providing:

An adapter instance can be obtained using the Input API method <A> Optional<A> as(Class<A> type). If an adapter of the given type is available (i.e. was registered as described above), the adapter function will be invoked to provide the adapter instance.

The value of any Input component can be validated using the standard Holon Platform Validator API, through the ValidatableInput API.

An Input can be made validatable, adding support for Validator registration, using:

1. The validatable builder method:

2. The ValidatableInput adapter:

A ValidatableInput extends the Validatable API, which provides method to validate the input value using the registered validators.

By default, the validation errors are notified to the user using the UI component error message, if supported by the concrete input component.

The validation errors notification strategy can be customized using a ValidationStatusHandler function. The validation event provides the validation status (valid, invalid or unresolved) and the current validation errors, if any.

A set of Input components can be grouped and organized using a PropertyInputGroup, using the Holon Platform Property model to bind each Input to a property definition.

The property definitions will be used as references to get and configure the Input instances managed by the group and to get and set the group values using a PropertyBox type.

The PropertyInputGroup API provides method to inspect the available properties and the Input instances bound to each property. Through the ValueHolder API, the group value can be setted and managed (see The ValueHolder interface).