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.

Note
It is only in very special cases that you need Bower or benefit from using it. In most cases it is quicker and easier to use webjars.

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/

Note
Many web component repositories tag versions using a v prefix. This is not included in the Maven version.
Note
All group and artifact ids are lower case, regardless of the GitHub name casing.

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:

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.

Note
You do not have to be the author of the component or owner of the repository to deploy a webjar. You can deploy anything publicly available in GitHub
Note
The webjar is immediately deployed to https://dl.bintray.com/webjars/maven/org/webjars/bowergithub/ and later synchronized to Maven central. Add dl.bintray.com in your pom.xml to be able to use it immediately:
<repositories>
    <repository>
        <id>webjars</id>
        <url>https://dl.bintray.com/webjars/maven</url>
    </repository>
</repositories>
Note
If you create a web component, never ever move the tag after a release or the webjar contents will not match the contents of the GitHub release tag, which is used by Bower.
Note
webjars.org contains "Bower Original WebJars" and "Bower GitHub WebJars". Always use "Bower GitHub WebJars", the other, deprecated version is not supported by Flow.

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

<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.

<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:

@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

@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

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

Note
Some web components will not show any UI when they are just added as empty tags to the page. If the demo view is empty, check first using the browser inspector that all files were found (no 404s) and then check if you need to configure the component in some way to show up.
Note
While the project setup is easy to use for development/testing, it does not allow you to easily produce a demo war file for deployment. It’s usually better to create a separate project (or convert the project into a multi-module project) for this as the "demo" files included in the addon itself tend to be more test UIs and a demo should be aimed at the end user.

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

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.

Note
The metadata used by Vaadin Directory is defined in assembly/MANIFEST.MF, based on the project’s metadata. If you do changes to the project such as removing <name></name>, make sure you update the metadata.