Docs

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

Docs

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.

Polymer (HTML) template support in Vaadin allows you to create pre-formatted HTML components (declarative layouts) that can be used from Java in the same way as any other component. Polymer templates give you full control over the appearance (look) of the DOM. You can use any Vaadin component in your design, as well as JavaScript logic, and even CSS. Declarative layouts have many benefits, but there are also disadvantages.

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.

  • When you want client-side logic (JavaScript) in your app.

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:

  • Component API: This allows you to use inheritance to easily create and modify your own custom components.

  • Element API: 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

The 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-grid in a template, for example. In the template itself, you can configure the Grid, add columns and add data. However, if you use the @Id annotation 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 Grid object 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

  • Put all your UI logic into the templates as JavaScript.

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.

37FBC7EF-CB5C-44D9-8A1D-168AD5027533