Getting Started With Vaadin 10

Modern Web Apps in Java

Vaadin makes it quick and simple to create HTML user interfaces using Java. Using a built-in selection of components, themes, data binding, and more, Vaadin is the ideal in web application development frameworks.

Getting Started With Vaadin 10

Modern Web Apps in Java

Vaadin makes it quick and simple to create HTML user interfaces using Java. Using a built-in selection of components, themes, data binding, and more, Vaadin is the ideal in web application development frameworks.

What Is Vaadin?

Vaadin is an open-source web development platform for implementing HTML user interfaces (UI) using Java. Vaadin's strength is in its server-side API, Vaadin Flow, which allows not only the composition and implementation of UI components but also the direct manipulation of the Document Object Model (DOM) from the server.

With Vaadin Flow, developers implement the UI in Java running on the server side by using components such as text fields and buttons, arranging them into layouts, and connecting them to business logic through event listeners.

Vaadin Flow provides a variety of high-level ready-to-use UI components optimized for mobile and responsive design. It also includes data binding helpers, URL-based navigation, Web Components integration, and support for HTML templates.

Figure 1: Vaadin client-server architecture

Since modern IDEs can list classes, methods, and even Javadocs, this Refcard is a reference guide to things IDEs can’t quickly or directly tell you.

Section 2

Important Links

Website: https://vaadin.com

Vaadin Flow’s information page: https://vaadin.com/flow

Blog: https://vaadin.com/blog

Documentation: https://vaadin.com/docs

List of components: https://vaadin.com/components/browse

Components directory: https://vaadin.com/directory

Forum: https://vaadin.com/forum

GitHub: https://github.com/vaadin

Section 3

“Hello, World” With Vaadin Flow

The following example shows how to implement a simple UI with a text field and a button that, when clicked, invokes server-side logic that adds a greeting text to the layout:

Figure 2: The “hello, world” application rendered as HTML in the browser

You implement user interfaces by extending an existing UI component such as VerticalLayout and annotating it with @Route. You can build up the UI by combining Vaadin components such as TextField, Button, Span, and many others to which you can add behavior by defining event listeners. The code runs on the server, which allows you to easily connect the UI to business logic. Optionally, you can customize the look and feel with CSS, bind UI components to backend data, manipulate the DOM from the server side in Java, and integrate Web Components.

Section 4

Bootstrapping a Project

The easiest way to bootstrap a new Vaadin Flow project is by using the project templates at vaadin.com/start. Select any of the templates for Vaadin version 10 or later, download and extract the zip file, and import it into your favorite IDE.

Alternatively, you can add the vaadin-core dependency in any Java web application and start using Vaadin Flow right away. With Maven, you can add the following to the pom.xml file:
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-core</artifactId>
<version>LATEST</version>
</dependency>

Vaadin Flow requires the Servlet API version 3.1 or later. You can add it with Maven as follows:

Components

All Vaadin UI components directly or indirectly extend the Component class. You can add visual components and layouts into other layouts. There’s always one root component for each view that is mapped to a URL with a @Route annotation. Figure 3 shows the Component abstract class, interfaces it implements, and some of the relevant methods. All of the 3 interfaces are also functional interfaces.

Figure 3: The Component Interface

You’ll see this API pattern throughout the framework: abstract and concrete classes implementing mixin interfaces to build up the functionality of the component. For example, the CheckBox class directly or indirectly implements the HasSize, HasStyle, Focusable, ClickNotifier, and HasValueAndElement interfaces. You don’t need to memorize or even use this interface when creating a UI. However, knowing about them and their methods will help you to understand the features available in the UI components. The following table shows the mixin interfaces, their purposes, and their methods:

Input Components

All input components implement HasSize (except ListBox), HasStyle, and, for most of them, HasValue and Focusable. The following table shows other of the mixing interfaces implemented by each input component:

HTML Components

There are UI components that represent most common elements in HTML and that extend the HtmlComponent class, for example: Div, Span, Section, Header, Footer, Article, H1, H2, H3, H4, H5, H6, Paragraph, Label, Anchor, OrderedList, ListItem, Image, and several others.

Tip: If you come from previous versions of Vaadin, note that the Label class is mapped to the label HTML element which is intended to be a label for an input element. Use components such as Span, Text, or Div, instead of Label when migrating from previous versions of Vaadin.

Section 8

Notifications

You can show notifications using the Notification class or its static show method. Notifications accept text or UI components:

new Notification(
new VerticalLayout(
new Span("Terms accepted."),
new RouterLink("Learn More", TermsView.class)
)
).open();

Section 9

Sizing

You can adjust the size of any Component that implement HasSize. The size of components can be set in fixed or relative units by either dimension (width or height) or be undefined to shrink to fit the content. You can either use explicit size or define it relatively from the area provided by the parent component. Notice that if all the components in a layout have relative size in a particular direction, the layout may not have undefined size in that direction!

Method

Description

setWidth
setHeight

Set the component size in either fixed units (px, pt, pc, cm, mm, in, em, or rem) or as a relative percentage (%) of the available area provided by the containing layout. The null value or -1 means undefined size (see below), causing the component to shrink to fit the content.

setSizeFull

Sets both dimensions to 100% relative size.

setSizeUndefined

Sets both dimensions as undefined, causing the component to shrink to its minimum size.

Layouts

A UI is built hierarchically from layout components, or more generally component containers, with the actual interaction components as the leaf nodes of the components tree. Some layouts accept multiple components and others a limited number.

Figure 4: Vertical and horizontal layouts

Section 10

Margin and Padding

Certain layouts (those implementing ThemableLayout) support setting margin and padding programmatically. Setting setMargin(true) and setPadding(true) enables all paddings and margins respectively. The margin and padding sizes can be adjusted with a CSS rule. Example:

Spacing

Certain layout components also support the setSpacing(true) method that controls the space between the contained components. Spacing can be adjusted with CSS properties (for example, --lumo-space-m: 20px).

Section 12

Alignment

Alignment is based in the Flexbox layout mode of CSS. With Flexbox, you have two axis: main axis and cross axis. In a VerticalLayout, the main axis is a column that runs from top to bottom (flex-direction: column, in CSS). In a HorizontalLayout, the main layout is a row that runs from left to right (flex-direction: row, in CSS). You can override to column-reverse or row-reverse with CSS if needed. Since the axes have a direction, you specify the alignment in terms of start/end instead of left/right or top/bottom. To set the alignment in the main axis you can use the setJustifyContentMode method.

Figure 5: Main axis alignments

To set the alignment in the cross axis you can use the following methods:

Grow (Expanding Components)

The setFlexGrow method allows you to configure how to distribute the space in a layout for each component. The flex grow property specifies the amount of the available space inside the layout a component should take up, proportionally to the other components. For example, if all components have a flex grow value of 1, the remaining space in the layout will be distributed equally to all components inside the layout. If you set the flex grow value of one component to 2, that component will take twice the available space as the other components, and so on.

Figure 6: Flex grow example

Section 14

FormLayout

FormLayout is a responsive layout that helps making forms readable in all screen sizes. The following example sets a FormLayout that uses 3 columns for widths of 22em or more, 2 columns for widths between 21em and 22em, and 1 column for widths of less than 21em:

formLayout.setResponsiveSteps(
new ResponsiveStep("0", 1),
new ResponsiveStep("21em", 2),
new ResponsiveStep("22em", 3));

Section 15

Dialog

Figure 7: The same form layout rendered in different screen sizes Dialog is a popup layout you can show in the UI using its open method. For example:

Grid and Lazy Loading

Grid, the component that shows your data in a tabular format, often plays a central part in business applications. The easiest way to use the Grid component is to pass the data as a list, stream, or array. In the following code example, Person is the domain object (a Java Bean):

The addColumn method returns a Column object that can be used to further configure the column and the data representation. In the above example, we only configure the caption of the column. With bean-based listing, you can get a reference to the Column with getColumn(“propertyName").

The setItems method stores the given data in your server memory for rapid access. If your data grid contains a lot of data and you wish to save server memory, you can also do a lazy binding with your backend using the setDataProvider method:

The example above uses the easiest solution, in which you only pass two lambda expressions: the first to provide the given range of items, and the second to provides the total number of items available. Alternatively, you can provide a custom implementation of the DataProvider interface.

Section 16

Data Binding

Binder is a helper class that allows you to bind Java properties to UI components so that the input made by the end user automatically gets written to your domain model. The Binder class also helps you to convert values and validate the data. The following binds firstName (String) and age (Integer) to two text fields:

Routing and Navigation

You can link UI components to URLs using the @Route annotation. Optionally, you can specify a layout (that must implement RouterLayout) where the annotated component should be rendered, and implement HasUrlParameter if the view accepts parameters:

To pass the value world as a parameter, you can request the application with a URL like http://yourdomain.com/greet/world. The route name is derived from the class name removing any trailing "View". If the class is named MainView or View, it will be mapped to a root URL (""). You can override this by using the value property of the @Route annotation.

The following interfaces allows you to interact with the navigation lifecycle. You can implement observers in a UI component or manually register listeners using the UI class.

Interface

Description

BeforeLeaveObserver
BeforeLeaveListener

Allows delaying or canceling the navigation, or changing the navigation to a different destination

BeforeEnterObserver
BeforeEnterListener

Allows changing the navigation to a different destination

AfterNavigationObserver
AfterNavigationListener

Allows updating parts of the UI once the navigation has been completed

Section 18

Custom Components

You can create custom components by using existing components and extending Composite, which allows you to hide the API of the actual root level component:

Element API

The Element API of Vaadin Flow allows you to manipulate the DOM from server-side Java. Most often you should use the Element API to create custom components or do small modifications to existing ones. Since the Component class implements the HasElement interface, all UI components have an underlying Element object that you can get with component.getElement(). The Element class represents an HTML element in the DOM and contains methods to update and query various parts of an element, such as attributes and child elements.

The following example shows how to create an input field with a companion label and how to set properties and styles:

Tip: You can visually edit HTML templates in Eclipse or IntelliJ with Vaadin Designer.

The previous template imports the Polymer library and two Web Components: vaadin-text-field and vaadin-button. These are static resources packaged as a WebJAR and included with Vaadin (from a Bower-based installation).

The name value and buttonClicked method can be used server-side as follows:

The ExampleModel interface defines getters and setters for the HTML attributes defined in the template (for example {{name}} in the HTML file).

Section 21

Themes

Vaadin separates the appearance of the user interface from its logic using themes. Theming is done, as with any HTML content, by using CSS. Vaadin 10 includes the Lumo theme. It has a light (default) and a dark variant:

You can add CSS class names to any UI component using the addClassName and addClassNames methods:

addClassName("custom");

This class name can be used in a selector in the shared-styles-html file:

.custom {
color: red;
}

Deployment

To deploy a Vaadin Flow application in a production environment, you must add the vaadin-maven-plugin in a Maven profile in the pom.xml file and compile the project specifying the name of the profile (for example, mvn clean package -PproductionMode). This performs three main tasks: