Sven Ruppert

We will now create a new Vaadin Flow application step by step and create a basic framework for our own projects with this component-based open-source web framework. So, right from the start, the question arises: How can you start with as little effort as possible without avoiding the usual expenses that sometimes come with creating projects?

How and where do I start my project?

First we go to the URL start.vaadin.com. Here, we get to an application that allows us to generate a Vaadin project. Here, we choose the option “Hello World Project” out of. As soon as you get to the field “Edit” on the right side with the mouse, the selection options shown here open. In this article, I will use Settings a) Flow / Java, b) Java, c) Maven, d) Servlet.

I chose this setting specifically because I don’t want to have any additional technological dependencies on other frameworks at this point, making the project as small as possible.

After downloading the packed project, you can unpack it in a folder of your choice and get the complete directory structure necessary for a Maven project. To work with the project, please open the project with the IDE of your choice. I will use the IDE IntelliJ (https://www.jetbrains.com/idea/) from JetBrains in the community version in this article. This is freely available on all relevant platforms (Windows, Linux, and OSX). At this point I am assuming that a JDK and Maven are already installed and configured to work on the development computer.

After the project has been opened, you can do the first test to see whether everything is working. You can do this, for example, on the command line within the project directory with the following Maven command. mvn clean verify If everything runs through to the end without any error messages, you have downloaded all the necessary dependencies from the relevant repositories to your computer using Maven.

With the command mvn clean package jetty:run, you can also try out the project straight away. Everything is translated, assembled, and started within the servlet container Jetty. If you now access the URL with a browser, http://localhost:8080/, you will see the Vaadin Flow application. 

Now, you can try out how this application works. by entering something into the input field and then clicking the button labelled “Say hello” clicks. In my case, I entered my name, “Sven Ruppert”, and activated the button once. The result then looks like this in my browser.

What is included in the project?

But how can you program this yourself? To do this, we first end the ongoing process that we are using mvn have started.

First, we edit the pom.xml a little. Here, we will limit Vaadin’s dependency on pure open-source components. This saves time and space during development. For this purpose, the definition “vaadin” changed in “vaadin-core”

<dependency>
   <groupId>com.vaadin</groupId>
   <artifactId>vaadin-core</artifactId>
</dependency>

The application logic

The example application consists of three Java classes. We’ll now start with the business logic we used in the class GreetingService find. There’s not much to say about this, as it’s a good old plain Java class. The goal is to transform the input string passed so that the greeting comes out. We don’t find any Vaadin elements here yet.

public class GreetService {
   public String greet(String name) {
       if (name == null || name.isEmpty()) {
           return "Hello anonymous user";
       } else {
           return "Hello " + name;
       }
   }
}

Then, we are missing two more Java classes, which we can find in the source code folder. On the one hand, it’s the class ”MainView”. The entire visual design of this demo app is implemented here.

How do I define the GUI?

@Route("")
public class MainView extends VerticalLayout {
   public MainView() {
       TextField textField 
           = new TextField("Your name");
       GreetService greetService = new GreetService();
       Button button
           = new Button("Say hello", and -> {
               String value = textField.getValue();
               String greet = greetService.greet(value);
               Paragraph paragraph = new Paragraph(greet);
               add(paragraph);
           });
       add(textField, button);
   }
}

Let’s go through this together. First, we see the class definition “MainView”, which arises from deriving the class “VerticalLayout” results. This is a layout component in which the elements are arranged vertically inside. Within the constructor, we now define the various visible elements. In this case, it is an input field and a button. At the very end, these are in the order of text field and button with the method add(..) added to the VerticalLayout. The GreetingService is created within the constructor, and then within the ActionListeners, the button is used. For this example, the procedure shown is exemplary. However, we will examine when you should use other design patterns in a later article. The button here has a clearly defined English label, “Say hello”, that the user sees. Things get more interesting when defining behaviour. When you click the button, the values ​​are read from the text field using the instance of GreetingServers modified. This new value is then embedded in a graphical component of the Paragraph type and passed to the external layout as a child node.

Here, you can see quite clearly that you don’t have to worry too much about the typical web application challenges during development. You can use everything that the Java language offers in terms of abstractions.

The MainView class has an annotation called “@Route(“”)”. Die Annotation “@Route” is used in Vaadin to map a view component (e.g. a UI) to a specific URL. It indicates which class is the web application’s main view for a particular path. This allows the user interface to be accessed via a specific URL in the browser.

The annotation’s value specifies the path under which the view can be reached. If no path is specified, the view is accessible at the root path (“/”).

   @Route("")
   public class MainView extends VerticalLayout {
       // View content
   }

In this example, the `MainView` is under the root path (“http://localhost:8080/“) reachable. You can also specify a specific path to make the view accessible at a specific URL.

   @Route("all")
   public class ToDoView extends VerticalLayout {
       // View content
   }

The “ToDoView” under the path “http://localhost:8080/todo” is reachable in this example.

The annotation allows Vaadin to control navigation within the application. Users can navigate to different views by changing the URL in the browser or using programmatic navigation methods. The “@Route” annotation can also be used with a layout. A layout is a high-level component that contains multiple views. Here is an example:

   @Route(value = "todo", layout = MainLayout.class)
   public class ToDoView extends VerticalLayout {
       // View content
   }

 In this example, “ToDoView” within the “MainLayout” is displayed if the URL “http://localhost:8080/todo” is called. You can also use dynamic parameters in the URL to display specific content in the view.

   @Route("user/:userID")
   public class UserView extends VerticalLayout {
       // View content
   }

In this example, “UserView” at a URL like “http://localhost:8080/user/123” is called, whereas “123” is a dynamic parameter.

In summary, the `@Route` annotation defines URL mapping to View classes in Vaadin, which enables navigation and access to various parts of the web application.

How can I configure the web app?

Now, we’re missing the class AppShell, which is the implementation of the interface AppSehllConfigurator. 

@PWA(name = "Project Base for Vaadin", shortName = "Project Base")

@Push

@Theme("my-theme")

public class AppShell implements AppShellConfigurator {

}

The interface ”AppShellConfigurator” in Vaadin Flow defines the general configuration of the HTML shell of your Vaadin application. This mainly concerns the “<head>” area of ​​the HTML document where meta tags, titles, links to external resources (such as CSS files or favicons), and similar configurations can be set. 

Here, for example, I added “Dark” to the theme definition, which now gives the following look.

@PWA(name = "Project Base for Vaadin", shortName = "Project Base")

@Push

@Theme(value = "my-theme", variant = Lumo.DARK)

public class AppShell implements AppShellConfigurator {

}

Let’s go back to the method”configurePage” in Vaadin Flow. Here, you can configure the general HTML shell of your application. This method customises various aspects of the HTML document, especially the “<head>“-Area. Here are the main adjustments you can make:

You can set the HTML page title. The page title is displayed in the browser tab and is essential for user experience and search engine optimisation.

Meta tags are essential for providing metadata about HTML documents. With “configurePage” you can add different meta tags, such as:

• Viewport meta tag: This is especially important for responsive designs as it determines how the page will appear on different devices and screen sizes.
• Description: A meta tag to describe the content of your page, which is vital for search engine optimisation (SEO).
• Keywords: Keywords that describe the page’s content and can improve SEO.

Favicons are tiny icons that appear in browser tabs and bookmarks. You can set different sizes and types of favicons to ensure they look good on all devices and platforms. You can add links to external resources such as CSS stylesheets or JavaScript files. This is useful for including additional libraries or styles in your application.

For Progressive Web Apps (PWAs), you can use the “configurePage” method to configure the manifest and service worker. The manifest defines how the application displays on the home screen of a mobile device while using the service worker for offline functionality and push notifications.

To increase the security of your application, you can add various security-related meta tags, such as Content Security Policy (CSP).

Social media tags such as Open Graph (for Facebook) or Twitter Cards can be added to determine how your pages appear when shared on social networks. For mobile applications, you can set specific settings that improve the appearance and behaviour of your web application on mobile devices, such as the status bar colour and the app icon on the home screen.

By using the method “configurePage”, you can ensure that all critical meta information and resources are consistently and correctly integrated into every HTML page in your application. This contributes to a better user experience, optimised performance and improved web application security.

Which Are there any components?

After discussing the existing classes, we can modify the GUI a bit. We will now try out various components a little. The first question is, what categories of components are there in Vaadin Flow?

There are a variety of components in Vaadin Flow that can be grouped into different categories. Here are the main types of components with some examples:

Basic layout components:

• VerticalLayout: Arranges components vertically.
• HorizontalLayout: Arranges components horizontally.
• Div: A simple container that works like a `<div>` element in HTML.
• FormLayout: Explicitly designed for form layouts to arrange input fields in a grid.

Input components:

• TextField: Simple text input.
• TextArea: Multi-line text input.
• PasswordField: Input field for passwords in which the characters are hidden.
• ComboBox: A drop-down menu with choices.
• DatePicker: Selecting a date.
• CheckBox: A checkbox.
• RadioButtonGroup: A group of radio buttons.
• Select: A drop-down selection component.

Button components:

• Button: A simple button that can be clicked.
• NativeButton: A button that behaves like a native HTML button.
• Checkbox: A checkbox.

Display and information components:

• Label: A simple text label.
• Html: Component for displaying HTML content.
• Image: To view images.
• Notification: To view notifications.
• ProgressBar: A progress bar.
• Badge: To display small blocks of information or counters.

Navigation components:

• MenuBar: A menu bar.
• Tabs: Tabs for navigation between different views.
• Accordion: An accordion component for collapsible content.
• DrawerToggle: A toggle for a side menu.

Grid and data displays:

• Grid: A robust table for displaying data.
• TreeGrid: A tree-structured grid for displaying hierarchical data.
• ListBox: A simple list to display choices.
• DataView: To display data in a structured form.

Dialogues and overlays:

• Dialog: A modal dialogue for user interactions.
• Overlay: To overlay content on the current view.

Multimedia components:

• Audio: For embedding and playing audio files.
• Video: For embedding and playing video files.

Forms and validation:

• FormLayout: Used to arrange form fields in a layout.
• Binder: For binding forms to data models and validation.

Special and advanced components:

• Upload: To upload files.
• RichTextEditor: A WYSIWYG editor for rich text input.
• SplitLayout: To divide the layout into two areas using a sliding divider.
• DateTimePicker: To select the date and time.

These components cover many use cases and enable developers to create rich and interactive web applications. Vaadin Flow also offers the ability to create and extend custom components to meet specific needs.

Hello World for advanced users 

Let’s now move on to the practical application of individual components. We are writing a small application that includes multiple input fields, a table to display data, and easy navigation between two views. This extension showcases more of Vaadin’s capabilities, including layouts, forms, data bindings, and navigation. However, we have not yet gone into the concepts of industrial applications. We will address this in detail in the next post.

If you have different views, the question almost automatically arises as to how you can define the general appearance of the application. Layouts in which the primary division of the application is defined are suitable for this. Vaadin Flow offers you the component AppLayout at this point. This is a simple layout structure that already provides you with elements such as a navigation bar and a workspace. This is precisely what we will use now. For this, we create the class MainLayout and direct them from AppLayout away. In the constructor, we define the desired structure. In our example, we would like to receive two entries for navigation. Firstly, access to the existing MainView and secondly to a new view with the name DataView to record and display a personal data record. The class RouterLink is the required element to be added to a navigation bar. 

public class MainLayout extends AppLayout {
 public MainLayout() {
   createHeader();
 }
 private void createHeader() {
   RouterLink mainLink = new RouterLink("Hello World", MainView.class);
   RouterLink dataLink = new RouterLink("Data View", DataView.class);
   addToNavbar(new HorizontalLayout(mainLink, dataLink));
 }
}

So the class MainView Now knowing that it is within the layout is in the annotation @Route the class MainLayout specified in the layout attribute.

@Route(value = "", layout = MainLayout.class)
public class MainView extends VerticalLayout {
    //COLLAR
}

This way, a nested layout can be quickly built with Vaadin Flow. 

Now, let’s move on to the second view, DataView. Here, we can do the same thing as MainView proceeds. 

@Route(value = "data", layout = MainLayout.class)
public class DataView extends VerticalLayout {
 private List<Person> people = new ArrayList<>();
 private Grid<Person> grid = new Grid<>(Person.class);
 private ListDataProvider<Person> dataProvider
     = new ListDataProvider<>(people);
 public DataView() {
   was firstNameField = new TextField("First Name");
   was lastNameField = new TextField("Last Name");
   was addButton = new Button("Add Person",
       event -> {
         people.add(
             new Person(firstNameField.getValue(),
                        lastNameField.getValue()));
         dataProvider.refreshAll();
       });
   grid.setDataProvider(dataProvider);
   grid.setColumns("firstName", "lastName");
   add(firstNameField, lastNameField, addButton, grid);
 }
}

The DataView is also derived from one VerticalLayout. First, we define the required infrastructure elements. In this case, there is a list for the people, a table to display them, and a ListDataProvider, which is the connection between the graphical representation and the data itself. I won’t go into the specific properties here, just this much in advance: the attributes of the class Person are the headings of the columns in the table. 

Now, we define the appearance and dynamic behaviour of the displayed components. This time, there are two text fields for entering the data and a button for adding the data to the table. The ActionListener of the button creates an instance of the class from the values ​​of the two input fields Person. This instance is added to the list and subsequently informed to the DataProvider that there has been a change to the data. So that the DataProvider and the table know about each other, they are made known to each other. This is done by passing the DataProvider to the table. 

Finally, all visible elements are added to the DataView.

If you start the application now, you will get the following views:

We now have a rudimentary basis for our projects with Vaadin Flow. The following article will look at how we can expand the project.

I have placed the example on Github using the following URL.

Until then, have fun with your experiments.

Happy Coding

Sven