Templates
In Vaadin, you have different options for how you build your views:
-
Build your views purely with Java
-
Define the layouts of your views declaratively and implement the UI logic in Java
-
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.