Vaadin Key Concepts

Need a button? Write new Button(). Need a text field? Write new TextField().

Build own components and views by composing existing components with layouts.

Navigate to components by marking them with a @Route("path") annotation.

Add a listener to a button with addClickListener() or get notified of changed selection in a select with addValueChangeListener().

Any component that a user can interact with will dispatch events that you can listen to.

@Route("")
public class MainView extends VerticalLayout {
 public MainView() {
   add(new H1("Hello World!"));
 }
}

Let’s begin by instantiating a new component:

Button button = new Button("Click me");
button.setIcon(VaadinIcon.VAADIN_V.create());

In Vaadin, each component is represented by a Java object. To use a component, create a new instance and configure it. The easiest way to explore the functionality of components is through the autocomplete menu in your IDE.

Having a component all by itself is not that useful. To build something more meaningful, we’ll want to create composites of several components that interact with each other. To do that, we need layouts.

VerticalLayout and HorizontalLayout are the workhorses of most Vaadin applications. As their name suggests, they place child components either vertically on top of each other or horizontally next to each other.

By default, the layouts are only as big as their contents and will add spacing between components to make the layout more natural to read and use. The spacing can be turned on or off with setPadding(false) for the spacing around the layout or setSpacing(false) for the spacing between components.

A common requirement is to have one component expand to use up all the space not needed by other components. This can be achieved with the expand(component) method on the layout.

Here is an example of the concepts in action to build a common app layout. In this example, we are setting widths and heights programmatically through Java. You can also do this via CSS, which we will cover later in this guide.

The Div is the most flexible of all the layouts, but it also requires you to handle all positioning yourself through CSS. We can use the CSS flexbox layout to achieve a smooth responsive layout that adapts to different viewport sizes.

When we are using CSS to layout components, we need to define CSS classnames for all the components. We also need to add a @StyleSheet annotation to load a CSS file.

Create the CSS file in the frontend/src/styles directory. This may either be webapp/frontend/src/styles/ or META_INF/resources/frontend/src/styles/ depending on the starter you are using.

Depending on your previous development background, you may find this approach cleaner than the earlier programmatic way. If you are working with designers as a part of your team, the CSS based view is going to be easier for them to configure without having to touch Java code.

Sometimes you may find it more convenient to define a layout declaratively in HTML. Vaadin supports this through the Template API.

Declarative layouts and Templates are considered a more advanced topic. You can learn more about creating declarative layouts in the documentation.

Button button = new Button("Click me");
button.addClickListener(click -> {
  Notification.show("Thanks for clicking!");
});

public class BusinessCard extends VerticalLayout {
  private Span name = new Span();
  private Span title = new Span();

  public BusinessCard() {
    add(name, title);
  }

  public void setName(String n) {
    name.setText(n);
  }

  public void setTitle(String t) {
    title.setText(t);
  }
}

@Route("component")
public class ComponentView extends VerticalLayout {

  public ComponentView() {
    BusinessCard businessCard = new BusinessCard();
    businessCard.setName("Marcus");
    businessCard.setTitle("Computer code maker");

    add(businessCard);
  }
}

public class BusinessCard extends Composite<VerticalLayout> {
  private Span name = new Span();
  private Span title = new Span();

  public BusinessCard() {
    getContent().add(name, title);
  }

  public void setName(String n) {
    name.setText(n);
  }

  public void setTitle(String t) {
    title.setText(t);
  }
}

Binder works with standard Java objects as the data model. It allows you to bind any property (getter/setter) to a UI field.

Binder supports both one-way data binding (readBean(model)) or two-way data binding (setBean(model)). Read the section on saving to learn how to get the value out of Binder if you are using one-way data binding.

Most of the time when building forms, we need to validate that the input we receive is correct. In Vaadin, this is done by adding a Validator to the field binding.

binder.forField(firstNameField)
  .asRequired()
  .withValidator(name -> name.equals("Marcus"), "Your name should be Marcus")
  .bind(Person::getFirstName, Person::setFirstName);

Here, we make the input field mandatory and require the input value to equal "Marcus." You can add as many validators as you want, they will get run in the order you define them.

Read more about field validation and how to use JSR 303 Bean validations for UI fields.

If your underlying data type does not match the data type of the UI component, you need to add a converter to the binding. In the following example, we want to bind a TextField (String) to an underlying int data field, so we need to add a StringToIntegerConverter.

binder.forField(ageField)
  .asRequired()
  .withConverter(new StringToIntegerConverter("Age must be a number"))
  .withValidator(age -> age > 2, "How are you using a computer?")
  .bind(Person::getAge, Person::setAge);

Read more about converting input

The same way you can add validations to individual fields, you can also add validators on the binder to validate fields against each other. Binder-level validation will only run if field level validation has passed.

We also need to define a layout in which we want error messages to be displayed.

Div statusLabel = new Div();
binder.setStatusLabel(statusLabel);
binder.withValidator(person ->
  person.getFirstName().equals("Marcus")
  && person.getLastName().equals("Hellberg"),
  "Ha! You have the correct first name, but wrong last name. Better luck next life!");

Two-way data binding

If you used two-way data binding (setBean()), the bound object would contain the updated values, provided that all field and form level validations passed.

One-way data binding

If you used one-way data binding (readBean()), you need to read the form manually.

try {
  Person saved = new Person();
  binder.writeBean(saved);
  // Persist saved bean
} catch (ValidationException e){
  //show errors to user
}

You need to pass Binder an instance to write the values to. If you are using one-way data binding, you usually do not want to pass in the original object, as this would mutate it.

Read more about saving and validating forms

If you have a small number of items, say a few hundred, the easiest way to deal with these is to just pass a java Collection to the setItems method.

In cases where you have much data, it makes sense to only load what’s needed at a given moment. Vaadin components like Grid and ComboBox do this automatically if you define a DataProvider.

Instead of calling setItems() as we did in the previous snippet, use setDataProvider().

The data provider takes two callback functions. The first query should return a stream of objects with a given offset and limit, the next page of data. The second query returns the total count of objects in your data set. This is used to display appropriate scrollbars and info in the UI.

The end user experience is the same whether you use setItems() or setDataProvider(). In both cases, the user can scroll freely through the entire data set. The only difference is that when using DataProvider, you are using fewer resources on the server.

Read about sorting and filtering lazily loaded data with DataProvider.

To define a route, annotate your class with @Route.

By default, Vaadin will determine the route path based on the class name, without the -View ending. In this case, the view would get mapped to /sample.

In many cases, it’s better to be explicit about the naming and define the path explicitly. For this, it’s recommended to use a constant to support refactoring later on.

Once you have a view defined, you can navigate to it in two ways. Using a router link, or programmatically.

To use a router link, add a RouterLink component to a layout.

add(new RouterLink("Go to the sample view!", SampleView.class));

The advantage of router links is that they will continue to work even if the server session has expired.

In some cases, you will need to navigate to another view programmatically. For instance, take the user to another view after filling a form. To do this, use ui.navigate().

Button saveButton = new Button("Save");
saveButton.addClickListener(click -> {
  // (Save form logic omitted)

  // On success, navigate to another view
  saveButton.getUI().ifPresent(ui -> ui.navigate(SampleView.NAME));
});

You can do much more sophisticated navigation systems than above. Please refer to the documentation to learn more about nested routes, URL parameters, and handling navigation exceptions.

@Route
public class ExampleComponent  extends VerticalLayout {
  private final Binder<Person> binder;
  private BackendService service;

  TextField firstName = new TextField("First Name");
  TextField lastName = new TextField("Last Name");
  Button saveButton = new Button("Save");

  public ExampleComponent(BackendService service) {
    this.service = service;
    add(firstName, lastName, saveButton);
    binder = new Binder<>(Person.class);
    // Bind fields to bean by name
    binder.bindInstanceFields(this);
    saveButton.addClickListener(click -> save());
  }

  public void save() {
    try{
      Person person = new Person();
      binder.writeBean(person);
      service.save(person);
      saveButton.setText("Saved");
    } catch (ValidationException e) {
      e.printStackTrace();
    }
  }
}

Unit and integration tests usually make up the bulk of the tests for your application. The tests do not require launching a server or a browser, so they are fast to run.

Unit tests and integration tests are very similar in their implementation. The main difference is that in a unit test, you test a single piece of code in isolation (for instance a component), whereas in an integration test you test several interconnected pieces of content together.

To write a unit test for the component above, we need a testing library to run the code and a mocking library to stub out dependencies to functionality that is not being tested.

In this example, we are using jUnit 5 and Mockito.

In the test, we set up a mock version of BackendService as we are focusing our test on ExampleComponent. All we need is to verify that it will get called with the right input.

In the test, we set up the UI state by entering values into the text fields. We then call save() and verify that the backend service would have been called with a Person object with the correct first and last names.

We could also have made this into an integration test by using a real implementation of BackendService instead of stubbing it out.

In end-to-end testing, we ensure that the complete application works as a whole. To do this, we need to set up a server to deploy the application and set up a browser testing environment.

Vaadin has an official browser testing tool called TestBench. It takes care of launching browsers and has Vaadin-specific selectors for finding UI components in the browser.

To test the component in its real environment through a browser, we could write the following TestBench test case.

Before running the test, we set up a new Chrome browser driver and open the route to the component.

We then find the button, click on it, and assert that the caption got updated correctly.

As you can see, this test is very coarse-grained. It can only tell us if everything worked, or if something failed. It won’t give us much information on what went wrong. Because of this, it’s good to have a comprehensive suite of fine-grained unit and integration tests to pinpoint issues. TestBench is better used for high-level, last line of defense, tests that can catch errors even if they are missed by other tests.

Read more about creating reliable and maintainable tests with TestBench.