Freemarker, not just another template language

This is the first in a series of blog post about how to use Freemarker in portlet views and also in Liferay WCM and themes. Some of the topics I will discuss in this and coming blog posts are:

  • How to switch to Freemarker for portlet views and still have accsess to JSP taglibs, using Spring Portlet MVC.
  • Using custom Freemarker Template Loaders for reading template files from outside of the portlet.
  • Creating a Freemarker Template Loader for reading templates from Liferay’s Document Library.
  • Creating a Freemarker Template Loader for reading templates from different repositories using CMIS, in my case I use Alfresco as the repository.
  • Using Liferay Sync together with the Liferay Document Library Template Loader for seamless view template editing.

Freemarker is a great template language with a lot of neat built-in functions. Therefore it is nice to see that it is so easy to change template language from JSP to Freemarker in a portlet when using Spring Portlet MVC. You can even use the same taglibs as in JSP in Freemarker. In that way you can develop your views with the same richness and also have access to Freemarker’s built-in functions for extra convenience.

All that is needed for you to use JSP taglibs in Freemarker is this small code:

<#assign liferay_ui=JspTaglibs["/WEB-INF/tld/liferay-ui.tld"]>

Now you use ”liferay_ui” in the same way as you would have used ”liferay-ui” in JSP:

<@liferay_ui.message key="liferay-message-key" /> VS <liferay-ui:message key="liferay-message-key"/>

When using Spring framework with your Liferay portlet you only need to change the view resolver bean in applicationContext.xml to use Freemarker instead of JSP, in order to make it work. Just create a freemarker config bean, specifying templateLoaderPath to a similar path where you usually have your JSP’s. Then, instead of using the regular InternalResourceViewResolver, you use org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver.

Here is an example how the applicationContext.xml can look like:

 <bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer" p:templateLoaderPath="/WEB-INF/freemarker/" />

<bean id="viewResolver" class="org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver">
    <property name="cache" value="true" />
    <property name="prefix" value="" />
    <property name="suffix" value=".ftl" />


But there is another great feature with Freemarker, namely that you can use a Template Loader to load your template from outside of the portlet. Freemarker has developed a FileTemplateLoader and a URLTemplateLoader that can be used to either get the template from a file in a specified directory or from a URL. Besides that, you also have the opportunity to create your own custom TemplateLoader that reads a template from a source of your choice.

To manage this kind of template loading you need to do some changes in applicationContext.xml. First you need to create a freemarkerTemplateLoader bean which should point to your custom template loader. Also you need to create a freemarkerTemplateLoaderList bean where you specify the template loaders which should be used, in our case a reference to the freemarkerTemplateLoader bean. Then you need to change the Freemarker config bean we created earlier so that it uses the newly freemarkerTemplateLoaderList bean instead.

The applicationContext.xml could look something like this when using a custom template loader:

 <bean id="freemarkerTemplateLoader" class="com.monator.freemarker.service.FreemarkerTemplateLoader" />
<bean id="freemarkerTemplateLoaderList" class="java.util.ArrayList">
            <ref bean="freemarkerTemplateLoader"/>
<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer" p:preferFileSystemAccess="false" >
    <property name="preTemplateLoaders" ref="freemarkerTemplateLoaderList" />


As stated in the beginning of this blog post I have created a template loader that reads a template from the Document Library in your Liferay Portal in the same way as I described above. More detailed information on how it works and how it was done is presented in a later blog post.

So there you have it! How you easily can use Freemarker instead of JSP in your portlet and how to use you own custom template loader for reading Freemarker templates from your source of choice. Now this isn’t stopping at just portlets, you can also use Freemarker as a template language instead of Velocity for Liferay themes as well. Mika Koivisto has an excellent blog post on how to do this: The same goes for WCM templates, Liferay supports Freemarker as a template language there also. With all of these combined one could get a homogeneous template language to use throughout the whole portal.

Trackback URL:

Liferay on Twitter

What are people saying about Liferay on Twitter?