Documentation

Documentation versions (currently viewingVaadin 24)

Templates

How to build views declaratively using templates.

In addition to imperative Java code, you can build views declaratively using templates. The components in such a template can be bound directly to data items.

In Vaadin, you have different options for how you build your views:

  1. Build your views purely with Java

  2. Define the layouts of your views declaratively and implement the UI logic in Java

  3. Build your views purely client-side with TypeScript and LitElement

These ways to build views can be mixed and matched within an application. All Vaadin components are available through the Java API and declaratively in HTML. The most appropriate option depends on your use case and preferences. This chapter describes the second option: how to build your UIs declaratively, while implementing the logic in Java.

Benefits of Using Templates

Defining the layout of a view separately from its logic results in clear, maintainable code. It makes it easier to see how the view is defined and where it’s updated. HTML templates are a robust way of defining the UI structure, whereas Java is a great way to define the logic of the view.

Vaadin has support for two declarative template languages: Polymer and LitElement. The LitElement library is the successor to the Polymer library. LitElement is the recommended template language for building new templates for your Vaadin applications. The LitElement template language is lightweight, more focused, and more future-proof.

Vaadin can refer to and access components defined by a template from Java. When you give unique IDs to components in the template, any component with an ID can be accessed through the Java API to configure the logic further. You can add Java-only components such as compositions to a template by giving a layout an ID in the template and adding the component in Java code.

For example, <vaadin-button id="my-button">Press me</vaadin-button> can be accessed with @Id("my-button") Button button; in Java.

The framework parses the elements and their attributes inside a template to make the initial state of each mapped server-side component consistent with the attributes set in the template.

For instance, consider a template containing the text field <vaadin-text-field id="name-field" placeholder="Enter name"></vaadin-text-field>, which is mapped as the class member @Id("name-field") TextField nameField in Java. After the server-side component is created, nameField.getPlaceholder() returns the placeholder text ("Enter name") immediately.

Declarative layouts are a robust and maintainable way of defining views. This is why Vaadin Designer, the visual tool for building UI for Vaadin applications, uses them as its format.

Known Limitations of Templates

The template API has limitations that you need to be aware of before using it. See Template Limitations for details.

Separating Structure and Logic

Try to only define things that don’t change in the template, and leave all the dynamic parts to Java. As an example, in the template you can have attributes that never change, captions for components like Button and TextField that always stay the same, or styling for the view. For instance, if the caption of a Button changes depending on user interaction, then leave it empty in the template and define the initial value in Java.

With Grid, defining columns may seem like a static part, but columns and data are strongly related. When using vaadin-grid inside a LitTemplate, the column configuration and driving of data must happen from the server-side Java code.

See Creating a Component Using Templates for a full example with an HTML template and Java logic.

Topics

Template-based Components
How to create a component using only the Template API.
Binding to Components
How to use the @Id annotation to reference a JavaScript LitElement template.
Combining with Binder
How to create a fully functional template-binder view.
Sub-Templates
How to create a parent LitElement template that includes a child LitElement template.
Adding Server-side Components
How to add server-side components to templates.
Styling
How to add component-specific scoped styles directly in the static styles template property.
Detecting Component Mappings
How to detect whether a component is part of a template.
Limitations
A list of limitations of Template.
Polymer Templates (deprecated)
Polymer support is deprecated; use Lit templates instead.