Use Lit templates insteadLit templates are recommended. Polymer templates are available in the next long term supported Vaadin version (LTS), but they are deprecated.
When to Use Polymer Templates
Polymer templates work best:
In simple, static views: where the view itself does not change when the data does.
When you need absolute control over the DOM.
For example, a Polymer template is a good choice for a simple login component, because login views are typically simple (with only a few UI controls) and require precise styling. In this instance, it is easier to use a template to build and maintain the view, than to use the Java API.
Apps or views that require offline functionality are another good example where a template is preferable. Templates allow you to define any logic you like on the client side and to serve the necessay content, without dependency on the server.
Polymer templates do have certain limitations. See Known Limitations of Polymer Templates below for more.
When to Use Java Components
The traditional way of building UIs in Vaadin is to use the Java API. This works very well for complex and dynamic UIs where the view structure changes depending on the data that is viewed.
The benefits of using the Java API include:
ComponentAPI: This allows you to use inheritance to easily create and modify your own custom components.
ElementAPI: This is a lower-level API that gives you more control over the DOM than ever before.
All Java code is completely type-safe: The risk of typos or other inadvertent mistakes is greatly reduced because the code is compiled before use.
The disadvantage of this approach is that it is harder to get a structural overview of the resulting view from the code. In addition, although modifying the DOM is possible, it is not as easy as simply writing HTML in a template.
Known Limitations of Polymer Templates
PolymerTemplate API has intentional limitations that you need to be aware of before chosing to use it. These limitations are by design. The root cause of the limitations is that HTML templates are not processed on the server before being sent to the client. Because templates are not checked on the server:
Errors are only detected by the browser, or they show up as incorrect layouting etc.
By default, the server is not aware of, nor does it have any information about, the content of the template (for example the attributes used by a component). This means that many getter methods return the incorrect value, because the client never sent them to the server. While it is possible to add synchronization of components, data, and events, it is not available by default.
To understand this behaviour, assume using a
vaadin-gridin a template, for example. In the template itself, you can configure the
Grid, add columns and add data. However, if you use the
@Idannotation to bind the Grid in the associated Java file, you will soon run into issues. This is because on the server (in the Java file), the
Gridobject is not aware of anything configured (such as the columns) in the template.
You can add components and a DOM to a template structure, but you cannot remove anything present in the original template. However, overriding component properties does work. For example, you can add an empty
Grid to a template, bind it using the
@Id annotation, and add columns and data from Java code.
Effectively, this means is that you need to make a choice as a developer to either:
Use the Java API for components, or
While combining these options is possible, there are severe limitations to what you can do from the server API.
You can still combine views made with the
PolymerTemplate API with views created with the
Component API in your application to reduce your total development effort. In this way you can, for example, create views that work offline with views that do not.