Creating a Simple Component with Polymer Templates
Note
|
Use Lit templates instead
Lit templates are recommended. Polymer templates are available in the next long term supported Vaadin version (LTS), but they are deprecated.
|
In this section, we demonstrate how to create a simple component using only the PolymerTemplate
API.
Our example:
-
Creates a simple view that allows the user to input their name and click a button for a response.
-
Uses standard Polymer 3.0 features. See Polymer Library 3.0 to learn more.
Creating the Template File on the 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.
Example: Creating the hello-world.js
JavaScript Polymer template file.
import {PolymerElement,html} from '@polymer/polymer/polymer-element.js';
import '@polymer/paper-input/paper-input.js';
class HelloWorld extends PolymerElement {
static get template() {
return html`
<div>
<paper-input id="inputId" value="{{userInput}}"></paper-input>
<button id="helloButton" on-click="sayHello">Say hello</button>
<div id="greeting">[[greeting]]</div>
</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 is used to reference this module. The tag name should contain at least one dash (-
). For example,hello-world
is a valid tag name, buthelloworld
is not. -
The template contains two bindings:
[[greeting]]
is a one-way binding and{{userInput}}
is a two-way binding. -
An event handler,
sayHello
, is triggered on ahelloButton
click. -
No model is specified: it will be propagated automatically from the server side.
-
The imported dependencies are:
-
PolymerElement
(from the Polymer library): This is the required superclass of all Polymer templates. -
paper-input
Polymer component: You can use any component you like, for example the VaadinTextField
. -
html
for inline DOM templating.
-
Note
| This documentation covers Polymer 3 and npm in Vaadin version 14+ only. Earlier Vaadin versions support Polymer 2, HTML imports, and the Bower package manager. You can still use these components in Vaadin 14, if you work in the special compatibility mode. See the Vaadin 13 documentation for how to build client-side components with Polymer 2 and HTML imports. |
Working on the Server Side
Creating the Java Template Class
To use the client-side JavaScript template on the server side, you need to create an associated Java class that extends the PolymerTemplate
class.
Example: Creating 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<HelloWorldModel> {
private static final String EMPTY_NAME_GREETING = "Please enter your name";
/**
* Creates the hello world template.
*/
public HelloWorld() {
setId("template");
getModel().setGreeting(EMPTY_NAME_GREETING);
}
@EventHandler
private void sayHello() {
// Called from the template click handler
String userInput = getModel().getUserInput();
if (userInput == null || userInput.isEmpty()) {
getModel().setGreeting(EMPTY_NAME_GREETING);
} else {
getModel().setGreeting(String.format("Hello %s!", userInput));
}
}
}
-
The
@Tag
annotation name matches the return value of theis()
function (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 thehello-world.js
template class by specifying the relative path to the JavaScript module in thefrontend
folder in the project root. You can import multiple JavaScript resources using the@JsModule
annotation, if needed. -
The
@NpmPackage
annotation declares a dependency to thepaper-input
npm package:@polymer/paper-input 3.0.2
. This annotation can be used to declare a dependency to any npm package. -
The
@EventHandler
annotation defines the event handler called by the template click hander. Specifically, it defines thesayHello
method that is called from the client side and triggered by ahelloButton
button click. The method name is used to map function calls between the JavaScript template and the Java class.
Creating a Model Class
Our example also needs a model class.
Example: Creating the HelloWorldModel
model class.
/**
* Model for the template.
*/
public interface HelloWorldModel extends TemplateModel {
/**
* Gets user input from corresponding template page.
*
* @return user input string
*/
String getUserInput();
/**
* Sets greeting that is displayed in corresponding template page.
*
* @param greeting
* greeting string
*/
void setGreeting(String greeting);
}
-
The model class describes all properties passed to the
html
template and used on the client side. -
It is a simple Java interface that:
-
Extends the
TemplateModel
interface. -
Defines getter and/or setter methods for properties.
-
-
To use a model, you need to specify it when extending the
PolymerTemplate
class. It is not necessary to create a model object yourself, because Vaadin handles this for you. All you need to do is create the interface. -
You can access the model instance using the
getModel()
method inside the template Java class.
Using the Polymer Template
You can now use the HelloWorld
component in the same way as any other component.
Example: Using the HelloWorld
component in a Java class.
HelloWorld hello = new HelloWorld();
Div layout = new Div();
layout.add(hello);
Note
|
Some browsers, like IE11 and Safari 9, do not support ES modules. To ensure that your component works in these browsers, you can configure this in the vaadin-maven-plugin in your pom.xml . See Deploying to Production for more.
|
791975C0-1AB2-4B8D-BDE1-8DFDDD680AEE