Integrating a Web Component

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.

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

In this case you will have to deploy it yourself.

Note	The webjar is immediately deployed to and later synchronized to Maven central. Add `dl.bintray.com` in your `pom.xml` to be able to use it immediately:

XML

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

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 , the relevant parts of the generated project is

XML

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

XML

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

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 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("")

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

in the project, it will deploy DemoView and show it at

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.

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

Go to , 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.