Custom FTL Macro Library in Liferay

Freemarker Macro Library Implementation

Overview

Liferay has an embedded freemarker library, which contains FTL macroses and functions to help with templates implementation. In this article we’ll review how out-of-the-box FTL Macro library works, and how to implement a custom one. 

Liferay FTL Library Review

Default liferay FTL library is exposed with a FTL_liferay.ftl file in the portal-template-freemarker module.

There is a FreeMarkerEngineConfiguration configuration, which references this library file and defines an alias (“liferay”) for it: 

@Meta.AD(

  deflt = "FTL_liferay.ftl as liferay", name = "macro-library",

  required = false

)

public String[] macroLibrary();

This configuration can be modified in System Settings -> Template Engines -> Freemarker Engine:

FTL_liferay.ftl file contains a lot of macroses and functions, which can be used in freemarker templates - for themes, widget templates or even fragments. 

For example, this macros defined for localization

<#macro language key>

${languageUtil.get(locale, key)}

</#macro>

can be used in a following way:

<@liferay.language key="page" />

Other macroses are used to render specific widgets, e.g.: <@liferay.breadcrumbs /> (for Breadcrumbs), <@liferay.search_bar /> (for Search Widget), etc.

For functions we can use expressions, e.g. ${liferay.max(2,3)} will return 3. 

Note: for using FTL library functions/macroses we specify the alias “liferay” defined in Macro Library configuration.

Custom Macro Library Implementation

Even though the default FTL Macro Library exposes a lot of helpful functions, they might not be enough for specific projects. In such cases we may proceed with a custom FTL Library.

First, we need to create a module with the following structure:

build.gradle:

dependencies {

  compileOnly group: "com.liferay.portal", name: "release.portal.api"

}

bnd.bnd:

Bundle-Name: LifeDev FTL Macro Library

Bundle-SymbolicName: com.lifedev.ftl.macro.library

Bundle-Version: 1.0.0

Fragment-Host: com.liferay.portal.template.freemarker

In bundle configuration we need to specify the Fragment-Host as com.liferay.portal.template.freemarker in order to export our custom library as part of Liferay’s module.

FTL_lifedev.ftl

This is the file where we can register our custom variables, macroses and functions (any file name can be defined, multiple macro library files can be created if needed). For this demo I registered  a function, which renders the copyright string:

<#-- Variables -->

<#assign currentYear = .now?string('yyyy') />

<#-- Functions -->

<#function copyright startYear>

   <#return '© LifeDev ${startYear} - ${currentYear} | All rights reserved' />

</#function>

After deploying the module, we need to register our FTL Macro library in the same way, as FTL_liferay.ftl is registered.

Here we registered our macro library with the “lifedev” alias.

Finally, you can use defined macroses and functions in your templates!

In our example code ${lifedev.copyright(2010)} will produce a label: © LifeDev 2010 - 2023 | All rights reserved

Enjoy 😏