Integrating a Web Component

Web Components are a collection of web standards allowing you to create new HTML tags with custom name, reusability and full encapsulation on styles & markup. To understand more about what Web Components are, visit Introduction to Web Components.

To be able to use a web component from Flow you need two things: to load the HTML/JS/CSS files needed by the component and a Java API used to configure the component and to listen to events from it.

The client-side files for a web component, typically one HTML file, are available using the Bower package manager. To avoid having to use two package managers, i.e. Maven and Bower, in the same project, the files can be packaged into a jar file called a webjar, which in turn can be deployed to Maven central. Flow will automatically use webjars and server the static files to the browser with an additional possibility to serve files installed using Bower.

Step 1. Creating a Webjar

If the webjar is not available yet, it can be deployed using webjars.org. Through https://www.webjars.org/ anybody can deploy any available Bower artifact as a webjar. Press “Add a WebJar”, make sure “Bower GitHub” is selected, enter the GitHub repository URL and select the version to deploy. Wait until deployment finishes.

Webjars are managed through the webjars.org service which handles packaging and deploying of them to Maven central. The groupId and artifactId of a webjar is defined as follows: * groupId: org.webjars.bowergithub.[GITHUB_ORG] * artifactId: [GITHUB_REPO] * version: [GITHUB_RELEASE_VERSION]

For example, paper-slider 2.0.4 is available at https://github.com/PolymerElements/paper-slider/releases/tag/v2.0.4 and the Maven artifact is * groupId: org.webjars.bowergithub.polymerelements * artifactId: paper-slider * version: 2.0.4

You can see that paper-slider 2.0.4 is already available by opening http://central.maven.org/maven2/org/webjars/bowergithub/polymerelements/paper-slider/2.0.4/

The most typical problem you can run into when deploying a webjar is that the license defined in the project’s bower.json is not a known open source license. The webjars.org site is an open source project and only deploys artifacts with a known, free license. If the license is just missing from the project’s bower.json, you can make a pull request to add it and everybody will benefit. You also have the possibility to fork the project, fix the license and deploy a webjar from your fork.

If the project does not use an open source license accepted by webjars.org, you can still use the webjars.org service to create a webjar using an available REST endpoint if the project is in a public GitHub repository:

sh

curl -OJ -H "Content-Type: application/json" -d '{"groupId": "com.example.yourcompany", "license": { "SomeLicenseID": "https://some.license.url/somewhere" } }' "https://www.webjars.org/create?webJarType=bowergithub&nameOrUrlish=[GITHUB_REPOSITORY_URL]&version=[GITHUB_VERSION]"

In this case you will have to deploy it yourself.

XML

<repositories>
    <repository>
        <id>webjars</id>
        <url>https://dl.bintray.com/webjars/maven</url>
    </repository>
</repositories>

Step 2. Creating the Java Integration

While you can start from scratch and do all the things manually, it’s easiest to start with the component project available at https://vaadin.com/start/v10-component. This will give you a project with Flow dependencies, import for the webjar for the selected component and a stub Java class for your web component integration. It also contains a Maven profile which will handle all things needed to deploy it to Vaadin Directory.

As an example, if you create a starter project for https://github.com/PolymerElements/paper-slider, the relevant parts of the generated project is

XML

<dependency>
    <groupId>org.webjars.bowergithub.polymerelements</groupId>
    <artifactId>paper-slider</artifactId>
    <version>2.0.6</version>
</dependency>

This includes the webjar for paper-slider, containing all needed HTML/CSS/JS.

XML

<profile>
    <id>directory</id>
    …
</profile>

This profile, activated as mvn clean install -Pdirectory, produces a zip package you can upload to https://vaadin.com/directory

The main component file src/main/java/…​/PaperSlider.java:

Java

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

The name of the HTML element is defined using @Tag("paper-slider") and the HTML import for the component is defined using @HtmlImport("bower_components/paper-slider/paper-slider.html"). The format for the HTML import should always be bower_components/abc/def.html even though webjars do not actually contain a bower_components directory. This allows you to temporarily or permanently use Bower instead of webjars in the project, without changing your code. The Flow server automatically removes the bower_components part when serving contents from webjars.

The main test/demo Java class src/test/java/…/DemoView.java

Java

@Route("")
public class DemoView extends VerticalLayout {

The project is set up in a slightly unconventional way so it can be a single-module Maven project. The test folder is used for a test/demo application in addition to actual test files. When you run

sh

mvn jetty:run

in the project, it will deploy DemoView and show it at http://localhost:8080

Now you are set to create the Java API, for more details see Creating Java API for a Web Component

Step 3. Deploying the Add-on to Vaadin Directory

When you are satisfied with the API, you can make the add-on available to the world by deploying it into Vaadin Directory. You can create the Directory compatible add-on package using

sh

mvn clean install -Pdirectory

This creates a zip file in the target directory.

Go to https://vaadin.com/directory, log in or register, and upload this zip file. Be sure to write an overview for your add-on to let others know what you can do with it, what browsers it supports etc. Then publish it and others can take your add-on into use by copying the dependency information from the add-on page in the directory.