Introduction

Freemarker is a powerful Java template engine. It can be used to generate basically anything, from HTML pages, configuration files, e-mails, or anything else. All you need to do is define your template, use Java to prepare the data, and use the Freemarker engine to process your data with the given template to produce the output you need. This tutorial will focus on how to configure Freemarker on a Spring Boot 2 application. We will use a simple Freemarker template to keep our example as easy as possible

 

Adding the required dependencies

We will use Maven to do our dependency management in this example. Spring Boot provides a convenient way to add the needed Freemarker dependencies. All we need to do is to import the “spring-boot-starter-freemarker” in our Pom.xml as shown below:

 

If your project does not have the Spring-boot-starter-parent as the parent project, then just add a dependency on the Freemarker library directly.

Laying the ground work

For our example, we will use a simple data structure to transfer the data to the Freemarker template. Say hello to the Post class:

 

We would also need to create an ftl template to process our Post objects. In this example we will create a very simple ftl file that will be used to generate html outputs. The ftl file looks a lot like an html file.

 

Here, post.title, post.description and post.content refer to the inner members of a post object. In this example, we will call the file “blogpost.ftl” and place it in our application’s resources folder, in a new folder called templates.

Configuring Freemarker using the FreeMarkerConfigurer

The next step would be to tell FreeMarker where we our templates our located. The FreeMarkerConfigurer is a configuration bean from Spring used to configure different settings of Freemarker, such as the default location of the .ftl templates, the default file encoding format and lots of other things. For this, let us create a configuration class called “BeansConfig” where we define our FreeMarkerConfigurer:

 

In our example, we pick up the templates from the classpath. It is of course possible to pick up the templates from a specific place in the filesystem instead. That may be more convenient in a production environment as we wouldn’t need to rebuild and re-start our Spring boot application just for making modifications in the templates.

 

If you would like to learn more about configuring Spring beans, then please check out our post here

 

If you would like to have a solid knowledge foundation about Spring, then I would recommend checking out the book “Pro Spring 5: An In-Depth Guide to the Spring Framewrk and Its Tools”.  The book provides the essential knowledge you need to be a professional Spring software engineer, while also keeping it relevant to newer version of Spring and JDK 9+.  You can check out more information about the book and the price in the link below.

 

 

Processing templates and writing the output

As you may have noticed, we defined another bean called the “FreemarkerTemplateWriter”. This is a custom bean which we created for our application to convert a “Post” object into an html file using Freemarker.

The Freemarker template engine can be fed with data using Java maps. Here, we create a HashMap and we insert a post object that is accessible with the key “post”. In the template .ftl files, we need to make sure that we access objects using their key in the map. Therefore, we used “${post.content}” to access the content member of the post object. We also used a FileOutputStream and an OutputStreamWriter to write the output. However, the output can be directed to any type of Writer, depending on the purpose of the application.

Some might argue that the OutputStreamWriter is outdated and we should use the new Writers from Java.NIO. However, as of JDK 8, there is no way of explicitly specifying the charset of a an NIO FileWriter. If this is not done, then Java will just use whatever charset it detects on your operating system. This might cause issues with non-ASCII characters displaying incorrectly in the resulting html files. Here we configured our good old OutputStreamWriter with the UTF-8 Charset.

Notice how we used the freeMarkerConfigurer bean to get our “blogpost.ftl” template. We need to go through the configuration in order to obtain the required template. Once we have it, we can call the template.process method in order to process the template with the given data. Our program will write a new html file with the post title as the file’s name. The whole process can be summarized in the following diagram:

The Freemarker engine needs three components. A template, a medium to write the output, and the data with which to process the template

 

Let us try out our program by triggering our FreemarkerTemplateWriter bean. We will call the bean directly within the main method for testing purposes (do not do this in production 😉 )

 

Building and running this program will result in the creation of a file called “My great post.html”.

 

The output file as displayed on Firefox

 

Conclusions

Our example is a simple illustration of what could be done with Freemarker and Spring. The output can be directed to a network stream and the data could be obtained from the database. Or the generated html files could be used in a Spring web MVC application for displaying database or other contents. This example is just a starting point for a really powerful framework!

 

If you are just getting started with Spring boot, then I would suggest that you read up more about it in the book “Learning Spring Boot 2.0” by Greg Turnquist. The book covers Spring boot basics and provides an overview of integrating important technologies such as AMQP messaging and REST into your application. You can find out more info about the book and the price in the link below.

 

 

If you like this content, then please support us by clicking that twitter follow button at the bottom of the page in order to be notified of our latest updates 😉