Documentation

Polymer support is deprecated. Use Lit templates instead.

Documentation

Create a Simple Component Using Polymer Template API

Polymer support is deprecated; use Lit templates instead.
Warning

Polymer support has been deprecated since Vaadin 18 (released in November 2020), in favor of faster and simpler Lit templates. The built-in support for Polymer templates has been removed and is only available as a commercial add-on. However, a free conversion tool is available to assist in converting Polymer templates to Lit.

Read more about setting up the commercial Polymer templates addon in the Upgrade Guide.

Creating Template File on Client Side

The first step is to create the Polymer JavaScript template file on the client side in frontend/src/hello-world.js. This file contains the view structure.

In the example, it shows how to create the hello-world.js JavaScript Polymer template file:

import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';
import '@polymer/paper-input/paper-input.js';
import '@vaadin/button';
import '@vaadin/text-field';

class HelloWorld extends PolymerElement {
  static get template() {
    return html`
      <div>
        <vaadin-text-field id="firstInput"></vaadin-text-field>
        <paper-input id="secondInput"></paper-input>
        <vaadin-button id="helloButton">Click me!</vaadin-button>
      </div>
    `;
  }

  static get is() {
    return 'hello-world';
  }
}

customElements.define(HelloWorld.is, HelloWorld);

This is the JavaScript ES6 module that defines a Polymer template. The is() function defines the name of the HTML tag that’s used to reference this module. The tag name should contain at least one dash (i.e., -). For example, hello-world is a valid tag name, but helloworld is not.

The imported dependencies are PolymerElement — from the Polymer library — which is the required superclass of all Polymer templates; vaadin-text-field, vaadin-button and paper-input components; and html for inline DOM templating.

Note
 The return statement in the render method needs to end with a semi-colon (i.e., ;) for the parser to find the template contents.

Creating Java Template Class

To use the client-side Polymer template on the server side, you need to create an associated Java class that extends the PolymerTemplate class.

You can see in the example here how to create the HelloWorld Java template class:

@Tag("hello-world")
@NpmPackage(value = "@polymer/paper-input", version = "3.0.2")
@JsModule("./src/hello-world.js")
public class HelloWorld extends PolymerTemplate<HelloWorld.HelloWorldModel> {

    /**
     * Creates the hello world template.
     */
    public HelloWorld() {
    }

    public interface HelloWorldModel extends TemplateModel {
    }
}

The @Tag annotation name matches the return value of the is() function (i.e., static getter) in the JavaScript template. This ensures that the tag name is the same on the server and the client.

The @JsModule annotation binds the Java class to the hello-world.js template class by specifying the relative path to the JavaScript module in the frontend folder in the project root. You can import multiple JavaScript resources using the @JsModule annotation, if needed.

The @NpmPackage annotation declares a dependency on the paper-input npm package: @polymer/paper-input 3.0.2. This annotation can be used to declare a dependency on any npm package.

BF7B633A-FD34-4762-A82E-D5B921B0F042