The template

The simplest template is a plain HTML file. When the client visits that page, FreeMarker will send that HTML to the client as is. However if you want that page to be more dynamic then you begin to put special parts into the HTML which will be understood by FreeMarker:

Anything not an FTL tag or an interpolation or comment is considered plain text, and will not be interpreted by FreeMarker; it is just printed directly to the output.

With FTL tags you refer to so-called directives. This is the same as with HTML tags (e.g.: <table> and </table>) you refer to HTML elements (e.g. to the table element). If you don't feel the difference then just consider that ``FTL tag'' and ``directive'' are synonyms.

Examples of directives

Though FreeMarker has far more directives, in this quick overview we will only look at three of the most commonly used ones.

The if directive

With the if directive you can conditionally skip a section of the template. For example, assume that in the very first example you want to greet your boss differently from other users; the name of your boss is Big Joe:

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>
    Welcome ${user}<#if user = "Big Joe">, our beloved leader</#if>!
  </h1>
  <p>Our latest product:
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>  

Here you have told FreeMarker that the ``, our beloved leader'' should be there only if the value of the variable user is equal to the string "Big Joe". In general, things between <#if condition> and </#if> tags are skipped if condition is false.

Note that I have used two syntactical elements that were explained earlier. On the left side of = I have referenced a variable, and on the right side I have specified a literal string. You can write things like this too (using the data model used to demonstrate hashes):

<#if animals.python.price < animals.elephant.price>
  Pythons are cheaper than elephants today.
</#if>  

With the <#else> tag you can specify what to do if the condition is false. For example:

<#if animals.python.price < animals.elephant.price>
  Pythons are cheaper than elephants today.
<#else>
  Pythons are not cheaper than elephants today.
</#if>  

This prints ``Pythons are cheaper than elephants today.'' if the price of python is less than the price of elephant, or else it prints ``Pythons are not cheaper than elephants today.''

The list directive

This is useful when you want to list something. For example if you merge this template with the data model I used earlier to demonstrate sequences:

<p>We have these animals:
<table border=1>
  <tr><th>Name<th>Price
  <#list animals as being>
  <tr><td>${being.name}<td>${being.price} Euros
  </#list>
</table>  

then the output will be:

<p>We have these animals:
<table border=1>
  <tr><th>Name<th>Price
  <tr><td>mouse<td>50 Euros
  <tr><td>elephant<td>5000 Euros
  <tr><td>python<td>4999 Euros
</table>  

The generic format of the list directive is:

<#list SequenceVar as variable>repeatThis</#list>

The repeatThis part will be repeated for each item in the sequence you have given as SequenceVar, one after the other, starting from the first item. In all repetitions variable will hold the value of the current item. This variable exists only within the <#list ...> and </#list>, and it does not overwrite any variables of the same name if they occur in the data model.

As another example, we list the fruits of that example data model:

<p>And BTW we have these fruits:
<ul>
<#list whatnot.fruits as fruit>
 <li>${fruit}
</#list>
<ul>  

Note that whatnot.fruits should be familiar to you; it references a variable in the data model.

The include directive

With the include directive you can insert the content of another file into the template.

For example, suppose you have to show the same copyright notice on several pages. You can create a file that contains the copyright notice only, and insert that file everywhere where you need that copyright notice. Say, you store this copyright notice in copyright_footer.html:

<hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i>  

And whenever you need that file you simply insert it with the include directive:

<html>
<head>
  <title>Test page</title>
</head>
<body>
  <h1>Test page</h1>
  <p>Blah blah...
<#include "/copyright_footer.html">
</body>
</html>  

and the output will be:

<html>
<head>
  <title>Test page</title>
</head>
<body>
  <h1>Test page</h1>
  <p>Blah blah...
<hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i>
</body>
</html>  

If you change the copyright_footer.html, then the visitor will see the new copyright notice on all pages.

Using directives together

You can use directives as many times on a page as you want, and you can freely nest directives into each other. For example this will list the animals and print the name of large animals with bold:

<p>We have these animals:
<table border=1>
  <tr><th>Name<th>Price
  <#list animals as being>
  <tr>
    <td>
      <#if being.size = "large"><b></#if>
      ${being.name}
      <#if being.size = "large"></b></#if>
    <td>${being.price} Euros
  </#list>
</table>  

Note that since FreeMarker does not interpret text outside FTL tags, interpolations and comments, it doesn't see the above <b> and </b> as wrongly nested tags.


Page generated: 2004-06-15 22:17:59 GMT FreeMarker Manual -- For FreeMarker 2.3