Freemarker● Introduction● Core features● Java part example● Template example● Expressions● Builtins

● Assigning value● Conditions● Loops● Macros● Import● Include

http://freemarker.sourceforge.net

What is Freemarker?

● Freemarker is a template engine● It is used to generate text output ● Example: HTML, XML, email, SQL, Java

code● Programmer prepares environment in Java ● Designer writes template referencing the

environment● Freemarker produces output

Core Features

● Powerful template language● Versatile data model - object wrappers● Internationalization / localization ready● Configurable and extensible● Generic - output goes to any Writer● Templates can be loaded from file, jar,

web, db ..● XML, Ant and Jython support

Java Part - Environment

Person person = new Person(1234);

person.setName("Jon Smith");

List phones = new ArrayList();

phones.add("333-5555-777");

phones.add("899-379-973");

person.setPhones(phones);

Map env = new HashMap();

env.put("PERSON", person);

Java Part - Configuration

Configuration config = new Configuration();

config.setObjectWrapper(BEANS_WRAPPER);

config.setOutputEncoding("ISO-8859-2");

config.setDirectoryForTemplateLoading(templates);

config.setSetting("number_format", "0");

config.setSharedVariable("TODAY", new Date());

config.setTemplateExceptionHandler(DEBUG_HANDLER);

Java Part - Process Template

Template template = config.getTemplate("person.ftl");

FileWriter writer = new FileWriter("person.txt");

template.process(env, writer);

writer.close();

Template Example

Dear ${PERSON.name},

you have successfully registered with account id

${PERSON.id}. You have set following contact

phone numbers:

<#list PERSON.phones as phone>

${phone}<#if phone_has_next>, </#if>

</#list>

${TODAY?string.medium}, Prague

FTL Expressions

● Expressions are usually surrounded by ${}● Variable is accessed by its name ${TODAY} ● Support for JavaBean properties, map keys

and collection indexes ${PERSON.phones[1]}

● Arithmetics: +, -, *, /, %, floating point supported

● Logical operations: &&, ||, !, ==, !=, <, >, <=, >=

● Sequence slices: ${PERSON.name[2..]}

FTL - Built-ins

● Function appended after expression with ? char● Undefined: default, exists, if_exists, has_content● String: html, xml, url, left_pad, right_pad,

length, split, replace, index_of, matches, word_list

● Sequence: first, last, reverse, size, sort● Hashes: keys, values● XML: parent, children, root, ancestors,

node_type

FTL - Assigning Value

● <#assign name=value [in namespace]> ● <#assign name>value</#assign>● Possible to create/overwrite top level

variable in specifed (or default) namespace.

<#assign step=2 iterate=PERSON.phones?exists>

<#assign colors = ["red", "blue", "green"] >

<#assign map = {"name":"John", "age":25}>

FTL - Conditions

● <#if expression>, <#elseif expression>, <#else>

● Expression must evaluate to boolean● There is no ${} inside directive tags● <#if> is pair tag, it must be closed● Character < must be escaped or surrounded

by ()

<#if (1<3)>No<#elseif (2<3)>No<#else>Yes<#/if>

● switch, case, default, break directives supported

FTL - Loops

● <#list sequence as item>, <#break>● Iterates over each element in sequence● Local variable item is introduced within

tags● Variables item_has_next and item_index

are available

<#list PERSON.phones as phone>

${phone_index}. ${phone}

</#list>

FTL - Macros

● <#macro>, <#return>, <#nested>● Macro is a repetitive template fragment● Default values, variable number of

parameters● Parameter passing by name or positional

<#macro table size=“0“><table border=“${size}“>

<tr><td><#nested></td></tr></table></#macro>

<@table size=“2“>Hello</@table>

FTL - Import

● Imports given library into the namespace

● Namespaces allows reusability without conflicts

<#import "v1/macros.ftl“ as lib>

<#import "v2/macros.ftl“ as lib2>

<@lib.showCopyright name=“Acme inc.“ />

<@lib2.showCopyright link=true />

FTL - Include

● Include is used to merge specified template

● Parent directories may be searched

<#include "*/header.ftl“>

wap/cz/header.ftl, cz/header.ftl, header.ftl● Localization support - like

ResourceBundles

<#include "header.ftl“>

header.ftl_cs_CZ, header_cs.ftl, header.ftl

FTL - XML support

● You can parse XML or wrap DOM tree

root.put( "doc", NodeModel.parse(file)));

● You can access elements by name, attribute with @

${doc.invoice.person.name}

<#list doc.invoice.item as item>

${item} - ${item.@price} USD

</#item>

● Declarative support available via <#recurse>