Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Integrating a Web Component

Web Components are a collection of web standards that allow you to create new HTML tags with custom names. Web Components can be reused and provide full encapsulation of styles and markup. See Introduction to Web Components for more.

To be able to use a Web Component in Vaadin you need:

  • To load the HTML/JS/CSS files needed by the component (see instructions below).

  • A Java API to configure the component and listen to events from it. See Creating a Java API for a Web Component for more.

The Web Component’s client-side files (typically JavaScript module files) are available using npm. Vaadin 14 and above (Flow 2.0 +) supports npm and automatically installs and uses npm packages, and serves the static files to the browser.

Since Vaadin 14.2 the pnpm tool can be used for frontend package management instead of the default tool npm. For switching between either npm or pnpm see more from differences between npm and pnpm sections. pnpm improves the package management in many ways, e.g. it allows to share the same packages between various projects and avoid downloading them every time for every project which also reduces the number of IO operations.

Integrating a JS Module into Vaadin

While you can start from scratch and do it all manually, the easiest way is to use the Vaadin Add-on Starter. This gives you:

  • A project with all the necessary dependencies.

  • An npm import for the selected component.

  • A stub component Java class for your Web Component integration.

  • A Maven profile that handles everything necessary to deploy the component to Vaadin Directory.

Example: Annotations in the Java component class for a starter project for the paper-slider Web Component.

@Tag("paper-slider")
@NpmPackage(value = "@polymer/paper-slider",
            version = "3.0.1")
@JsModule("@polymer/paper-slider/paper-slider.js")

  • The @Tag annotation defines the name of the HTML element.

  • The @JSModule and @NpmPackage annotations define the import of the JavaScript module.

Adding Front-end Files

If your component requires in-project front-end files, for example additional JavaScript modules, add them to the src/main/resources/META-INF/frontend directory so that they are packaged in the component JAR if you choose to make an add-on of your component.

Example: Using the @JsModule annotation to add a local JavaScript module.

@JsModule("./my-local-module.js")

When running mvn clean install, the vaadin-maven-plugin automatically installs the npm package in node_modules and imports the JavaScript module file into the document provided to the browser. In addition, if you run the Jetty web server from Maven (using mvn jetty:run), your project’s source code is monitored for changes to these types of annotations: any change to @NpmPackage or @JsModule annotations triggers installation of the referenced packages and hot deployment of your app, including the new JS module imports.

Understanding the Project Files

The project includes the DemoView component class at src/test/java/…/DemoView.java.

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

The project set up is slightly unconventional in order to allow it to be a single-module Maven project: it uses the test folder for both the demo application and for the actual test files. When you run mvn jetty:run in the project, it deploys DemoView and displays it at http://localhost:8080.

Your project is now set up and you can go ahead and create the Java API. See Creating a Java API for a Web Component for how to do this.

Note
 Some Web Components do not show a UI when they are added to the page as empty tags. If the demo view is empty, use the browser console to verify that all files were found (no 404 errors) and then check if the component is correctly configured. See Debugging a Web Component Integration for more.
Note
 While the project setup is easy to use for development and testing, it does not allow you to easily produce a demo WAR file for deployment. It is usually better to create a separate project (or convert the project into a multi-module project) for this purpose. The demo files included in the starter, are intended as test UIs, whereas your result should be aimed at the end user.
Note
 See Making a Component Add-on OSGi Compatible if you need to make your component OSGI-compatible.
Important
 If your project is configured as a multi-module project, for example because the base project is an older version or you have manually converted it, source monitoring does not work and changes to the component are not automatically reflected to your demo application.

Deploying the Add-on to the Vaadin Directory

When you are satisfied with the API, you can make the add-on available to everyone by deploying it to the Vaadin Directory.

To create a directory-compatible add-on package use:

mvn clean install -Pdirectory

  • This creates a ZIP file in the target directory.

To add your add-on to the Vaadin Directory:

  1. Go to https://vaadin.com/directory.

  2. Login or register.

  3. Upload the ZIP file.

  4. Write an overview for your add-on to let others know:

    • What it can do.

    • Which browsers are supported

    • Any other relevant information.

  5. Publish your add-on.

Users can use your add-on by copying the dependency information from the add-on page in the directory.

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

C3CD2665-F729-46B0-9D34-2DA5C88B3840