Using FreeMarker Macros in Liferay

Introduction

Efficiency and maintainability are important when creating dynamic, content-rich websites in Liferay. FreeMarker Macros is a commonly ignored yet extremely powerful feature that helps achieve both objectives. By allowing developers to produce reusable templates for rendering user interface elements, macros help to maintain clean, modular, and easily maintainable code.

This article will explain what macros are, their benefits, and how you can improve your development process by using Liferay's built-in macros or even making your own.

What Are FreeMarker Macros?

A macro in FreeMarker is a reusable block of code that you define once and call repeatedly as needed, much like a function in programming.

You can define a macro and just call it, saving you the trouble of copying and pasting the same HTML structure or complicated logic across all of your templates. This results in:

Cleaner templates

Easier maintenance

Less repetition

Better readability

Example of a simple macro:

				
					[#macro product_card is_premium]
    <div class="card_box">[#if is_premium]<span></span>[/#if]</div>
[/#macro]

<div class="container">
    <h2>Next-gen tech for everyday living</h2>
    <div class="grid">
        [#list products as product]
            [@product_card product?is_odd_item /]
        [/#list]
    </div>
</div>

<div class="container">
    <h2>Best Sellers</h2>
    <div class="grid">
        [#list products as product]
            [@product_card false /]
        [/#list]
    </div>
</div>

Defines a reusable FreeMarker macro called product_card that accepts a boolean parameter is_premium. You can define a macro with multiple parameters and access them by their names. The parameters follow the same order as defined in the macro. Additionally, you can access specific parameters by using key-value pairs when calling the macro — for example: title="Liferay".

This example outputs:

Built-In Macros in Liferay

Liferay takes macros even further by providing built-in macros that you can use right away in your FreeMarker templates. These macros save you even more time by managing common UI patterns and integrating seamlessly with Liferay's backend.

Macro	Parameters	Description	Example
breadcrumbs	default_preferences	Adds a Breadcrumbs portlet with optional settings	`<@liferay.breadcrumbs />`
control_menu	N/A	Shows the Control Menu on the page	`<@liferay.control_menu />`
css	file_name	Links an external CSS file	`<@liferay.css file_name="${css_folder}/mycss.css"/>`
date	format	Displays the date in the user's local format	`<@liferay.date format="/yyyy/MM/dd/HH/" />`
js	file_name	Loads an external JavaScript file	`<@liferay.js file_name="${javascript_folder}/myJs.js"/>`
language	key	Prints a translated language key based on the current locale	`<@liferay.language key="last-modified" />`
language_format	arguments key	Formats a language key with custom arguments — for instance, using the key `what-is-x` with `Macros` would render as What is Macros.	`<@liferay.language_format arguments="${site_name}" key="what-is-x" />`
languages	default_preferences	Inserts the Languages portlet with optional settings	`<@liferay.languages />`
navigation_menu	default_preferences instance_id	Adds a Navigation Menu with customizable options	`<@liferay.navigation_menu />`
search	default_preferences	Displays a Search portlet with optional preferences	`<@liferay.search />`
search_bar	default_preferences	Embeds a Search Bar with optional settings	`<@liferay.search_bar />`
user_personal_bar	N/A	Shows the User Personal Bar for logged-in users	`<@liferay.user_personal_bar />`

Using Liferay's Built-In Macros

Liferay provides several built-in FreeMarker macros that make it easier to integrate UI components and dynamic content into your templates. Here are some of the most useful macros in Liferay:

				
					<!-- Displays a localized message based on the user's language settings -->
<@liferay_ui["message"] key="welcome-message" />

<!-- Inserts a Liferay-styled icon -->
<@liferay_ui["icon"] image="home" />

<!-- Renders a Liferay portlet inside a template -->
<@liferay_portlet["runtime"] portletName="com_liferay_site_navigation_menu_web_portlet_SiteNavigationMenuPortlet" />

<!-- Allows including another FreeMarker template within the current one -->
<@liferay_util["include"] page="/templates/footer.ftl" />

Note:

By default, FreeMarker macro calls in Liferay are namespaced with liferay (e.g., <@liferay.macro_variable_name />). The explicit variable name can be used to call custom macros that you create.

Best Practices for Using Macros

Give your parameters and macros meaningful names.
Combine similar macros into a single file.
To help others (or yourself in the future) understand what your macros do, document them.
When feasible, use built-in macros; they guarantee that your user interface complies with Liferay requirements.
One macro should do one thing well, so keep them small and targeted.

Conclusion

One useful tool that can completely change the way you work with Liferay is macros. You can create templates that are cleaner, faster, and easier to maintain by utilizing both Liferay's built-in macros and FreeMarker's macro functionality.

Whether you're building simple themes or complex web applications, understanding and mastering macros will greatly enhance your development efficiency.

Take some time to explore the macros Liferay already provides, and don't be afraid to create your own when needed. Happy templating! 😉

Byte Long