Using FreeMarker Macros in Liferay Web Content - Part 1

Liferay supports using FreeMarker as a web content template language. There are many things I really like about FreeMarker and use it whenever possible. Macros are one of those features, as you can create libraries of routines you can use over and over. But it’s not apparent where to place those libraries to get Liferay to recognize them and use them.

There is a setting in portal.properties where you can specify macro libraries

1
2
3
4
5

#
# Input a list of comma delimited macros that will be loaded. These files
# must exist in the class path.
#
freemarker.engine.macro.library=FTL_liferay.ftl as liferay

but, unfortunately if you do, they are not recognized by WCM templates.

So it looks like we need to find a way to put them somewhere that the built in template loaders will find them. The comment above is a provides the hint of where they need to be.

These files must exist in the class path.

So even though we can’t specify them in that property, we just need to get them into the class path somewhere.

Hooks to the rescue!

We can create a hook to deploy our macro library files somewhere in the class path. And while most people talk about using a hook for custom jsps, any file can be deployed by a hook.

1
2
3
4
5
6

<?xml version="1.0"?>
<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 6.1.0//EN" "http://www.liferay.com/dtd/liferay-hook_6_1_0.dtd">

<hook>
  <custom-jsp-dir>/custom_files</custom-jsp-dir>
</hook>

Like a typical jsp hook, I just set the directory name for where the files will be added/replaced. In my case I used custom_files instead of custom_jsps because I’m not using jsps.

Where you put them in the class path is up to you, I put them in /WEB-INF/classes/freemarker/macros

I’ve created a hook in the blog files project called freemarker-macros-hook for you to use as a starting point.

Build and deploy your hook and verify that the library got deployed where you expected it to.

In the next part, we’ll actually use the mylib.ftl and see how this all works.

(make sure you use the mylib.ftl in the project if you plan to move on to part 2)