Home > Frontend, Java > Thymeleaf: create page templates for web and non-web environments

Thymeleaf: create page templates for web and non-web environments

Most likely you have found yourself in the following situation: you’re at the start of new web application project and one thing you need to take care of is the layout. Problem is that you can build static HTML templates with dummy data, but then you have to (manually) convert these into JSP. When you don’t have a running system you don’t have any choice but to make static HTML, or model templates a different way. Because of this the main problem will be on how to update the system given this (updated) design. This post will described the Thymeleaf framework which addresses these issues and will allow static templates to run unchanged in a web application.

Templates the right way

Regardless if you have a running system or not it would be nice to be able to have basic static HTML templates which can run offline and in a running online system without too much hassle. Basically templates which:

  • can be easily updated with the stylesheets/updates of the designers
  • can be easily integrated into a running web application as soon as the application is set up (including wired beans, form validation etc.)

In this post I will introduce a template engine which addresses both points.

Thymeleaf – a full HTML 5 oriented template engine

Thymeleaf is by default a XML/XHTML(1.0 & 1.1)/HTML5 template engine for Java which is extensible for other formats. The project started in 2011 and released version 1.0 in July. Version 2.0 was released in 2012 (also in July) and almost every month after that a new (build) version has been released. The main goal of the framework to provide a well-formed way of creating templates. Thymeleaf is different to other template engines like Velocity and jFreeMarker as it uses natural templating. The Thymeleaf template syntax does not break the document’s structure, and the template remains a well-formed XML document. It does so by using HTML attributes only. Templates can serve as working prototypes, and Thymeleaf will take care of replacing static values at run-time. Thymeleaf has a lot of HTML attributes which have a JSTL counterpart (for example for loops and conditions). One of the main advantages of the framework to run templates online is: Spring WebMVC 3 integration.

Template interpretation & conversion

Thymeleaf uses a XML parser and a DOM processor under the hood for processing the templates. By default HTML5 is well supported as long as the template is well-formed XML. If it is not (for example due to legacy integration) the template will first be converted to well-formed XML by use of tag balancing. The DTD definition of a template need to be set as the Thymeleaf DTD which defines all custom HTML attributes. This makes all the attributes known and therefore the template a complete well-formed XML. Once a template is processed all th:* attributes are removed and the DTD declaration will be substituted by a standard XHTML 1.0 Strict one.

Source example

In this example I will show you a basic source code structure and give some pointers in order to give you an idea of this framework.

 thymeleaf/layout :: headerFragment">
 <!-- replaced with fragment content -->
 <!--—- '<span class="hiddenSpellError" pre=""-->thymeleaf/layout' refers to /thymeleaf/layout.html on the filesystem -->


 <div th:include="thymeleaf/layout :: menuFragment">
 <div th:if="${not #lists.isEmpty(users)}">
     <tr th:each="book : ${books}">
      <td th:text="${book.title}">x</td>
      <td th:text="${book.author}">y</td>

The first thing to notice here is that this file is XHTML that can be correctly displayed by any browser. This because it does not include any non-XHTML tags. Browsers ignore all
attributes they don’t understand (for example th:include)
The only thing you need to add is a dedicated namespace (xmlns:th) in order to turn static html pages into dynamic views. All parts that require dynamic processing are prefixed with “th:”.
All JSTL counterparts can be implemented this way, like the th:if and th:each in the example above.
When creating a form for submitting data, the form element can be bound to command object (form backing bean) using the th:object attribute. Input, checbox, radiobutton and dropdown (th:field), dropdown, can be easily added to the form to map attributes of object. For validation the framework has methods for the #fields object for detecting (like ${#fields.hasErrors(‘datePublished’)}) errors and the th:errors attribute to show these.


Thymeleaf allows you to chop up html into fragments. This will allow you to separate logical ui blocks like menu’s to a separate fragment.
This can be done using the th:include attribute. When trying to run fragmented pages offline I found out that it did not work. Thymol, which is javascript-based is a working solution to perform fragment inclusion for static template preview. See the Thymol website for more details.

Other features

As mentioned before, one of the strengths is that the framework integrates well with Spring WebMVC 3.
You can define a separate view resolver so that Thymeleaf implemented code can run side by side already existing regular JSP based code.
Other features which are supported are:
– Full internationalization support, which is extensible.
– Configurable, high performance parsed template cache that reduces input/output to the minimum
– Automatic DOCTYPE translations — from template DTD to result DTD
– URL rewriting capabilities
– Integration with Spring Security 3.x, Spring Webflow and Play Framework 1.2


There is much more to it than I have shown you in this blog. Thymeleaf has excellent examples
and is well documented. It has three source projects which you can download in order to experiment with. These sources and documentation can be found in the documentation section of the Thymeleaf site .

Categories: Frontend, Java Tags: , , , ,
  1. No comments yet.
  1. 04/04/2013 at 14:12

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

Join 275 other followers