FreeMarker Template Language

The FreeMarker Template Language (FTL) is a declarative template language used by the FreeMarker template engine — a Java library for generating text output from templates and a supplied data model. Although FTL is most commonly associated with HTML page generation, it is general-purpose: FreeMarker is routinely used to produce configuration files, source code, email bodies, SQL, and any other text-based artifact that benefits from separating presentation from data.

FreeMarker is now an Apache Software Foundation project, distributed as Apache FreeMarker.

History & Origins

FreeMarker was started by Benjamin Geer in 1999 as an open-source Java template engine, originally hosted on SourceForge. Its earliest 1.x releases used a relatively simple custom syntax and a tag-oriented approach inspired in part by earlier template tools such as WebMacro.

In 2002, the project underwent a substantial rewrite for the 2.0 release. This version introduced the modern FreeMarker Template Language (FTL) with its angle-bracket directive syntax, a clean separation between the template author’s “view” of data and the application’s actual Java objects, and a parser generated with JavaCC. Many of the abstractions that distinguish FreeMarker today — the TemplateModel data-model interface, the configuration-driven object wrapping system, and the rich library of built-ins — date from this era.

Development of the 2.3 series began in 2004 and has continued, in remarkably steady fashion, ever since. Rather than producing a “FreeMarker 3.0” with a breaking change, the maintainers have generally preferred to evolve 2.3 incrementally while maintaining a strong commitment to backward compatibility.

In 2015, the project was donated to the Apache Software Foundation and entered the Apache Incubator. It graduated to a top-level Apache project in 2018, becoming Apache FreeMarker.

Design Philosophy

FreeMarker’s design has consistently emphasized a few principles:

1. Strict separation of concerns — A template should describe presentation only; it should not perform business logic. FTL deliberately makes it awkward to do “real” computation in templates, encouraging developers to prepare a clean data model in Java instead.
2. Tolerant data model abstraction — Templates work against an abstract data model, not against specific Java classes. The same template can be fed POJOs, Maps, JDOM nodes, JSON-like structures, or custom data wrappers without changing.
3. Predictable, side-effect-free output — FTL is declarative: a template, given the same data model and configuration, always produces the same output.
4. Output-format awareness — Modern FreeMarker is aware of the kind of output it is producing (HTML, XML, RTF, plain text, etc.) and applies appropriate auto-escaping by default in the ? (built-in) and interpolation syntax, helping prevent injection bugs such as XSS.

Key Features

Interpolations and Directives

FTL has two main syntactic constructs:

• Interpolations — ${expression} — substitute the value of an expression into the output, with type-aware formatting and optional auto-escaping.
• Directives — <#if ...>...</#if>, <#list ...>...</#list>, <#assign ...>, <#macro ...>, etc. — control the structure of the output.

User-defined directives use the <@name ... /> syntax and are typically defined as macros.

Built-ins

FreeMarker provides a large library of built-ins, applied with the ? operator, for working with values:

${name?upper_case}                  <#-- string transformation -->
${price?string.currency}            <#-- locale-aware formatting -->
${items?size}                       <#-- collection size -->
${html?no_esc}                      <#-- mark a string as already-escaped -->
${user.email!"[email protected]"} <#-- default value for missing data -->

Built-ins cover string manipulation, number and date formatting (with locale and time-zone awareness), collection operations, type introspection, and HTML/XML/JavaScript escaping.

Macros and Functions

FTL supports user-defined macros for reusable template fragments and functions for reusable expressions:

<#macro greeting name greeting="Hello">
  <p>${greeting}, ${name?cap_first}!</p>
</#macro>

<@greeting name="ada" />
<@greeting name="grace" greeting="Welcome" />

Macros may take positional or named parameters, default values, and nested content (via <#nested>), making them a flexible building block for component-style template design.

The Data Model

A FreeMarker template never operates directly on Java objects. Instead, the engine wraps incoming data through an ObjectWrapper into types defined by the TemplateModel interfaces (TemplateScalarModel, TemplateSequenceModel, TemplateHashModel, etc.). This indirection lets the same template run against many backing representations:

• Plain Java Maps and Lists
• POJOs accessed via reflection (BeansWrapper)
• DOM and JDOM trees (NodeModel)
• Custom data sources via user-implemented TemplateModel adapters

Output Formats and Auto-Escaping

Modern FreeMarker (2.3.24+) supports named output formats such as HTML, XHTML, XML, RTF, and plainText. Templates can be associated with an output format either by file-name suffix (e.g., .ftlh for HTML) or by configuration. When auto-escaping is enabled for an output format, interpolated values are escaped by default unless explicitly marked safe — a significant defense against XSS in HTML output.

Internationalization

FreeMarker has strong, built-in support for locale-sensitive formatting of numbers, currencies, dates, and times, driven by the configured Locale and TimeZone. Templates can also access localized message bundles through standard data-model conventions, supporting fully localized UIs without complex template logic.

A Small Example

A typical FreeMarker template combining an interpolation, a directive, and built-ins:

<#-- greeting.ftlh -->
<!DOCTYPE html>
<html>
<head><title>${title?html}</title></head>
<body>
  <h1>${title?html}</h1>
  <#if users?size == 0>
    <p>No users yet.</p>
  <#else>
    <ul>
      <#list users as user>
        <li>${user.name?cap_first} &mdash; joined ${user.joined?date}</li>
      </#list>
    </ul>
  </#if>
</body>
</html>

In Java, the template is processed against a data model:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setClassForTemplateLoading(getClass(), "/templates");
cfg.setDefaultEncoding("UTF-8");

Template tpl = cfg.getTemplate("greeting.ftlh");

Map<String, Object> data = new HashMap<>();
data.put("title", "Members");
data.put("users", users); // List of POJOs with name + joined fields

tpl.process(data, new OutputStreamWriter(System.out));

Evolution

FreeMarker has had a famously stable evolution:

• 1.x (1999–2001) — Initial open-source releases on SourceForge with a simpler, tag-style syntax.
• 2.0 (2002) — Substantial rewrite introducing FTL as it is recognized today, the data-model abstraction, and a JavaCC-based parser.
• 2.3 (2004 onward) — The long-lived stable line. Subsequent point releases have added features (macros, namespaces, output formats, auto-escaping, new built-ins, improved error reporting) while keeping templates broadly backward compatible.
• 2015 — Project donated to the Apache Software Foundation; enters the Apache Incubator.
• 2018 — Graduates to a top-level Apache project as Apache FreeMarker.
• 2.3.30+ (2020 onward) — Releases under Apache governance focus on bug fixes, security improvements, and incremental enhancements while preserving compatibility.

A “FreeMarker 3” with breaking changes has been discussed by the project repeatedly, but in practice the maintainers have prioritized continuity over revolution, and the 2.3 line continues to be the actively used release series.

Current Relevance

Although newer Java templating engines such as Thymeleaf have taken much of the mindshare for HTML rendering in modern Spring applications, FreeMarker remains widely deployed for several reasons:

• Stable, mature ecosystem — Twenty years of compatible releases mean that legacy FreeMarker templates generally still work, which is enormously valuable in long-lived enterprise systems.
• Excellent fit for non-HTML output — Because FreeMarker is text-oriented and not HTML-centric, it is a strong choice for generating emails, configuration files, SQL, and source code, where Thymeleaf’s HTML-parsing model is a poor fit.
• First-class Spring integration — Spring MVC and Spring Boot both ship support for FreeMarker as a view technology with very little setup.
• Code generation — Many code generators continue to use FTL, taking advantage of its expressiveness, predictable output, and strong support for whitespace control and output-format awareness.
• Apache stewardship — Being part of the ASF gives the project a stable governance model and clear long-term licensing under the Apache License 2.0.

Why FreeMarker Matters

FreeMarker is one of the longest-running successful Java template engines, and it played a significant role in establishing now-standard ideas: a strict separation between templates and business logic, a wrapper-based data-model abstraction, locale-aware built-ins, and output-format-aware auto-escaping. Its design directly and indirectly influenced how subsequent Java template engines and many code-generation tools approach the problem of producing text from data.

For Java teams that need a dependable, focused template engine — especially for non-HTML outputs or for long-lived applications where compatibility matters more than fashion — Apache FreeMarker remains a quietly excellent choice.