Vaadin 8 Tutorial

You’ll have your first Vaadin app running in your IDE in a couple of minutes. To complete the whole tutorial, you’ll need about 20 to 60 minutes, depending on your existing experience. Naturally, you can just do the beginning of the exercise or pick any of the steps you want. To start from a specific step, we have prepared the example code after each step to be downloaded as a zip file.

In this tutorial, we build a simple customer management system. It is not a real application; we use an in-memory "back-end", so that you can understand how to hook it to an existing Java based back-end. We cover the basic Vaadin development and you can use the result as a basis for more experiments with Vaadin, such as using add-ons, your own custom look-and- feel (aka. theme), adding new views, or optimizing the result for mobile support.

If you do not want to do the exercise at all, you can also just download the final application and play around with it.

The following video shows how to do this step of the tutorial:

As the starting point for the application, we use a Maven archetype called vaadin-archetype-application. Archetypes are project stubs that have some example code and a basic Maven build script.

If this is your first Vaadin app, creating a project might take a while, depending on the speed of your network, as Vaadin libraries and other dependencies are being downloaded. Maven caches them on your local file system. Creating your next Maven-based Vaadin project will be much faster.

Right click on the newly created project and choose Run as › Maven Install. This initiates a full build of your application and finally creates a WAR file into the target directory. You can deploy the WAR file to your application server. The first build might take a while, as Maven might again need to download some new modules.

While the build is running, let us have a look at what the archetype created for you. You can browse your project resources from the tree structure in the Project Explorer. Maven’s pom.xml on top level contains settings for building your project and declares the used dependencies. Open Java Resources and below it src/main/java, the main source directory, and my.vaadin.app, the main Java package that will contain your Vaadin UI code.

The UI code (and the Servlet declaration) used by the application stub can be found in the MyUI.java file. Let us read it through to see how it works. The init() method of a UI class is triggered when a user enters your web application. The VerticalLayout is one of the most used layout components, which are used to position and display other Vaadin components in your UI classes. The example code creates one TextField to allow the user to input her name and a Button whose click listener dynamically adds a new Label component to the main layout. In the end of the init() method, we just configure the main layout and place components into it and set it to be the content of MyUI.

To test your first Vaadin application, right-click on the project and choose Debug as › Maven build…​. The debug mode is slightly slower than the basic run mode, but it often helps you to figure out what is happening in your application.

In the dialog, type Run in jetty to the Name input and jetty:run to the Goals input.

Before clicking debug, to make sure debugging works properly, add your Java project to the source lookup path from the Source tab, as it is being done in Adding sources for debugging.

Now click Debug to continue. This will download a small Java web server (if not cached to your local Maven repository), and use it to host your application. Once the server has started, point your browser to the URL http://localhost:8080/ to see the running application.

If you make changes to the code, the Jetty server will notice the changes and in a couple of seconds most changes are automatically deployed. Reloading the page in your browser will show the changes.

Mastering the usage of the Java debugger is also handy to better understand how your application actually works and fixing bugs that all developers write at some point. As Vaadin is "only" Java code, you can use all of Java’s debugging tools, which cannot be done with other UI frameworks where the UI is written (partly) in HTML and/or JavaScript. Double-click on the line number in the Java editor, for example of the following line in the click listener:

Doing so adds a breakpoint to the selected line. If you then click the button in your browser, the execution of the application will stop on that line. Eclipse will ask you to enter to Debugging perspective. That way you can step through the execution and inspect the variables. Clicking on the play icon in the toolbar will continue the execution. Double-click the same line again to remove the breakpoint.

Clicking the red square in the Console view will terminate the server process. You can restart it easily form the run/debug history. You can find that from the small down arrow next to the green play button or bug button (for the debug mode) in the tool bar. Alternatively, you can use the main menu Run › Run history/Debug history › Run in Jetty.

To get back to the Java EE Perspective, an Eclipse mode designed for editing Java web app code, click the Java EE button in the toolbar.

Before getting more into real Vaadin development, let us introduce some domain objects and a "fake backend". In a real-world application, you will most likely have something similar, implemented with, for example, JPA and EJB or a Spring-based service.

The following video shows how to do this step of the tutorial:

Copy the following three classes from github to your project. Class names point to the classes hosted in Github. Copying classes can be done in many ways.

In the next steps, we will be using these classes and build a UI around them. The actual implementation of these classes is not relevant for this tutorial, but feel free to have a look around.

Often when you start building a UI for a data-centric application, the first thing you want to do is to list your data from your back-end. There are several components and ways in Vaadin to do this. In this example, we will use the Grid component for tabular presentation of our customers.

The following video shows how to do this step of the tutorial:

We start by introducing a Grid to the MyUI class. We could of course just introduce the Grid as a variable in the init() method, but we most likely want to refer to it later. Also, let us get a reference to the CustomerService.

To simply list all properties of all Customer objects from the backend service, replace the init method with the following snippet:

As we’ll want to refresh the listing from various places in our application, extract the customer listing part into its own "updateList" method with the public modifier. The public modifier is handy later when we want to update the listing from other classes. You can let Eclipse help here by selecting the relevant lines and using the "quick fix" feature (Ctrl+1 or Cmd+1 on Macs). The extracted method call looks like this:

If you try the application now, you’ll see an empty Grid with no columns. To add columns, configure the Grid using the setColumns method to show the "firstName", "lastName" and "email" properties.

At this point the body of the MyUI class should look like this (servlet declaration omitted):

You can now save your changes to the file and verify the changes from your browser. You can do this at any point during the rest of the tutorial as well.

A search functionality is expected in every modern application and it is also a nice Vaadin development exercise. Let’s add a filtering functionality to the Customer listing we created in the previous step.

The following video shows how to do this step of the tutorial:

We’ll start by introducing a TextField component as a field to our UI class:

In the init() method, configure the text field to contain a helpful input prompt and add a text change listener to the field. The exact place of these lines is not important, but add them, for example, after you have introduced the layout object.

As its name implies, the value change listener allows you to react to changes in the value contained in the text field. It is configured so that the event is fired lazily while the user is typing, when there is a small pause in the typing. This makes it perfect for this kind of automatic filtering. When the user has changed the text, we’ll just update the listing calling the updateList method.

To keep the updateList method functional, it should take into consideration the possible value in the filterText field. Change the line for fetching the customers into this:

Before adding the text field to the UI, let’s improve the usability a bit and make a short exercise to compose better components from lower level UI components. The search field can naturally be cleared with the keyboard, but let’s add a clear button next to the text field. Start by adding the following lines to the init method, for example right after your filterText configuration:

Vaadin contains a set of built in icons, from which we use the "X" icon, VaadinIcons.CLOSE, here, which most users will recognise as a functionality to clear the value. If we set the description to a component, it will be shown as a tooltip for those users who hover the cursor over the button and wonder what to do with it. In the click listener, we simply clear the text from the field.

Vaadin contains lots of different kinds of layouts. The simplest way to align the text field and the button next to each other would be to use a HorizontalLayout. An alternative way we use here is using a CssLayout, which is a lightweight layout that is easy to customize with css. Even if you wouldn’t want to play with CSS yourself, you can often use one of the existing style rules in the default Valo theme. The following snippet will create a nice compact "composition" of both the TextField and the clear button. Add these lines to the init method right after you configured the clearFilterTextBtn:

Finally, change the line in the init method that currently adds only the grid, to add both filtering composition and the grid to the main layout of the application.

Now it is a good place to save your changes and try them in your browser.

To edit and add Customer objects we need to create a form, that edits the values in our domain objects. This tutorial has two alternative methods to do that. Pick either of them.

In this part, we’ll use the CustomerForm class, which we created in the previous step, from the MyUI class. We will use it for both editing the existing customers and creating new ones.

The following video shows how to do this step of the tutorial:

In the previous part, we already added the form to the MyUI to see what it looks like. By default, we want it to be invisible, so let’s first hide it by adding this line to the init method of MyUI class:

To edit the customer chosen from the Grid, add the following selection listener to the end of the init method:

In the listener, we simply take the Customer object of the selected row and pass it to the CustomerForm for editing. In the previous step, we added a side effect to the setCustomer method that will bind the domain object to the corresponding fields and make it visible. If the selection is empty, we’ll hide the form.

To allow users to also create new customer records, we’ll create a simple "Add customer button" to the top of the UI, right next to the filtering composition we have already built from a CssLayout, a TextField and a Button. Introduce the new Button with a click listener, by adding the following lines to the init method, right after where you introduced the filtering composition:

In the click listener, we first clear a possible selection from the grid and then instantiate a new Customer object and pass that to the form for editing.

To add it beside our filtering composition, we can use a HorizontalLayout to create a toolbar where we place both components. First, introduce a toolbar like this after the previously created addCustomerBtn:

And, again, replace the line that populates your main layout to add the toolbar instead of just the filtering composition, which we just moved to the toolbar layout.

All planned features are now done. You can save the changes and play around with the application. If something went wrong, you can also download an example of the final application and see what went wrong.

Congratulations! Users can now create, read, update and delete customer records stored in the demo backend and you have completed creating your first CRUD UI with Vaadin.

If you are an experienced Java developer, you are probably already full of ideas of how you can use your existing skills and create new shiny web UIs for your existing Java apps. If you want more ideas of how to create full stack applications, you might, for example, go through the Creating CRUD UI with Vaadin guide and create a bit similar UI with a real database backend implemented with Spring Data JPA. We have also collected a couple of other resources for an easy start in your Vaadin developer career.