/ Vaadin Flow Framework

Using Web Components in Vaadin with Gradle

One of the biggest changes in Vaadin Flow compared to Vaadin Framework 8 is the change from using Google Web Toolkit (GWT) to using web components. For previous Vaadin developers this brings a lot of new terminology to learn and a lot of new Javascript framework tools, mostly known to frontend developers, to handle and manage.

The Gradle plugin tries to mitigate the JS tool bloat by allowing you to work with web component dependencies just as you would do with standard Maven dependencies.

This new support is introduced in Gradle Vaadin Flow Plugin 1.0.0.M2 which is now available from the Gradle Plugin repository.

Selecting your web component distribution channel

By default all the Vaadin components are distributed as WebJars. WebJars are pre-packaged web components that you can add as a standard dependency to your Gradle build. Support for this was already added in the M1 version of the plugin. For more information on this see https://github.com/devsoap/gradle-vaadin-flow/wiki/Dependency-management.

While it is preferrable to use WebJars as they can be handled by the standard dependency management not all dependencies you might like are available as WebJars. In this case the Gradle plugin now provides two ways of dowloading them, using Bower or Yarn.

For those of you who haven't been involved in frontend development these might be unfamiliar, but in principal they are dependency managers for Javascript dependencies in a similar fashion as Gradle or Maven are dependency managers for Java dependencies. They come with their own tool-chains and configurations which might be very confusing for us backend developers.

But don't worry, you will not need to learn neither bower or yarn to be able to build a Vaadin project with them, the plugin will configure and use them behind the scenes, you will just need to list the dependencies you need.

Adding a client dependency to the project

While usually to use Bower or Yarn you will need to manage the dependencies in separate json files, the plugin allows you to manage the dependencies inside your build.gradle and it will then generate the proper files automatically.

To add a new dependency we use the vaadinClientDependencies-configuration block in build.gradle.

vaadinClientDependencies {
    bower 'PolymerElements/paper-slider'
}

In this example we want to include the paper-slider component from the PolymerElements project into our project using Bower. The syntax for adding dependencies is very similar to what adding normal dependencies is.

And here is the same example using Yarn:

 vaadinClientDependencies {
    yarn '@polymer/paper-slider:0.0.3'
}

The only difference is that we use the yarn keyword here instead of bower.

As you can see you can also optionally add a specific version of the dependency if you wish. If you omit the version, then the latest version will be used.

When you add a client dependency then when the project is built, the dependency will be downloaded and placed in a special folder src/main/webapp/frontend. Vaadin will use this folder when rendering the view.

Taking a client dependency into use in a Vaadin project

We have so far only looked at how we can download the dependency into our project with Gradle but not yet looked at how we can integrate that Javascript component with our Java application.

To simplify things the plugin comes with a special task for adding web components to the project and generating the necessery stubs for using the component in the Java application.

To create a new Web Component in our project we can simply run

$> gradle vaadinCreateWebComponent --dependency 'bower:PolymerElements/paper-slider' --name 'PaperSlider'

This will create the following class in your project:

package com.example.vaadinflowtest;

import com.vaadin.flow.component.Component;
import com.vaadin.flow.component.Tag;
import com.vaadin.flow.component.dependency.HtmlImport;

@Tag("paper-slider")
@HtmlImport("frontend://bower_components/paper-slider/paper-slider.html")
public class PaperSlider extends Component {

    public PaperSlider() {
    }
}

You can then use this class anywhere in your views just as you do with normal Vaadin components.

The task will also add the client dependency to your build.gradle automatically, so you don't have to manually add the dependency.

One thing to note is that, the first time you run the task it will be slow. This is because Gradle will need to download all necessery tooling for handling Javascript web components and download the actual component as well. This can take some time so be patient. Once you have the dependencies already downloaded then it will be faster.

Taking a peek under the hood

If you are curious about what is downloaded you can have a look into the build/frontend directory. There you will find all the downloaded components in bower_components and node_modules directories as well as the bower.json and package.json files used to build the components.

In normal situation you will not need to know what exists here, but if you encounter an error then it might prove useful to have a look and see if you get a better hint from there.

Another good hint if you want to see more logging from the client tools is to run gradle with the --info option. This will print out better error messages and download information as the plugin downloads the dependencies.

--

You now know how to take into use javascript components in your Vaadin web apps. In the next article we will be looking into how to take our project into production and how to support older browsers like Internet Explorer 11 with our javascript components which might not even be written for such browers. Stay tuned!