manual.book.xml Maven / Gradle / Ivy
Go to download
Google App Engine compliant variation of FreeMarker.
FreeMarker is a "template engine"; a generic tool to generate text output based on templates.
<?xml version="1.0" encoding="UTF-8"?>
<book conformance="docgen" version="5.0" xml:lang="en"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:ns5="http://www.w3.org/1999/xhtml"
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1998/Math/MathML"
xmlns:ns="http://docbook.org/ns/docbook">
<title>FreeMarker Manual</title>
<subtitle>For FreeMarker 2.3.17</subtitle>
<preface xml:id="preface">
<title>Preface</title>
<section>
<title>What is FreeMarker?</title>
<para>FreeMarker is a <emphasis>template engine</emphasis>: a generic
tool to generate text output (anything from HTML to autogenerated source
code) based on templates. It's a Java package, a class library for Java
programmers. It's not an application for end-users in itself, but
something that programmers can embed into their products.</para>
<para>FreeMarker is designed to be practical for the generation of
<emphasis>HTML Web pages</emphasis>, particularly by servlet-based
applications following the <link linkend="gloss.MVC">MVC (Model View
Controller) pattern</link>. The idea behind using the MVC pattern for
dynamic Web pages is that you separate the designers (HTML authors) from
the programmers. Everybody works on what they are good at. Designers can
change the appearance of a page without programmers having to change or
recompile code, because the application logic (Java programs) and page
design (FreeMarker templates) are separated. Templates do not become
polluted with complex program fragments. This separation is useful even
for projects where the programmer and the HTML page author is the same
person, since it helps to keep the application clear and easily
maintainable.</para>
<para>Although FreeMarker has some programming capabilities, it is
<emphasis>not</emphasis> a full-blown programming language like PHP.
Instead, Java programs prepare the data to be displayed (like issue SQL
queries), and FreeMarker just generates textual pages that display the
prepared data using templates.</para>
<mediaobject>
<imageobject>
<imagedata fileref="figures/overview.png"></imagedata>
</imageobject>
</mediaobject>
<para>FreeMarker is <emphasis>not</emphasis> a Web application
framework. It is suitable as a component in a Web application framework,
but the FreeMarker engine itself knows nothing about HTTP or servlets.
It simply generates text. As such, it is perfectly usable in non-web
application environments as well. Note, however, that we provide
out-of-the-box solutions for using FreeMarker as the view component of
Model 2 frameworks such as Struts.</para>
<para>FreeMarker is <link
xlink:href="http://www.fsf.org/philosophy/free-sw.html">Free</link>,
released under a BSD-style license. It is <link
xlink:href="http://www.opensource.org/">OSI Certified Open Source
Software</link>. OSI Certified is a certification mark of the Open
Source Initiative.</para>
</section>
<section>
<title>What should I read?</title>
<para>If you are a ...</para>
<itemizedlist>
<listitem>
<para>designer, then you should read the <xref linkend="dgui" /> and
then you can look into the <xref linkend="ref" /> on an as-needed
basis for more specific details.</para>
</listitem>
<listitem>
<para>programmer, then you should read the <xref linkend="dgui" />
guide first, then the <xref linkend="pgui" /> and then you can look
into the <xref linkend="ref" /> on an as-needed basis for more
specific details.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Document conventions</title>
<para>Variable names, template fragments, Java class names, etc. are
written like this: <literal>foo</literal>.</para>
<para>If something should be replaced with a concrete value then it is
written in italics, as follows: <literal>Hello
<replaceable>yourName</replaceable>!</literal>.</para>
<para>Template examples are written like this:</para>
<programlisting role="template">something</programlisting>
<para>Data-model examples are written like this:</para>
<programlisting role="dataModel">something</programlisting>
<para>Output examples are written like this:</para>
<programlisting role="output">something</programlisting>
<para>Program examples are written like this:</para>
<programlisting role="unspecified">something</programlisting>
<remark>This paragraph is for the editors, and not visible for the
public</remark>
<para>In chapters <remark>this section is for the editors
too</remark>written for both designers and programmers fragments
addressed to programmers are written like this: <phrase
role="forProgrammers">This is for programmers only.</phrase></para>
<para>New terms are emphasized like this: <emphasis role="term">some new
term</emphasis></para>
</section>
<section>
<title>Contact</title>
<indexterm>
<primary>help</primary>
</indexterm>
<indexterm>
<primary>homepage</primary>
</indexterm>
<indexterm>
<primary>download</primary>
</indexterm>
<indexterm>
<primary>contact</primary>
</indexterm>
<para>For the latest version of FreeMarker and to subscribe to the
<emphasis>mailing lists</emphasis> visit the FreeMarker homepage: <olink
targetdoc="homepage"><phrase role="homepage"></phrase></olink></para>
<para>If you <emphasis>need help</emphasis> or you have
<emphasis>suggestions</emphasis>, use the mailing lists (mail archives
can be searched without subscription) or the Web based forums. If you
want to <emphasis>report a bug</emphasis>, use the Web based bug
tracker, or the mailing lists. To find all of these visit <olink
targetdoc="homepage"><phrase role="homepage"></phrase></olink>. Also,
note that we have a <link linkend="app_faq">FAQ</link> and <link
linkend="alphaidx">index</link>; use them.</para>
</section>
<section>
<title>About this document</title>
<para>If you find <emphasis>any mistakes</emphasis> (including
<emphasis>grammatical mistakes</emphasis>, <emphasis>typos</emphasis>,
typographical mistakes) or you find something <emphasis>misleading or
confusing</emphasis> in the documentation, or you have other
suggestions, please let me know! Email: ddekany at
users.sourceforge.net</para>
</section>
</preface>
<part xml:id="dgui">
<title>Template Author's Guide</title>
<chapter xml:id="dgui_quickstart">
<title>Getting Started</title>
<para>This chapter is a very rough introduction to FreeMarker. The
chapters after this will go over things in much greater detail.
Nonetheless, once you have read this chapter, you will be able to write
simple but useful FreeMarker templates.</para>
<section xml:id="dgui_quickstart_basics">
<title>Template + data-model = output</title>
<para>Assume you need a HTML page in an e-shop application, similar to
this:</para>
<programlisting role="output"><html>
<head>
<title>Welcome!</title>
</head>
<body>
<h1>Welcome <emphasis>Big Joe</emphasis>!</h1>
<p>Our latest product:
<a href="<emphasis>products/greenmouse.html</emphasis>"><emphasis>green mouse</emphasis></a>!
</body>
</html></programlisting>
<para>Let's say that the user name ("Big Joe" above) should depend on
who the logged in Web page visitor is, and the latest product should
come from a database and thus it potentially changes at any moment. In
this situation you can't just enter the user name nor the URL and name
of the latest product into the HTML, you can't use static HTML.</para>
<para>FreeMarker's solution for this problem is using a <emphasis
role="term">template</emphasis> instead of the static HTML. The
template is the same as the static HTML, except that it contains some
instructions to FreeMarker that makes it dynamic:</para>
<programlisting role="template" xml:id="example.first"><html>
<head>
<title>Welcome!</title>
</head>
<body>
<h1>Welcome <emphasis>${user}</emphasis>!</h1>
<p>Our latest product:
<a href="<emphasis>${latestProduct.url}</emphasis>"><emphasis>${latestProduct.name}</emphasis></a>!
</body>
</html></programlisting>
<para>The template is stored on the Web server, usually just like the
static HTML page would be. But whenever someone visits this page,
FreeMarker will step in and transform the template on-the-fly to plain
HTML by replacing the
<literal>${<replaceable>...</replaceable>}</literal>-s with up-to-date
content (e.g., replacing <literal>${user}</literal> with Big Joe or
whoever the visitor is) and send the result to the visitor's Web
browser. So the visitor's Web browser will receive something like the
first example HTML (i.e., plain HTML without FreeMarker instructions),
and it will not perceive that FreeMarker is used on the server. The
template file itself (which is, again, stored on the Web server) is
not changed during this, so the transformation will happen again and
again for each visiting. This ensures that the displayed information
is always up-to-date.</para>
<para>Now, you already may have noticed that the template contains no
instructions regarding how to find out who the current visitor is, or
how to query the database to find out what the latest product is. It
seems it just already know these values. And indeed that's the case.
An important idea behind FreeMarker (actually, behind Web MVC) is that
presentation logic and "business logic" should be separated. In the
template you only deal with presentation issues, that is, visual
design issues, formatting issues. The data that will be displayed
(such as the user name and so on) is prepared outside FreeMarker,
usually by routines written in Java language or other general purpose
language. So the template author doesn't have to know how these values
are calculated. In fact, the way these values are calculated can be
completely changed while the templates can remain the same, and also,
the look of the page can be completely changed without touching
anything but the template. This separation can be especially useful
when the template authors (designers) and the programmers are
different individuals.</para>
<para><indexterm>
<primary>data-model</primary>
</indexterm>While for FreeMarker (and for the template author) it's
not interesting <emphasis>how</emphasis> the data was calculated,
FreeMarker still have to know <emphasis>what</emphasis> the actual
data is. All the data that the template can use is packed into the so
called <emphasis role="term">data-model</emphasis>. It's created by
the already mentioned routines that calculate the data. As far as the
template author is concerned, the data-model is a tree-like structure
(like folders and files on your hard disk), that in this case could be
visualized as:</para>
<programlisting role="dataModel">(root)
|
+- <emphasis>user</emphasis> = "Big Joe"
|
+- <emphasis>latestProduct</emphasis>
|
+- <emphasis>url</emphasis> = "products/greenmouse.html"
|
+- <emphasis>name</emphasis> = "green mouse"</programlisting>
<para>(To prevent misunderstandings: The data-model is not a text
file, the above is just a visualization of a data-model for you. It's
from Java objects, but let that be the problem of the Java
programmers.)</para>
<para>Compare this with what you seen in the template earlier:
<literal>${user}</literal> and
<literal>${latestProduct.name}</literal>. As an analogy, the data
model is something like the file system of computers: the root and
<literal>latestProduct</literal> correspond to directories (folders)
and the <literal>user</literal>, <literal>url</literal> and
<literal>name</literal> correspond to files. <literal>url</literal>
and <literal>name</literal> are in the
<literal>latestProduct</literal> directory. So
<literal>latestProduct.name</literal> is like saying
<literal>name</literal> in the <literal>latestProduct</literal>
directory. But as I said, it was just a simile; there are no files or
directories here.</para>
<para>To recapitulate, a template and a data-model is needed for
FreeMarker to generate the output (like the HTML shown first):</para>
<para><phrase role="markedTemplate">Template</phrase> + <phrase
role="markedDataModel">data-model</phrase> = <phrase
role="markedOutput">output</phrase></para>
</section>
<section xml:id="dgui_quickstart_datamodel">
<title>The data-model at a glance</title>
<para>As you have seen, the data-model is basically a tree. This tree
can be arbitrarily complicated and deep, for example:</para>
<programlisting role="dataModel"
xml:id="example.qStart.dataModelWithHashes">(root)
|
+- animals
| |
| +- mouse
| | |
| | +- size = "small"
| | |
| | +- price = 50
| |
| +- elephant
| | |
| | +- size = "large"
| | |
| | +- price = 5000
| |
| +- python
| |
| +- size = "medium"
| |
| +- price = 4999
|
+- test = "It is a test"
|
+- whatnot
|
+- because = "don't know"</programlisting>
<para>The variables that act as directories (the root,
<literal>animals</literal>, <literal>mouse</literal>,
<literal>elephant</literal>, <literal>python</literal>,
<literal>whatnot</literal>) are called <emphasis
role="term">hashes</emphasis>. Hashes store other variables (the so
called <anchor
xml:id="topic.dataModel.subVar" /><emphasis>subvariables</emphasis>)
by a lookup name (e.g., "animals", "mouse" or "price").</para>
<para>The variables that store a single value
(<literal>size</literal>, <literal>price</literal>,
<literal>test</literal> and <literal>because</literal>) are called
<emphasis role="term">scalars</emphasis>.</para>
<para><anchor xml:id="topic.qStart.accessVariables" />When you want to
use a subvariable in a template, you specify its path from the root,
and separate the steps with dots. To access the
<literal>price</literal> of a <literal>mouse</literal>, you start from
the root and go into <literal>animals</literal>, and then go into
<literal>mouse</literal> then go into <literal>price</literal>. So you
write <literal>animals.mouse.price</literal>. When you put the special
<literal>${<replaceable>...</replaceable>}</literal> codes around an
expression like this, you are telling FreeMarker to output the
corresponding text at that point.</para>
<para>There is one more important kind of variable: <emphasis
role="term">sequences</emphasis>. They are similar to hashes, but they
don't store names for the variables they contain. Instead, they store
the subvariables sequentially, and you can access them with a
numerical index. For example, in this data-model,
<literal>animals</literal> and <literal>whatnot.fruits</literal> are
sequences:</para>
<programlisting role="dataModel"
xml:id="example.qStart.dataModelWithSequences">(root)
|
+- animals
| |
| +- (1st)
| | |
| | +- name = "mouse"
| | |
| | +- size = "small"
| | |
| | +- price = 50
| |
| +- (2nd)
| | |
| | +- name = "elephant"
| | |
| | +- size = "large"
| | |
| | +- price = 5000
| |
| +- (3rd)
| |
| +- name = "python"
| |
| +- size = "medium"
| |
| +- price = 4999
|
+- whatnot
|
+- fruits
|
+- (1st) = "orange"
|
+- (2nd) = "banana"</programlisting>
<para>To access a subvariable of a sequence you use a numerical index
in square brackets. Indexes start from 0 (it's a programmer tradition
to start with 0), thus the index of the first item is 0, the index of
the second item is 1, and so on. So to get the name of the first
animal you write <literal>animals[0].name</literal>. To get the second
item in <literal>whatnot.fruits</literal> (which is the string
<literal>"banana"</literal>) you write
<literal>whatnot.fruits[1]</literal>.</para>
<para>Scalars can be further divided into these categories:</para>
<itemizedlist>
<listitem>
<para>String: Text, that is, an arbitrary sequence of characters
such as ''m'', ''o'', ''u'', ''s'', ''e'' above. For example the
<literal>name</literal>-s and <literal>size</literal>-s are
strings above.</para>
</listitem>
<listitem>
<para>Number: It's a numerical value, like the
<literal>price</literal>-s above. The string
<literal>"50"</literal> and the number <literal>50</literal> are
two totally different things in FreeMarker. The former is just a
sequence of two characters (which happens to be readable as a
number for humans), while the latter is a numerical value that you
can use, say, in arithmetical calculations.</para>
</listitem>
<listitem>
<para>Date/time: A date or time. Like the date an animal were
captured, or the time the shop opens.</para>
</listitem>
<listitem>
<para>Boolean: A true/false (yes/no, on/off, etc.) thing. Like
animals could have a <literal>protected</literal> subvariable,
which store if the animal is protected or not.</para>
</listitem>
</itemizedlist>
<para>Summary:</para>
<itemizedlist>
<listitem>
<para>The data-model can be visualized as a tree.</para>
</listitem>
<listitem>
<para>Scalars store a single value. The value can be a string or a
number or a date/time or a boolean.</para>
</listitem>
<listitem>
<para>Hashes are containers that store other variables and
associate them with a unique lookup name.</para>
</listitem>
<listitem>
<para>Sequences are containers that store other variables in an
ordered sequence. The stored variables can be retrieved via their
numerical index, starting from 0.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="dgui_quickstart_template">
<title>The template at a glance</title>
<para>The simplest template is a plain HTML file (or whatever text
file -- FreeMarker is not confined to HTML). 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:</para>
<itemizedlist>
<listitem>
<para><literal>${<replaceable>...</replaceable>}</literal>:
FreeMarker will replace it in the output with the actual value of
the thing inside the curly brackets. They are called <emphasis
role="term">interpolation</emphasis>s. As an example see <link
linkend="example.first">the very first example</link>.</para>
</listitem>
<listitem>
<para><emphasis role="term">FTL tags</emphasis> (for FreeMarker
Template Language tags): FTL tags are a bit similar to HTML tags,
but they are instructions to FreeMarker and will not be printed to
the output. The name of these tags start with
<literal>#</literal>. (User-defined FTL tags use
<literal>@</literal> instead of <literal>#</literal>, but they are
an advanced topic.)</para>
</listitem>
<listitem>
<para><emphasis role="term">Comments:</emphasis> Comments are
similar to HTML comments, but they are delimited by
<literal><#--</literal> and <literal>--></literal>. Anything
between these delimiters and the delimiter itself will be ignored
by FreeMarker, and will not be written to the output.</para>
</listitem>
</itemizedlist>
<para>Anything not an FTL tag or an interpolation or comment is
considered as static text, and will not be interpreted by FreeMarker;
it is just printed to the output as is.</para>
<para>With FTL tags you refer to so-called <emphasis
role="term">directives</emphasis>. This is the same kind of
relationship as between HTML tags (e.g.:
<literal><table></literal> and
<literal></table></literal>) and HTML elements (e.g., the
<literal>table</literal> element) to which you refer to with the HTML
tags. (If you don't feel this difference then just take "FTL tag" and
"directive" as synonyms.)</para>
<section>
<title>Examples of directives</title>
<para>Though FreeMarker has far more directives, in this quick
overview we will only look at three of the most commonly used
ones.</para>
<section>
<title>The if directive</title>
<para>With the <literal>if</literal> directive you can
conditionally skip a section of the template. For example, assume
that in the <link linkend="example.first">very first
example</link> you want to greet your boss, Big Joe, differently
from other users:</para>
<programlisting role="template"><html>
<head>
<title>Welcome!</title>
</head>
<body>
<h1>
Welcome ${user}<emphasis><#if user == "Big Joe"></emphasis>, our beloved leader<emphasis></#if></emphasis>!
</h1>
<p>Our latest product:
<a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html></programlisting>
<para>Here you have told FreeMarker that the '', our beloved
leader'' should be there only if the value of the variable
<literal>user</literal> is equal to the string <literal>"Big
Joe"</literal>. In general, things between <literal><#if
<replaceable>condition</replaceable>></literal> and
<literal></#if></literal> tags are skipped if
<literal><replaceable>condition</replaceable></literal> is false
(the boolean value).</para>
<para>Let's detail the
<literal><replaceable>condition</replaceable></literal> used here:
The <literal>==</literal> is an operator that tests if the values
at its left and right side are equivalent, and the results is a
boolean value, true or false accordingly. On the left side of
<literal>==</literal> I have <link
linkend="topic.qStart.accessVariables">referenced a
variable</link> with the syntax that should be already familiar;
this will be replaced with the value of the variable. In general,
unquoted words inside directives or interpolations are treated as
references to variables. On the right side I have specified a
literal string. Literal strings in templates must
<emphasis>always</emphasis> be put inside quotation marks.</para>
<para>This will print "Pythons are free today!" if their price is
0:</para>
<programlisting role="template"><#if animals.python.price == <emphasis>0</emphasis>>
Pythons are free today!
</#if></programlisting>
<para>Similarly as earlier when a string was specified directly,
here a number is specified directly (<literal>0</literal>). Note
that the number is <emphasis>not</emphasis> quoted. If you quoted
it (<literal>"0"</literal>), FreeMarker were misinterpret it as a
string literal.</para>
<para>This will print "Pythons are not free today!" if their price
is not 0:</para>
<programlisting role="template"><#if animals.python.price <emphasis>!=</emphasis> 0>
Pythons are not free today!
</#if></programlisting>
<para>As you may have guessed, <literal>!=</literal> means not
equivalent.</para>
<para>You can write things like this too (using <link
linkend="example.qStart.dataModelWithHashes">the data-model used
to demonstrate hashes</link>):</para>
<programlisting role="template"><#if <emphasis>animals.python.price < animals.elephant.price</emphasis>>
Pythons are cheaper than elephants today.
</#if></programlisting>
<para>With the <literal><#else></literal> tag you can
specify what to do if the condition is false. For example:</para>
<programlisting role="template"><#if animals.python.price < animals.elephant.price>
Pythons are cheaper than elephants today.
<emphasis><#else></emphasis>
Pythons are not cheaper than elephants today.
</#if></programlisting>
<para>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.''</para>
<para>If you have a variable with boolean value (a true/false
thing) then you can use it directly as the
<literal><replaceable>condition</replaceable></literal> of
<literal>if</literal>:</para>
<programlisting role="template"><#if animals.python.protected>
Warning! Pythons are protected animals!
</#if></programlisting>
</section>
<section>
<title>The list directive</title>
<para>This is useful when you want to list something. For example
if you merge this template with the <link
linkend="example.qStart.dataModelWithSequences">data-model I used
earlier to demonstrate sequences</link>:</para>
<programlisting role="template"><p>We have these animals:
<table border=1>
<tr><th>Name<th>Price
<emphasis><#list animals as being></emphasis>
<tr><td>${<emphasis>being</emphasis>.name}<td>${<emphasis>being</emphasis>.price} Euros
<emphasis></#list></emphasis>
</table></programlisting>
<para>then the output will be:</para>
<programlisting role="output"><p>We have these animals:
<table border=1>
<tr><th>Name<th>Price
<emphasis><tr><td>mouse<td>50 Euros
<tr><td>elephant<td>5000 Euros
<tr><td>python<td>4999 Euros</emphasis>
</table></programlisting>
<para>The generic format of the <literal>list</literal> directive
is:</para>
<para><literal><#list <replaceable>sequence</replaceable> as
<replaceable>loopVariable</replaceable>><replaceable>repeatThis</replaceable></#list></literal></para>
<para>The <literal><replaceable>repeatThis</replaceable></literal>
part will be repeated for each item in the sequence that you have
given with <literal><replaceable>sequence</replaceable></literal>,
one after the other, starting from the first item. In all
repetitions
<literal><replaceable>loopVariable</replaceable></literal> will
hold the value of the current item. This variable exists only
between the <literal><#list ...></literal> and
<literal></#list></literal> tags.</para>
<para>As another example, we list the fruits of that example data
model:</para>
<programlisting role="template"><p>And BTW we have these fruits:
<ul>
<emphasis><#list whatnot.fruits as fruit></emphasis>
<li>${fruit}
<emphasis></#list></emphasis>
<ul></programlisting>
<para>The <literal>whatnot.fruits</literal> expression should be
familiar to you; it <link
linkend="topic.qStart.accessVariables">references a variable in
the data-model</link>.</para>
</section>
<section>
<title>The include directive</title>
<para>With the <literal>include</literal> directive you can insert
the content of another file into the template.</para>
<para>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
<literal>copyright_footer.html</literal>:</para>
<programlisting role="template"><hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i></programlisting>
<para>Whenever you need that file you simply insert it with the
<literal>include</literal> directive:</para>
<programlisting role="template"><html>
<head>
<title>Test page</title>
</head>
<body>
<h1>Test page</h1>
<p>Blah blah...
<emphasis><#include "/copyright_footer.html"></emphasis>
</body>
</html></programlisting>
<para>and the output will be:</para>
<programlisting role="output"><html>
<head>
<title>Test page</title>
</head>
<body>
<h1>Test page</h1>
<p>Blah blah...
<emphasis><hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i></emphasis>
</body>
</html></programlisting>
<para>If you change the <literal>copyright_footer.html</literal>,
then the visitor will see the new copyright notice on all
pages.</para>
</section>
</section>
<section>
<title>Using directives together</title>
<para>You can use directives as many times on a page as you want,
and you can nest directives into each other similarly as you can
nest HTML elements into each other. For example this will list the
animals and print the name of large animals with bigger font:</para>
<programlisting role="template"><p>We have these animals:
<table border=1>
<tr><th>Name<th>Price
<emphasis><#list animals as being></emphasis>
<tr>
<td>
<emphasis><#if being.size == "large"></emphasis><font size="+1"><emphasis></#if></emphasis>
${being.name}
<emphasis><#if being.size == "large"></emphasis></font><emphasis></#if></emphasis>
<td>${being.price} Euros
<emphasis></#list></emphasis>
</table></programlisting>
<para>Note that since FreeMarker does not interpret text outside FTL
tags, interpolations and comments, it doesn't see the above
<literal>font</literal> tags as badly nested ones.</para>
</section>
<section>
<title>Dealing with missing variables</title>
<para>In practice the data-model often has variables that are
optional (i.e., sometimes missing). To spot some typical human
mistakes, FreeMarker doesn't tolerate the referring to missing
variables unless you tell them explicitly what to do if the variable
is missing. Here we will show the two most typical ways of doing
that.</para>
<para><phrase role="forProgrammers">Note for programmers: A
non-existent variable and a variable with <literal>null</literal>
value is the same for FreeMarker, so the "missing" term used here
covers both cases.</phrase></para>
<para>Wherever you refer to a variable, you can specify a default
value for the case the variable is missing, by following the
variable name with a <literal>!</literal> and the default value.
Like in the following example, when <literal>user</literal> is
missing from data model, the template will behave like if
<literal>user</literal>'s value were the string
<literal>"Anonymous"</literal>. (When <literal>user</literal> isn't
missing, this template behaves exactly like if
<literal>!"Anonymous"</literal> were not there):</para>
<programlisting role="template"><h1>Welcome ${user<emphasis>!"Anonymous"</emphasis>}!</h1></programlisting>
<para>You can ask whether a variable isn't missing by putting
<literal>??</literal> after its name. Combining this with the
already introduced <literal>if</literal> directive you can skip the
whole greeting if the <literal>user</literal> variable is
missing:</para>
<programlisting role="template"><#if <emphasis>user??</emphasis>><h1>Welcome ${user}!</h1></#if></programlisting>
<para>Regarding variable accessing with multiple steps, like
<literal>animals.python.price</literal>, writing
<literal>animals.python.price!0</literal> is correct only if
<literal>animals.python</literal> is never missing and only the last
subvariable, <literal>price</literal>, is possibly missing (in which
case here we assume it's <literal>0</literal>). If
<literal>animals</literal> or <literal>python</literal> is missing,
the template processing will stop with an "undefined variable"
error. To prevent that, you have to write
<literal>(animals.python.price)!0</literal>. In that case the
expression will be <literal>0</literal> even if
<literal>animals</literal> or <literal>python</literal> is missing.
Same logic goes for <literal>??</literal>;
<literal>animals.python.price??</literal> versus
<literal>(animals.python.price)??</literal>.</para>
</section>
</section>
</chapter>
<chapter xml:id="dgui_datamodel">
<title>Values, Types</title>
<section xml:id="dgui_datamodel_basics">
<title>Basics</title>
<note>
<para>It is assumed that you have already read the <xref
linkend="dgui_quickstart" /> chapter.</para>
</note>
<para>Understanding the concept of values and types is crucial for the
understanding of data-models. However, the concept of values and types
is not confined to data-models, as you will see.</para>
<section xml:id="topic.value">
<title>What is a value?</title>
<indexterm>
<primary>value</primary>
</indexterm>
<para><phrase role="forProgrammers">Real programmers can safely skip
this section.</phrase></para>
<para>Examples of <emphasis>values</emphasis> as you know the term
from the everyday math are 16, 0.5, and so on, i.e. numbers. In the
case of computer languages the value term has a wider meaning, as a
value needn't be a number. For example, take this data-model:</para>
<programlisting role="dataModel" xml:id="example.stdDataModel">(root)
|
+- user = "Big Joe"
|
+- today = Jul 6, 2007
|
+- todayHoliday = false
|
+- lotteryNumbers
| |
| +- (1st) = 20
| |
| +- (2st) = 14
| |
| +- (3rd) = 42
| |
| +- (4th) = 8
| |
| +- (5th) = 15
|
+- cargo
|
+- name = "coal"
|
+- weight = 40
</programlisting>
<para>We say that the <emphasis>value</emphasis> of the the
<literal>user</literal> variable is "Big Joe" (a string), the
<emphasis>value</emphasis> of <literal>today</literal> is Jul 6,
2007 (a date), the <emphasis>value</emphasis> of
<literal>todayHoliday</literal> is false (a boolean, ie. a yes/no
thing). The <emphasis>value</emphasis> of
<literal>lotteryNumbers</literal> is the sequence that contains 20,
14, 42, 8, 15. Surely <literal>lotteryNumbers</literal> is multiple
values in the sense that it <emphasis>contains</emphasis> multiple
values (for example, the 2nd item in it is a the
<emphasis>value</emphasis> 14), but still,
<literal>lotteryNumbers</literal> itself is a single value. It's
like a box that contains many other items; the whole box can be seen
as a single item. Last not least we also have the
<emphasis>value</emphasis> of <literal>cargo</literal>, which is a
hash (a box-like thing again).So, a value is something that can be
stored in a variable (e.g., in <literal>user</literal> or
<literal>cargo</literal> or <literal>cargo.name</literal>). But a
value need not be stored in a variable to be called a value, for
example we have the value 100 here:</para>
<programlisting role="template"><#if cargo.weight < <emphasis>100</emphasis>>Light cargo</#if></programlisting>
<para>The temporaly result of a calculations are also called values,
like 20 and 120 when this template is executed (it will print
120):</para>
<programlisting role="template">${cargo.weight / 2 + 100}</programlisting>
<para>Explanation for this last: As the result of dividing the two
values, 40 (the weight of the cargo) and 2, a new value 20 is
created. Then 100 is added to it, so the value 120 is created. Then
120 is printed
(<literal>${<replaceable>...</replaceable>}</literal>), and the
template execution goes on and all these values gone.</para>
<para>Certainly now you feel what the value term means.</para>
</section>
<section>
<title>What is type?</title>
<para>Values have an important aspect, their type. For example the
type of the value of the <literal>user</literal> variable is string,
and the type of the value of the <literal>lotteryNumbers</literal>
variable is sequence. The type of a value is important because it
determines to a large extent how and where you can use the value.
Like <literal>${user / 2}</literal> is an error, but
<literal>${cargo.weight / 2}</literal> works and prints 20, since
division only does make sense for a number, but not for a string.
Or, using dot like in <literal>cargo.name</literal> does make sense
only if <literal>cargo</literal> is a hash. Or, you can list with
<literal><#list <replaceable>...</replaceable>></literal>
sequences only. Or, the condition of <literal><#if
...></literal> must be a boolean. And so on.</para>
<note>
<para>A little terminology... Saying "a boolean" or "a boolean
value" or "a value of type boolean" are all the same.</para>
</note>
<para xml:id="topic.multitype"><indexterm>
<primary>Multi-typed value</primary>
</indexterm>A value can have multiple types at the same time,
although it's rarely utilized. For example in the data-model below
<literal>mouse</literal> is both a string and a hash:</para>
<programlisting role="dataModel">(root)
|
+- mouse = "Yerri"
|
+- age = 12
|
+- color = "brown"</programlisting>
<para>If you merge this template with the above data-model:</para>
<programlisting role="template">${mouse} <#-- uses mouse as a string -->
${mouse.age} <#-- uses mouse as a hash -->
${mouse.color} <#-- uses mouse as a hash --></programlisting>
<para>the output will be:</para>
<programlisting role="output">Yerri
12
brown</programlisting>
</section>
<section>
<title>The data-model is a hash</title>
<para>Looking at the various data-model examples you may already
realized: the thing marked as "(root)" is just a value of type hash.
When you write something like <literal>user</literal>, that means
that you want the "user" variable stored in the root hash. Like if
you were writing <literal>root.user</literal>, except that there is
no variable called "root" so that wouldn't work.</para>
<para>Some may get confused by the fact that our example data-model,
that is, the root hash, contains further hashes and sequences
(<literal>lotteryNumbers</literal> and <literal>cargo</literal>).
There is nothing special in that. A hash contains other variables,
and those variables have a value, which can be a string, a number,
etc., and of course it can be a hash or sequence as well. Because,
as it was explained earlier, a sequence or a hash is just a value,
like a string or a number is.</para>
</section>
</section>
<section xml:id="dgui_datamodel_types">
<title>The types</title>
<para>The suppored types are:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="dgui_datamodel_scalar"
os="">Scalars:</link></para>
<itemizedlist spacing="compact">
<listitem>
<para>String</para>
</listitem>
<listitem>
<para>Number</para>
</listitem>
<listitem>
<para>Boolean</para>
</listitem>
<listitem>
<para>Date</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link
linkend="dgui_datamodel_container">Containers:</link></para>
<itemizedlist spacing="compact">
<listitem>
<para>Hash</para>
</listitem>
<listitem>
<para>Sequence</para>
</listitem>
<listitem>
<para>Collection</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Subroutines:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="dgui_datamodel_method">Methods and
functions</link></para>
</listitem>
<listitem>
<para><link linkend="dgui_datamodel_userdefdir">User-defined
directives</link></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Miscellaneous/seldom used:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="dgui_datamodel_node">Node</link></para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<section xml:id="dgui_datamodel_scalar">
<title>Scalars</title>
<anchor xml:id="topic.designer.scalarVariable" />
<para>These are the basic, simple kind of values. They can
be:</para>
<itemizedlist>
<listitem>
<para><indexterm>
<primary>string</primary>
<secondary>the FTL value type</secondary>
</indexterm>String: It is simple text, e.g., the name of a
product.</para>
<para>If you want to give a string value directly in the
template, rather than use a variable that comes from the data
model, you write the text between quotation marks, e.g.,
<literal>"green mouse"</literal> or <literal>'green
mouse'</literal>. (More details regarding the syntax can be
found <link linkend="dgui_template_exp_direct_string"
xml:lang="">later</link>.)</para>
</listitem>
<listitem>
<para><indexterm>
<primary>number</primary>
<secondary>the FTL value type</secondary>
</indexterm>Number: For example the price of a product.
<phrase role="forProgrammers">Whole numbers and non-whole
numbers are not distinguished; there is only a single number
type. So for example 3/2 will be always 1.5, and never 1. Just
like if you are using a calculator.</phrase></para>
<para>If you want to give a numerical value directly in the
template, then you write for example: <literal>150</literal> or
<literal>-90.05</literal> or <literal>0.001</literal>. (More
details regarding the syntax can be found <link
linkend="dgui_template_exp_direct_number"
xml:lang="">later</link>.)</para>
</listitem>
<listitem>
<para><indexterm>
<primary>boolean</primary>
<secondary>the FTL value type</secondary>
</indexterm>Boolean: A boolean value represents a logical true
or false (yes or no). For example, if a the visitor has been
logged in or not. Typically you use booleans as the condition of
the <literal>if</literal> directive, like <literal><#if
loggedIn
><replaceable>...</replaceable></#if></literal> or
<literal><#if price ==
0><replaceable>...</replaceable></#if></literal>; in
the last case the result of the <literal>price == 0</literal>
part is a boolean value.</para>
<para>In the templates you can directly specify a boolean with
the reserved words <literal>true</literal> and
<literal>false</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>date</primary>
<secondary>the FTL value type</secondary>
</indexterm><indexterm>
<primary>time</primary>
<secondary>the FTL value type</secondary>
</indexterm><indexterm>
<primary>date-time</primary>
<secondary>the FTL value type</secondary>
</indexterm>Date: A date variable stores date/time related
data. It has three variations:</para>
<itemizedlist>
<listitem>
<para>A date with day precision (often referred simply as
"date") as April 4, 2003</para>
</listitem>
<listitem>
<para>Time of day (without the date part), as 10:19:18 PM.
Time is stored with millisecond precision.</para>
</listitem>
<listitem>
<para>Date-time (sometimes called "time stamp") as April 4,
2003 10:19:18 PM. The time part is stored with millisecond
precision.</para>
</listitem>
</itemizedlist>
<para>Unfortunately, because of the limitations of the Java
platform, FreeMarker sometimes can't decide which parts of the
date are in use (i.e., if it is date-time, or a time of day,
etc.). The solution for this problem is an advanced topic that
will be discussed <link
linkend="ref_builtin_date_datetype">later</link>.</para>
<para>It is possible to define date values directly in
templates, but this is an advanced topic that will be explained
<link linkend="ref_builtin_string_date">later</link>.</para>
</listitem>
</itemizedlist>
<para>Bear in mind that FreeMarker distinguishes strings from
numbers and booleans, so the string <literal>"150"</literal> and the
number <literal>150</literal> are totally different. A number holds
a numerical value. A boolean holds a logical true or false. A string
holds an arbitrary sequence of characters.</para>
</section>
<section xml:id="dgui_datamodel_container">
<title>Containers</title>
<remark>Re-explanation of hashes and sequences from a more
''professional'' viewpoint as earlier, and some meditation about
them.</remark>
<para>These are the values whose purpose is to contain other
variables; they are just containers. The contained variables are
often referred as <emphasis>subvariables</emphasis>. The container
types are:</para>
<itemizedlist>
<listitem>
<para><indexterm>
<primary>hash</primary>
<secondary>the FTL value type</secondary>
</indexterm>Hash: Associates a unique lookup name with each of
its subvariables. The name is an unrestricted string. A hash
<emphasis>doesn't define an ordering</emphasis> for the
subvariables in it. That is, there is no such thing as the first
subvariable, and the second subvariable, etc.; the variables are
just accessed by name.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>sequence</primary>
<secondary>the FTL value type</secondary>
</indexterm>Sequence: Associates an integer number with each
of its subvariables. The first subvariable is associated with 0,
the second with 1, the third to 2, and so on; the subvariables
are ordered. These numbers are often called the
<emphasis>indexes</emphasis> of the subvariables. Sequences are
usually dense, i.e., all indexes up to the index of the last
subvariable have an associated subvariable, but it's not
strictly necessary. The type of the subvariable values need not
be the same.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>collection</primary>
<secondary>the FTL value type</secondary>
</indexterm>Collection: A collection, from the viewpoint of
the template author, is a restricted sequence. You cannot access
its size or retrieve its subvariables by index, but they can be
still listed with the <link
linkend="ref.directive.list"><literal>list</literal>
directive</link>.</para>
</listitem>
</itemizedlist>
<para>Note that since <link linkend="topic.multitype">a value can
have multiple types</link>, it is possible for a value to be both a
hash and a sequence, in which case it would support index-based
access as well as access by lookup name. However, typically a
container will be either a hash or a sequence, not both.</para>
<para>As the value of the variables stored in hashes and sequences
(and collections) can be anything, it can be a hash or sequence (or
collection) as well. This way you can build arbitrarily deep
structures.</para>
<para>The data-model itself (or better said the root of it) is a
hash.</para>
</section>
<section>
<title>Subroutines</title>
<section xml:id="dgui_datamodel_method">
<title>Methods and functions</title>
<anchor xml:id="topic.designer.methodVariable" />
<indexterm>
<primary>method</primary>
<secondary>the FTL value type</secondary>
</indexterm>
<para>A value that is a method or a function is used to calculate
another value, influenced by the parameters you give to it.</para>
<para><phrase role="forProgrammers">For programmer types:
Methods/functions are first-class values, just like in functional
programming languages. This means that functions/methods can be
the parameters or return values of other functions/methods, you
can assign them to variables, and so on.</phrase></para>
<para>Suppose that programmers have put the method variable
<literal>avg</literal> in the data-model that can be used to
calculate the average of numbers. If you give the 3 and 5 as
parameters when you access <literal>avg</literal>, then you get
the value 4.</para>
<para>The usage of methods will be explained <link
linkend="dgui_template_exp_methodcall">later</link>, but perhaps
this example helps to understand what methods are:</para>
<programlisting role="template">The average of 3 and 5 is: ${avg(3, 5)}
The average of 6 and 10 and 20 is: ${avg(6, 10, 20)}
The average of the price of a python and an elephant is:
${avg(animals.python.price, animals.elephant.price)}</programlisting>
<para>this will output:</para>
<programlisting role="output">The average of 3 and 5 is: 4
The average of 6 and 10 and 20 is: 12
The average of the price of a python and an elephant is:
4999.5</programlisting>
<para>What is the difference between a method and a function? As
far as the template author is concerned, nothing. Well not really
nothing, as methods typically come from the data-model (<phrase
role="forProgrammers">as they reflect the methods of Java
objects</phrase>), and functions are defined in templates (with
the <link
linkend="ref.directive.function"><literal>function</literal>
directive</link> -- an advanced topic), but both can be used on
the same way.</para>
</section>
<section xml:id="dgui_datamodel_userdefdir">
<title>User-defined directives</title>
<indexterm>
<primary>macro</primary>
<secondary>the FTL value type</secondary>
</indexterm>
<indexterm>
<primary>directive</primary>
<secondary>the FTL value type</secondary>
</indexterm>
<indexterm>
<primary>user-defined directive</primary>
<secondary>the FTL value type</secondary>
</indexterm>
<para>A value of this type can be used as user-defined directive
(with other words, as FreeMarker tag). An user-defined directive
is a subroutine, something like a little reusable template
fragment. But this is an advanced topic that will be explained
<link linkend="dgui_misc_userdefdir">later</link> in its own
chapter.</para>
<para><phrase role="forProgrammers">For programmer types:
user-defined directives (such as macros), are first-class values
too, just like functions/methods are.</phrase></para>
<para>Just to get an idea about user-defined directives (so just
ignore this if you won't understand), assume we have a variable,
<literal>box</literal>, whose value is a user-defined directive
that prints some kind of fancy HTML message box with a title bar
and a message in it. The <literal>box</literal> variable could be
used in the template like this (for example):</para>
<programlisting role="template"><@<emphasis>box</emphasis> title="Attention!">
Too much copy-pasting may leads to
maintenance headaches.
</@<emphasis>box</emphasis>></programlisting>
</section>
<section>
<title>Function/method versus user-defined directive</title>
<para>This is for advanced users again (so ignore it if you don't
understand). It's a frequent dilemma if you should use a
function/method or an user-defined directive to implement
something. The rule of thumb is: Implement the facility as
user-defined directive instead of as function/method if:</para>
<itemizedlist>
<listitem>
<para>... the output (the return value) is markup (HTML, XML,
etc.). The main reason is that the result of functions are
subject to automatic XML-escaping (due to the nature of
<literal>${<replaceable>...</replaceable>}</literal>), while
the output of user-defined directives are not (due to the
nature of
<literal><@<replaceable>...</replaceable>></literal>;
its output is assumed to be markup, and hence already
escaped).</para>
</listitem>
<listitem>
<para>... it's the side-effect that is important and not the
return value. For example, a directive whose purpose is to add
an entry to the server log is like that. (In fact you can't
have a return value for a user-defined directive, but some
kind of feedback is still possible by setting non-local
variables.)</para>
</listitem>
<listitem>
<para>... it will do flow control (like for example
<literal>list</literal> or <literal>if</literal> directives
do). You just can't do that with a function/method
anyway.</para>
</listitem>
</itemizedlist>
<para>The Java methods of FreeMarker-unaware Java objects are
normally visible as methods in templates, regardless of the nature
of the Java method. That said, you have no choice there.</para>
</section>
</section>
<section>
<title>Miscellaneous</title>
<section xml:id="dgui_datamodel_node">
<title>Nodes</title>
<indexterm>
<primary>node</primary>
<secondary>the FTL value type</secondary>
</indexterm>
<para>Node variables represent a node in a tree structure, and are
used mostly with <link linkend="xgui">XML processing</link>, which
is an advanced, and specialized topic.</para>
<para>Still, a quick overview <emphasis>for advanced
users</emphasis>: A node is similar to a sequence that stores
other nodes, which are often referred as the children nodes. A
node stores a reference to its container node, which is often
referred as the parent node. The main point of being a node is the
topological information; other data must be stored by utilizing
that a value can have multiple types. Like, a value may be both a
node and a number, in which case it can store a number as the
"pay-load". Apart from the topological information, a node can
store some metainformation as well: a node name, a node type
(string), and a node namespace (string). For example, if the node
symbolizes a <literal>h1</literal> element in an XHTML document,
then its name could be <literal>"h1"</literal>, it's node type
could be <literal>"element"</literal>, and it's namespace could be
<literal>"http://www.w3.org/1999/xhtml"</literal>. But it's up to
the designer of the data-model if what meaning these
metainformations have, and if they are used at all. The way of
retrieving the topological and metainformations is described <link
linkend="ref_builtins_node">in a later chapter</link> (that you
don't have to understand at this point).</para>
</section>
</section>
</section>
</chapter>
<chapter xml:id="dgui_template">
<title>The Template</title>
<indexterm>
<primary>template</primary>
</indexterm>
<note>
<para>It is assumed that you have already read the <xref
linkend="dgui_quickstart" /> and the <xref linkend="dgui_datamodel" />
chapter.</para>
</note>
<section xml:id="dgui_template_overallstructure">
<title>Overall structure</title>
<para>Templates are in fact programs you write in a language called
<indexterm>
<primary>FTL</primary>
</indexterm><emphasis role="term">FTL</emphasis> (for FreeMarker
Template Language). This is a quite simple programming language
designed for writing templates and nothing else.</para>
<para>A template (= FTL program) is a mix of the following
sections:</para>
<itemizedlist>
<listitem>
<para><emphasis role="term">Text</emphasis><indexterm>
<primary>text</primary>
</indexterm>: Text that will be printed to the output as
is.</para>
</listitem>
<listitem>
<para><emphasis role="term">Interpolation</emphasis><indexterm>
<primary>interpolation</primary>
</indexterm>: These sections will be replaced with a calculated
value in the output. Interpolations are delimited by
<literal>${</literal> and <literal>}</literal> (or with
<literal>#{</literal> and <literal>}</literal>, but that shouldn't
be used anymore; <link
linkend="ref_depr_numerical_interpolation">see more
here</link>).</para>
</listitem>
<listitem>
<para><emphasis role="term">FTL tags</emphasis><indexterm>
<primary>FTL tag</primary>
</indexterm>: FTL tags are a bit similar to HTML tags, but they
are instructions to FreeMarker and will not be printed to the
output.</para>
</listitem>
<listitem>
<para><emphasis role="term">Comments</emphasis><indexterm>
<primary>comment</primary>
</indexterm><indexterm>
<primary><#--...--></primary>
</indexterm><indexterm>
<primary>#</primary>
</indexterm>: Comments are similar to HTML comments, but they
are delimited by <literal><#--</literal> and
<literal>--></literal>. Comments will be ignored by FreeMarker,
and will not be written to the output.</para>
</listitem>
</itemizedlist>
<para>Let's see a concrete template. I have marked the template's
components with colors: <phrase role="markedText">text</phrase>,
<phrase role="markedInterpolation">interpolation</phrase>, <phrase
role="markedFTLTag">FTL tag</phrase>, <phrase
role="markedComment">comment</phrase>. With the <phrase
role="markedInvisibleText">[BR]</phrase>-s I intend to visualize the
<link linkend="gloss.lineBreak">line breaks</link>.</para>
<programlisting role="template"><phrase role="markedText"><html><phrase
role="markedInvisibleText">[BR]</phrase>
<head><phrase role="markedInvisibleText">[BR]</phrase>
<title>Welcome!</title><phrase role="markedInvisibleText">[BR]</phrase>
</head><phrase role="markedInvisibleText">[BR]</phrase>
<body><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedComment"><#-- Greet the user with his/her name --></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<h1>Welcome <phrase role="markedInterpolation">${user}</phrase>!</h1><phrase
role="markedInvisibleText">[BR]</phrase>
<p>We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
<ul><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#list animals as being></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<li><phrase role="markedInterpolation">${being.name}</phrase> for <phrase
role="markedInterpolation">${being.price}</phrase> Euros<phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"></#list></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
</ul><phrase role="markedInvisibleText">[BR]</phrase>
</body><phrase role="markedInvisibleText">[BR]</phrase>
</html></phrase></programlisting>
<para>FTL distinguishes upper case and lower case letters. So
<literal>list</literal> is good directive name, while
<literal>List</literal> is not. Similarly <literal>${name}</literal>
is not the same as <literal>${Name}</literal> or
<literal>${NAME}</literal></para>
<para>It is important to realize that <phrase
role="markedInterpolation">interpolations</phrase> can be used in
<phrase role="markedText">text</phrase> (and in string literal
expressions; see <link
linkend="dgui_template_exp_stringop_interpolation">later</link>)
only.</para>
<para>An <phrase role="markedFTLTag">FTL tag</phrase> can't be inside
another <phrase role="markedFTLTag">FTL tag</phrase> nor inside an
<phrase role="markedInterpolation">interpolation</phrase>. For example
this is <emphasis>WRONG</emphasis>: <literal><#if <#include
'foo'>='bar'>...</#if></literal></para>
<para><phrase role="markedComment">Comments</phrase> can be placed
inside <phrase role="markedFTLTag">FTL tags</phrase> and <phrase
role="markedInterpolation">interpolations</phrase>. For
example:</para>
<programlisting role="template"><phrase role="markedText"><h1>Welcome <phrase
role="markedInterpolation">${user <phrase role="markedComment"><#-- The name of user --></phrase>}</phrase>!</h1><phrase
role="markedInvisibleText">[BR]</phrase>
<p>We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
<ul><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#list <phrase role="markedComment"><#-- some comment... --></phrase> animals as <phrase
role="markedComment"><#-- again... --></phrase> being></phrase><phrase
role="markedInvisibleText">[BR]</phrase></phrase>
<replaceable>...</replaceable></programlisting>
<note>
<para>For those of you who have tried the above examples: You may
notice that some of spaces, tabs and line breaks are missing from
the template output, even though we said that <phrase
role="markedText">text</phrase> is printed as is. Don't bother with
it now. This is because the feature called ''white-space stripping''
is turned on, and that automatically removes some superfluous
spaces, tabs and line breaks. This will be explained <link
linkend="dgui_misc_whitespace">later</link>.</para>
</note>
</section>
<section xml:id="dgui_template_directives">
<title>Directives</title>
<indexterm>
<primary><#...></primary>
</indexterm>
<indexterm>
<primary>#</primary>
</indexterm>
<anchor xml:id="term.designer.directive" />
<remark>Note that the Expressions chapter depends on this chapter, and
Interpolations chapter depends on Expressions chapter. Thus Directives
must be the first chapter after Basics.</remark>
<para><indexterm>
<primary>directive</primary>
</indexterm>You use FTL tags to call <emphasis
role="term">directives</emphasis>. In the example you have called the
<literal>list</literal> directive. Syntactically you have done it with
two tags: <literal><#list animals as being></literal> and
<literal></#list></literal>.</para>
<para><indexterm>
<primary>FTL tag</primary>
</indexterm>There are two kind of FTL tags:</para>
<itemizedlist>
<listitem>
<para>Start-tag:
<literal><#<replaceable>directivename</replaceable>
<replaceable>parameters</replaceable>></literal></para>
</listitem>
<listitem>
<para>End-tag:
<literal></#<replaceable>directivename</replaceable>></literal></para>
</listitem>
</itemizedlist>
<para>This is similar to HTML or XML syntax, except that the tag name
starts with <literal>#</literal>. If the directive doesn't have nested
content (content between the start-tag and the end-tag), you must use
the start-tag with no end-tag. For example you write <literal><#if
<replaceable>something</replaceable>><replaceable>...</replaceable></#if></literal>,
but just <literal><#include
<replaceable>something</replaceable>></literal> as FreeMarker knows
that the <literal>include</literal> directive can't have nested
content.</para>
<para>The format of the
<literal><replaceable>parameters</replaceable></literal> depends on
the
<literal><replaceable>directivename</replaceable></literal>.</para>
<para>In fact there are two types of directives: <link
linkend="gloss.predefinedDirective">predefined directives</link> and
<link linkend="gloss.userDefinedDirective">user-defined
directives</link>. For user-defined directives you use
<literal>@</literal> instead of <literal>#</literal>, for example
<literal><@mydirective
<replaceable>parameters</replaceable>><replaceable>...</replaceable></@mydirective></literal>.
Further difference is that if the directive has no nested content, you
must use a tag like <literal><@mydirective
<replaceable>parameters</replaceable> /></literal>, similarly as in
XML (e.g. <literal><img <replaceable>...</replaceable>
/></literal>). But user-defined directives is an advanced topic
that will be discussed <link
linkend="dgui_misc_userdefdir">later</link>.</para>
<para>FTL tags, like HTML tags, must be properly nested. So the code
below is wrong, as the <literal>if</literal> directive is both inside
and outside of the nested content of the <literal>list</literal>
directive:</para>
<programlisting role="template"><ul>
<emphasis><#list animals as being></emphasis>
<li>${being.name} for ${being.price} Euros
<emphasis><#if user == "Big Joe"></emphasis>
(except for you)
<emphasis></#list></emphasis> <#-- WRONG! The "if" has to be closed first. -->
<emphasis></#if></emphasis>
</ul></programlisting>
<para>Note that FreeMarker doesn't care about the nesting of HTML
tags, only about the nesting of FTL tags. It just sees HTML as flat
text, it doesn't interpret it in any way.</para>
<para>If you try to use a non-existing directive (e.g., you mistype
the directive name), FreeMarker will decline to use the template and
produce an error message.</para>
<para>FreeMarker ignores superfluous <link
linkend="gloss.whiteSpace">white-space</link> inside FTL tags. So you
can write this:</para>
<programlisting role="template"><phrase role="markedText"><phrase
role="markedFTLTag"><#list<phrase role="markedInvisibleText">[BR]</phrase>
animals as<phrase role="markedInvisibleText">[BR]</phrase>
being<phrase role="markedInvisibleText">[BR]</phrase>
></phrase><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInterpolation">${being.name}</phrase> for <phrase
role="markedInterpolation">${being.price}</phrase> Euros<phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"></#list ></phrase></phrase></programlisting>
<para>You may not, however, insert white-space between the
<literal><</literal> or <literal></</literal> and the directive
name.</para>
<para>The complete list and description of all directives can be found
in the <xref linkend="ref_directives" /> (but I recommend that you
look at the chapter about expressions first).</para>
<note>
<para>FreeMarker can be configured to use <literal>[</literal> and
<literal>]</literal> instead of <literal><</literal> and
<literal>></literal> in the FTL tags and FTL comments, like
<literal>[#if user == "Big
Joe"]<replaceable>...</replaceable>[/#if]</literal>. For more
information read: <xref
linkend="dgui_misc_alternativesyntax" />.</para>
</note>
<note>
<para>FreeMarker can be configured so that it understands predefined
directives without <literal>#</literal> (like <literal><if user
== "Big
Joe"><replaceable>...</replaceable></if></literal>).
However we don't recommend the usage of this mode. For more
information read: <xref linkend="ref_depr_oldsyntax" /></para>
</note>
</section>
<section xml:id="dgui_template_exp">
<title>Expressions</title>
<para><indexterm>
<primary>expression</primary>
</indexterm>When you supply values for interpolations or directive
parameters you can use variables or more complex expressions. For
example, if x is the number 8 and y is 5, the value of <literal>(x +
y)/2</literal> resolves to the numerical value 6.5.</para>
<para>Before we go into details, let's see some concrete
examples:</para>
<itemizedlist>
<listitem>
<para>When you supply value for interpolations: The usage of
interpolations is
<literal>${<replaceable>expression</replaceable>}</literal> where
expression gives the value you want to insert into the output as
text. So <literal>${(5 + 8)/2}</literal> prints ``6.5'' to the
output (or possibly ``6,5'' if the language of your output is not
US English).</para>
</listitem>
<listitem>
<para>When you supply a value for the directive parameter: You
have already seen the <literal>if</literal> directive in the
Getting Started section. The syntax of this directive is:
<literal><#if
<replaceable>expression</replaceable>><replaceable>...</replaceable></#if></literal>.
The expression here must evaluate to a boolean value. For example
in <literal><#if 2 < 3></literal> the <literal>2 <
3</literal> (2 is less than 3) is an expression which evaluates to
<literal>true</literal>.</para>
</listitem>
</itemizedlist>
<section xml:id="exp_cheatsheet">
<title>Quick overview (cheat sheet)</title>
<para>This is a reminder for those of you who already know
FreeMarker or are just experienced programmers:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="dgui_template_exp_direct">Specify values
directly</link></para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_direct_string">Strings</link>:
<literal>"Foo"</literal> or <literal>'Foo'</literal> or
<literal>"It's \"quoted\""</literal> or
<literal>r"C:\raw\string"</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_direct_number">Numbers</link>:
<literal>123.45</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_direct_boolean">Booleans</link>:
<literal>true</literal>, <literal>false</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_direct_seuqence">Sequences</link>:
<literal>["foo", "bar", 123.45]</literal>,
<literal>1..100</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_direct_hash">Hashes</link>:
<literal>{"name":"green mouse",
"price":150}</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_var">Retrieving
variables</link></para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_var_toplevel">Top-level
variables</link>: <literal>user</literal></para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_var_hash">Retrieving
data from a hash</link>: <literal>user.name</literal>,
<literal>user["name"]</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_var_sequence">Retrieving data
from a sequence</link>:
<literal>products[5]</literal></para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_var_special">Special
variable</link>: <literal>.main</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_stringop">String
operations</link></para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_stringop_interpolation">Interpolation
(or concatenation)</link>:
<literal>"Hello ${user}!"</literal> (or
<literal>"Free" + "Marker"</literal>)</para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_get_character">Getting a
character</link>: <literal>name[0]</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_sequenceop">Sequence
operations</link></para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_sequenceop_cat">Concatenation</link>:
<literal>users + ["guest"]</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_seqenceop_slice">Sequence
slice</link>: <literal>products[10..19]</literal> or
<literal>products[5..]</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_hashop">Hash
operations</link></para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_hashop_cat">Concatenation</link>:
<literal>passwords + {"joe":"secret42"}</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_arit">Arithmetical
calculations</link>: <literal>(x * 1.5 + 10) / 2 - y %
100</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_comparison">Comparison</link>:
<literal>x == y</literal>, <literal>x != y</literal>,
<literal>x < y</literal>, <literal>x > y</literal>,
<literal>x >= y</literal>, <literal>x <= y</literal>,
<literal>x &lt; y</literal>, ...etc.</para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_logicalop">Logical
operations</link>: <literal>!registered && (firstVisit
|| fromEurope)</literal></para>
</listitem>
<listitem>
<para><link
linkend="dgui_template_exp_builtin">Built-ins</link>:
<literal>name?upper_case</literal></para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_methodcall">Method
call</link>: <literal>repeat("What", 3)</literal></para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_missing">Missing value
handler operators</link>:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="dgui_template_exp_missing_default">Default
value</link>: <literal>name!"unknown"</literal> or
<literal>(user.name)!"unknown"</literal> or
<literal>name!</literal> or
<literal>(user.name)!</literal></para>
</listitem>
<listitem>
<para><link linkend="dgui_template_exp_missing_test">Missing
value test</link>: <literal>name??</literal> or
<literal>(user.name)??</literal></para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>See also: <link
linkend="dgui_template_exp_precedence">Operator
precedence</link></para>
</section>
<section xml:id="dgui_template_exp_direct">
<title>Specify values directly</title>
<indexterm>
<primary>literal</primary>
</indexterm>
<indexterm>
<primary>constant</primary>
</indexterm>
<para>Often you want to specify a value directly and not as a result
of some calculations.</para>
<section xml:id="dgui_template_exp_direct_string">
<title>Strings</title>
<indexterm>
<primary>string</primary>
<secondary>literal</secondary>
</indexterm>
<para>To specify a string value directly you give the text in
quotation marks, e.g.: <literal>"some text"</literal> or in
apostrophe-quote, e.g. <literal>'some text'</literal>. The two
forms are equivalent. If the text itself contains the character
used for the quoting (either <literal>"</literal> or
<literal>'</literal>) or backslashes, you have to precede them
with a backslash; this is called escaping. You can type any other
character, including <link linkend="gloss.lineBreak">line
breaks</link>, in the text directly. Example:</para>
<programlisting role="template">${"It's \"quoted\" and
this is a backslash: \\"}
${'It\'s "quoted" and
this is a backslash: \\'}</programlisting>
<para>will print:</para>
<programlisting role="output">It's "quoted" and
this is a backslash: \
It's "quoted" and
this is a backslash: \</programlisting>
<note>
<para>Of course, you could simply type the above text into the
template, without using
<literal>${<replaceable>...</replaceable>}</literal>. But we do
it here just for the sake of example, to demonstrate
expressions.</para>
</note>
<anchor xml:id="topic.escapeSequence" />
<indexterm>
<primary>escape sequences</primary>
</indexterm>
<para>This is the list of all supported escape sequences. All
other usage of backlash in string literals is an error and any
attempt to use the template will fail.</para>
<informaltable border="1">
<thead>
<tr>
<th>Escape sequence</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>\"</literal></td>
<td>Quotation mark (u0022)</td>
</tr>
<tr>
<td><literal>\'</literal></td>
<td>Apostrophe (a.k.a. apostrophe-quote) (u0027)</td>
</tr>
<tr>
<td><literal>\\</literal></td>
<td>Back slash (u005C)</td>
</tr>
<tr>
<td><literal>\n</literal></td>
<td>Line feed (u000A)</td>
</tr>
<tr>
<td><literal>\r</literal></td>
<td>Carriage return (u000D)</td>
</tr>
<tr>
<td><literal>\t</literal></td>
<td>Horizontal tabulation (a.k.a. tab) (u0009)</td>
</tr>
<tr>
<td><literal>\b</literal></td>
<td>Backspace (u0008)</td>
</tr>
<tr>
<td><literal>\f</literal></td>
<td>Form feed (u000C)</td>
</tr>
<tr>
<td><literal>\l</literal></td>
<td>Less-than sign: <literal><</literal></td>
</tr>
<tr>
<td><literal>\g</literal></td>
<td>Greater-than sign: <literal>></literal></td>
</tr>
<tr>
<td><literal>\a</literal></td>
<td>Ampersand: <literal>&</literal></td>
</tr>
<tr>
<td><literal>\x<replaceable>Code</replaceable></literal></td>
<td>Character given with its hexadecimal <link
linkend="gloss.unicode">Unicode</link> code (<link
linkend="gloss.UCS">UCS</link> code)</td>
</tr>
</tbody>
</informaltable>
<para>The <literal><replaceable>Code</replaceable></literal> after
the <literal>\x</literal> is 1 to 4 hexadecimal digits. For
example this all put a copyright sign into the string:
<literal>"\xA9 1999-2001"</literal>,
<literal>"\x0A9 1999-2001"</literal>,
<literal>"\x00A9 1999-2001"</literal>. When the character directly
after the last hexadecimal digit can be interpreted as hexadecimal
digit, you must use all 4 digits or else FreeMarker will be
confused.</para>
<para>Note that the character sequence <literal>${</literal> (and
<literal>#{</literal>) has special meaning. It's used to insert
the value of expressions (typically: the value of variables, as in
<literal>"Hello ${user}!"</literal>). This will be explained <link
linkend="dgui_template_exp_stringop_interpolation">later</link>.
If you want to print <literal>${</literal>, you should use raw
string literals as explained below.</para>
<indexterm>
<primary>raw string literal</primary>
</indexterm>
<para>A special kind of string literals is the raw string
literals. In raw string literals, backslash and
<literal>${</literal> have no special meaning, they are considered
as plain characters. To indicate that a string literal is a raw
string literal, you have to put an <literal>r</literal> directly
before the opening quotation mark or apostrophe-quote.
Example:</para>
<programlisting role="template">${r"${foo}"}
${r"C:\foo\bar"}</programlisting>
<para>will print:</para>
<programlisting role="output">${foo}
C:\foo\bar</programlisting>
</section>
<section xml:id="dgui_template_exp_direct_number">
<title>Numbers</title>
<indexterm>
<primary>number</primary>
<secondary>literal</secondary>
</indexterm>
<para>To specify a numerical value directly you type the number
without quotation marks. You have to use the dot as your decimal
separator and must not use any grouping separator symbols. You can
use <literal>-</literal> or <literal>+</literal> to indicate the
sign (<literal>+</literal> is redundant). Scientific notation is
not yet supported (so <literal>1E3</literal> is wrong). Also, you
cannot omit the 0 before the decimal separator (so
<literal>.5</literal> is wrong).</para>
<para>Examples of valid number literals: <literal>0.08</literal>,
<literal>-5.013</literal>, <literal>8</literal>,
<literal>008</literal>, <literal>11</literal>,
<literal>+11</literal></para>
<para>Note that numerical literals like <literal>08</literal>,
<literal>+8</literal>, <literal>8.00</literal> and
<literal>8</literal> are totally equivalent as they all symbolize
the number eight. Thus, <literal>${08}</literal>,
<literal>${+8}</literal>, <literal>${8.00}</literal> and
<literal>${8}</literal> will all print exactly same.</para>
</section>
<section xml:id="dgui_template_exp_direct_boolean">
<title>Booleans</title>
<indexterm>
<primary>boolean</primary>
<secondary>literal</secondary>
</indexterm>
<indexterm>
<primary>literal</primary>
<secondary>boolean</secondary>
</indexterm>
<para>To specify a boolean value you write <literal>true</literal>
or <literal>false</literal>. Don't use quotation marks.</para>
</section>
<section xml:id="dgui_template_exp_direct_seuqence">
<title>Sequences</title>
<indexterm>
<primary>sequence</primary>
<secondary>literal</secondary>
</indexterm>
<indexterm>
<primary>numerical sequence</primary>
</indexterm>
<indexterm>
<primary>numerical range expression</primary>
</indexterm>
<indexterm>
<primary>range expression</primary>
</indexterm>
<para>To specify a literal sequence, you list the <link
linkend="topic.dataModel.subVar">subvariables</link> separated by
commas, and put the whole list into square brackets. For
example:</para>
<programlisting role="template"><#list <emphasis>["winter", "spring", "summer", "autumn"]</emphasis> as x>
${x}
</#list></programlisting>
<para>will print:</para>
<programlisting role="output">winter
spring
summer
autumn
</programlisting>
<para>The items in the list are expressions, so you can do this
for example: <literal>[2 + 2, [1, 2, 3, 4], "whatnot"]</literal>.
Here the first subvariable will be the number 4, the second will
be another sequence, and the third subvariable will be the string
"whatnot".</para>
<para>You can define sequences that store a numerical range with
<literal><replaceable>start</replaceable>..<replaceable>end</replaceable></literal>,
where <literal><replaceable>start</replaceable></literal> and
<literal><replaceable>end</replaceable></literal> are expressions
that resolve to numerical values. For example
<literal>2..5</literal> is the same as <literal>[2, 3, 4,
5]</literal>, but the former is much more efficient (occupies less
memory and faster). Note that the square brackets are missing. You
can define decreasing numerical ranges too, e.g.:
<literal>5..2</literal>. (Furthermore, you can omit the
<literal><replaceable>end</replaceable></literal>, for example
<literal>5..</literal>, in which case the sequence will contain 5,
6, 7, 8, ...etc up to the infinity.)</para>
</section>
<section xml:id="dgui_template_exp_direct_hash">
<title>Hashes</title>
<indexterm>
<primary>hash</primary>
<secondary>literal</secondary>
</indexterm>
<indexterm>
<primary>literal</primary>
<secondary>hash</secondary>
</indexterm>
<para>To specify a hash in a template, you list the key/value
pairs separated by commas, and put the list into curly brackets.
The key and value within a key/value pair are separated with a
colon. Here is an example: <literal>{"name":"green mouse",
"price":150}</literal>. Note that both the names and the values
are expressions. However, the lookup names must be strings.</para>
</section>
</section>
<section xml:id="dgui_template_exp_var">
<title>Retrieving variables</title>
<section xml:id="dgui_template_exp_var_toplevel">
<title>Top-level variables</title>
<indexterm>
<primary>subvariable</primary>
<secondary>accessing</secondary>
</indexterm>
<para>To access a top-level variable, you simply use the variable
name. For example, the expression <literal>user</literal> will
evaluate to the value of variable stored with name ``user'' in the
root. So this will print what you store there:</para>
<programlisting role="template">${user}</programlisting>
<para>If there is no such top-level variable, then an error will
result when FreeMarker tries to evaluate the expression, and it
aborts template processing (unless programmers has configured
FreeMarker differently).</para>
<para>In this expression the variable name can contain only
letters (including non-Latin letters), digits (including non-Latin
digits), underline (_), dollar ($), at sign (@) and hash (#).
Furthermore, the name must not start with digit.</para>
</section>
<section xml:id="dgui_template_exp_var_hash">
<title>Retrieving data from a hash</title>
<indexterm>
<primary>subvariable</primary>
<secondary>accessing</secondary>
</indexterm>
<indexterm>
<primary>hash</primary>
<secondary>accessing subvariable</secondary>
</indexterm>
<para>If we already have a hash as a result of an expression, then
we can get its subvariable with a dot and the name of the
subvariable. Assume that we have this data-model:</para>
<programlisting role="dataModel">(root)
|
+- book
| |
| +- title = "Breeding green mouses"
| |
| +- author
| |
| +- name = "Julia Smith"
| |
| +- info = "Biologist, 1923-1985, Canada"
|
+- test = "title"</programlisting>
<para>Now we can read the <literal>title</literal> with
<literal>book.title</literal>, since the book expression will
return a hash (as explained in the last chapter). Applying this
logic further, we can read the name of the author with this
expression: <literal>book.author.name</literal>.</para>
<para>There is an alternative syntax if we want to specify the
subvariable name with an expression:
<literal>book["title"]</literal>. In the square brackets you can
give any expression as long as it evaluates to a string. So with
this data-model you can also read the title with
<literal>book[test]</literal>. More examples; these are all
equivalent: <literal>book.author.name</literal>,
<literal>book["author"].name</literal>,
<literal>book.author.["name"]</literal>,
<literal>book["author"]["name"]</literal>.</para>
<para>When you use the dot syntax, the same restrictions apply
regarding the variable name as with top-level variables (name can
contain only letters, digits, _, $, @, etc.). There are no such
restrictions when you use the square bracket syntax, since the
name is the result of an arbitrary expression. (Note, that to help
the FreeMarker XML support, if the subvariable name is
<literal>*</literal> (asterisk) or <literal>**</literal>, then you
do not have to use square bracket syntax.)</para>
<para>As with the top-level variables, trying to access a
non-existent subvariable causes an error and aborts the processing
of the template (unless programmers has configured FreeMarker
differently).</para>
</section>
<section xml:id="dgui_template_exp_var_sequence">
<title>Retrieving data from a sequence</title>
<indexterm>
<primary>subvariable</primary>
<secondary>accessing</secondary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>accessing subvariable</secondary>
</indexterm>
<para>This is the same as for hashes, but you can use the square
bracket syntax only, and the expression in the brackets must
evaluate to a number, not a string. For example to get the name of
the first animal of the <link
linkend="example.stdDataModel">example data-model</link> (remember
that the number of the first item is 0, not 1):
<literal>animals[0].name</literal></para>
</section>
<section xml:id="dgui_template_exp_var_special">
<title>Special variables</title>
<indexterm>
<primary>special variables</primary>
</indexterm>
<para>Special variables are variables defined by the FreeMarker
engine itself. To access them, you use the
<literal>.<replaceable>variable_name</replaceable></literal>
syntax.</para>
<para>Normally you don't need to use special variables. They are
for expert users. The complete list of special variables can be
found in the <link linkend="ref_specvar">reference</link>.</para>
</section>
</section>
<section xml:id="dgui_template_exp_stringop">
<title>String operations</title>
<indexterm>
<primary>string</primary>
<secondary>operations</secondary>
</indexterm>
<section xml:id="dgui_template_exp_stringop_interpolation">
<title>Interpolation (or concatenation)</title>
<indexterm>
<primary>interpolation</primary>
</indexterm>
<indexterm>
<primary>concatenate strings</primary>
</indexterm>
<indexterm>
<primary>joining strings</primary>
</indexterm>
<indexterm>
<primary>string</primary>
<secondary>concatenate</secondary>
</indexterm>
<indexterm>
<primary>string</primary>
<secondary>interpolation</secondary>
</indexterm>
<indexterm>
<primary>adding strings</primary>
</indexterm>
<para>If you want to insert the value of an expression into a
string, you can use
<literal>${<replaceable>...</replaceable>}</literal> (and
<literal>#{<replaceable>...</replaceable>}</literal>) in string
literals. <literal>${<replaceable>...</replaceable>}</literal>
behaves similarly as in <phrase role="markedText">text</phrase>
sections. For example (assume that user is ``Big Joe''):</para>
<programlisting role="template">${"Hello ${user}!"}
${"${user}${user}${user}${user}"}</programlisting>
<para>will print:</para>
<programlisting role="output">Hello Big Joe!
Big JoeBig JoeBig JoeBig Joe</programlisting>
<para>Alternatively, you can use the <literal>+</literal> operator
to achieve similar result. This is the old method, and it is
called string concatenation. Example:</para>
<programlisting role="template">${"Hello " + user + "!"}
${user + user + user + user}</programlisting>
<para>This will print the same as the example with the
<literal>${<replaceable>...</replaceable>}</literal>-s.</para>
<warning>
<para>A frequent mistake of users is the usage of interpolations
in places where it shouldn't/can't be used. Interpolations work
<emphasis>only</emphasis> in <link
linkend="dgui_template_overallstructure"><phrase
role="markedText">text</phrase> sections</link> (e.g.
<literal><h1>Hello ${name}!</h1></literal>) and in
string literals (e.g. <literal><#include
"/footer/${company}.html"></literal>). A typical bad usage is
<literal><#if ${isBig}>Wow!</#if></literal>, which
is syntactically <emphasis>WRONG</emphasis>. You should simply
write <literal><#if isBig>Wow!</#if></literal>.
Also, <literal><#if "${isBig}">Wow!</#if></literal>
is <emphasis>WRONG</emphasis> too, since the parameter value
will be a string, and the <literal>if</literal> directive wants
a boolean value, so it will cause a runtime error.</para>
</warning>
</section>
<section xml:id="dgui_template_exp_get_character">
<title>Getting a character</title>
<indexterm>
<primary>charAt</primary>
</indexterm>
<indexterm>
<primary>get character</primary>
</indexterm>
<para>You can get a single character of a string at a given index
similarly as you can <link
linkend="dgui_template_exp_var_sequence">read the subvariable of a
sequence</link>, e.g. <literal>user[0]</literal>. The result will
be a string whose length is 1; FTL doesn't have a separate
character type. As with sequence subvariables, the index must be a
number that is at least 0 and less than the length of the string,
or else an error will abort the template processing.</para>
<para>Since the sequence subvariable syntax and the character
getter syntax clashes, you can use the character getter syntax
only if the variable is not a sequence as well (which is possible
because FTL supports multi-typed values), since in that case the
sequence behavior prevails. (To work this around, you can use
<link linkend="ref_builtin_string_for_string">the
<literal>string</literal> built-in</link>, e.g.
<literal>user?string[0]</literal>. Don't worry if you don't
understand this yet; built-ins will be discussed later.)</para>
<para>Example (assume that user is ``Big Joe''):</para>
<programlisting role="template">${user[0]}
${user[4]}</programlisting>
<para>will print (note that the index of the first character is
0):</para>
<programlisting role="output">B
J
</programlisting>
<note>
<para>You can get a range of characters in the same way as you
<link linkend="dgui_template_exp_seqenceop_slice">get a sequence
slice</link>, e.g <literal>${user[1..4]}</literal> and
<literal>${user[4..]}</literal>. However, it's now depreacted to
utilize this, and instead you should use <link
linkend="ref_builtin_substring">the <literal>substring</literal>
built-in</link>; built-ins will be discussed later.</para>
</note>
</section>
</section>
<section xml:id="dgui_template_exp_sequenceop">
<title>Sequence operations</title>
<indexterm>
<primary>sequence</primary>
<secondary>operations</secondary>
</indexterm>
<section xml:id="dgui_template_exp_sequenceop_cat">
<title>Concatenation</title>
<indexterm>
<primary>concatenate sequences</primary>
</indexterm>
<indexterm>
<primary>joining sequences</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>concatenate</secondary>
</indexterm>
<indexterm>
<primary>adding sequences</primary>
</indexterm>
<para>You can concatenate sequences in the same way as strings,
with <literal>+</literal>. Example:</para>
<programlisting role="template"><#list ["Joe", "Fred"] + ["Julia", "Kate"] as user>
- ${user}
</#list></programlisting>
<para>will print:</para>
<programlisting role="output">- Joe
- Fred
- Julia
- Kate
</programlisting>
<para>Note that sequence concatenation is not to be used for many
repeated concatenations, like for appending items to a sequence
inside a loop. It's just for things like <literal><#list users
+ admins as person></literal>. Although concatenating sequences
is fast and its speed is independently of the size of the
concatenated sequences, the resulting sequence will be always a
little bit slower to read than the original two sequences were.
This way the result of many repeated concatenations is a sequence
that is slow to read.</para>
</section>
<section xml:id="dgui_template_exp_seqenceop_slice">
<title>Sequence slice</title>
<indexterm>
<primary>sequence slice</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>slice</secondary>
</indexterm>
<indexterm>
<primary>subsequence</primary>
</indexterm>
<para>With
<literal>[<replaceable>firstindex</replaceable>..<replaceable>lastindex</replaceable>]</literal>
you can get a slice of a sequence, where
<literal><replaceable>firstindex</replaceable></literal> and
<literal><replaceable>lastindex</replaceable></literal> are
expressions evaluate to number. For example, if
<literal>seq</literal> stores the sequence <literal>"a"</literal>,
<literal>"b"</literal>, <literal>"c"</literal>,
<literal>"d"</literal>, <literal>"e"</literal>,
<literal>"f"</literal> then the expression
<literal>seq[1..4]</literal> will evaluate to a sequence that
contains <literal>"b"</literal>, <literal>"c"</literal>,
<literal>"d"</literal>, <literal>"e"</literal> (since the item at
index 1 is <literal>"b"</literal>, and the item at index 4 is
<literal>"e"</literal>).</para>
<para>The <literal><replaceable>lastindex</replaceable></literal>
can be omitted, in which case it defaults to the index of the last
item of the sequence. For example, if <literal>seq</literal>
stores the sequence <literal>"a"</literal>,
<literal>"b"</literal>, <literal>"c"</literal>,
<literal>"d"</literal>, <literal>"e"</literal>,
<literal>"f"</literal> again, then <literal>seq[3..]</literal>
will evaluate to a sequence that contains <literal>"d"</literal>,
<literal>"e"</literal>, <literal>"f"</literal>.</para>
<note>
<para><literal><replaceable>lastindex</replaceable></literal>
can be omitted only since FreeMarker 2.3.3.</para>
</note>
<para>An attempt to access a subvariable past the last subvariable
or before the first subvariable of the sequence will cause an
error and abort the processing of the template.</para>
</section>
</section>
<section xml:id="dgui_template_exp_hashop">
<title>Hash operations</title>
<indexterm>
<primary>hash</primary>
<secondary>operations</secondary>
</indexterm>
<section xml:id="dgui_template_exp_hashop_cat">
<title>Concatenation</title>
<indexterm>
<primary>concatenate hashes</primary>
</indexterm>
<indexterm>
<primary>joining hashes</primary>
</indexterm>
<indexterm>
<primary>hash</primary>
<secondary>concatenate</secondary>
</indexterm>
<indexterm>
<primary>adding hashes</primary>
</indexterm>
<para>You can concatenate hashes in the same way as strings, with
<literal>+</literal>. If both hashes contain the same key, the
hash on the right-hand side of the <literal>+</literal> takes
precedence. Example:</para>
<programlisting role="template"><#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}>
- Joe is ${ages.Joe}
- Fred is ${ages.Fred}
- Julia is ${ages.Julia}
</programlisting>
<para>will print:</para>
<programlisting role="output">- Joe is 30
- Fred is 25
- Julia is 18</programlisting>
<para>Note that hash concatenation is not to be used for many
repeated concatenations, like for adding items to a hash inside a
loop. It's the same as with the <link
linkend="dgui_template_exp_sequenceop_cat">sequence
concatenation</link>.</para>
</section>
</section>
<section xml:id="dgui_template_exp_arit">
<title>Arithmetical calculations</title>
<indexterm>
<primary>arithmetic</primary>
</indexterm>
<indexterm>
<primary>math</primary>
</indexterm>
<indexterm>
<primary>addition</primary>
</indexterm>
<indexterm>
<primary>subtraction</primary>
</indexterm>
<indexterm>
<primary>division</primary>
</indexterm>
<indexterm>
<primary>modulus</primary>
</indexterm>
<para>This is the basic 4-function calculator arithmetic plus the
modulus operator. So the operators are:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Addition: <literal>+</literal></para>
</listitem>
<listitem>
<para>Subtraction: <literal>-</literal></para>
</listitem>
<listitem>
<para>Multiplication: <literal>*</literal></para>
</listitem>
<listitem>
<para>Division: <literal>/</literal></para>
</listitem>
<listitem>
<para>Modulus (remainder): <literal>%</literal></para>
</listitem>
</itemizedlist>
<remark>Information about the precision?</remark>
<para>Example:</para>
<programlisting role="template">${100 - x * x}
${x / 2}
${12 % 10}</programlisting>
<para>Assuming that <literal>x</literal> is 5, it will print:</para>
<programlisting role="output">75
2.5
2</programlisting>
<para>Both operands must be expressions which evaluate to a
numerical value. So the example below will cause an error when
FreeMarker tries to evaluate it, since <literal>"5"</literal> is a
string and not the number 5:</para>
<programlisting role="template">${3 * "5"} <#-- WRONG! --></programlisting>
<para>There is an exception to the above rule. The
<literal>+</literal> operator, is used to <link
linkend="dgui_template_exp_stringop_interpolation">concatenate
strings</link> as well. If on one side of <literal>+</literal> is a
string and on the other side of <literal>+</literal> is a numerical
value, then it will convert the numerical value to string (using the
format appropriate for language of the page) and then use the
<literal>+</literal> as string concatenation operator.
Example:</para>
<programlisting role="template">${3 + "5"}</programlisting>
<para>will output this:</para>
<programlisting role="output">35</programlisting>
<para>Generally, FreeMarker never converts a string to a number
automatically, but it may convert a number to a string
automatically.</para>
<para><indexterm>
<primary>integer division</primary>
</indexterm><indexterm>
<primary>integer part</primary>
</indexterm> People often want only the integer part of the result
of a division (or of other calculations). This is possible with the
<literal>int</literal> built-in. (Built-ins are explained <link
linkend="dgui_template_exp_builtin">later</link>):</para>
<programlisting role="template">${(x/2)?int}
${1.1?int}
${1.999?int}
${-1.1?int}
${-1.999?int}</programlisting>
<para>Assuming that <literal>x</literal> is 5, it will print:</para>
<programlisting role="output">2
1
1
-1
-1</programlisting>
</section>
<section xml:id="dgui_template_exp_comparison">
<title>Comparison</title>
<indexterm>
<primary>comparison operators</primary>
</indexterm>
<para>Sometimes you want to know if two values are equal or not, or
which value is the greater.</para>
<para>To show concrete examples I will use the <literal>if</literal>
directive here. The usage of <literal>if</literal> directive is:
<literal><#if
<replaceable>expression</replaceable>>...</#if></literal>,
where expression must evaluate to a boolean value or else an error
will abort the processing of the template. If the value of
expression is <literal>true</literal> then the things between the
begin and end-tag will be processed, otherwise they will be
skipped.</para>
<para>To test two values for equality you use <literal>=</literal>
(or <literal>==</literal> as in Java or C; the two are absolutely
equivalent.) To test two values for inequality you use
<literal>!=</literal>. For example, assume that
<literal>user</literal> is ``Big Joe'':</para>
<programlisting role="template"><#if <emphasis>user = "Big Joe"</emphasis>>
It is Big Joe
</#if>
<#if <emphasis>user != "Big Joe"</emphasis>>
It is not Big Joe
</#if></programlisting>
<para>The <literal>user = "Big Joe"</literal> expression in the
<literal><#if ...></literal> will evaluate to the boolean
<literal>true</literal>, so the above will say ``It is Big
Joe''.</para>
<para>The expressions on both sides of the <literal>=</literal> or
<literal>!=</literal> must evaluate to a scalar. Furthermore, the
two scalars must have the same type (i.e. strings can only be
compared to strings and numbers can only be compared to numbers,
etc.) or else an error will abort template processing. For example
<literal><#if 1 = "1"></literal> will cause an error. Note
that FreeMarker does exact comparison, so string comparisons are
case and white-space sensitive: <literal>"x"</literal> and
<literal>"x "</literal> and <literal>"X"</literal> are not equal
values.</para>
<para>For numerical and date values you can also use
<literal><</literal>, <literal><=</literal>,
<literal>>=</literal> and <literal>></literal>. You can't use
them for strings! Example:</para>
<programlisting role="template"><#if x <emphasis><=</emphasis> 12>
x is less or equivalent with 12
</#if></programlisting>
<para>There is a little problem with <literal>>=</literal> and
<literal>></literal>. FreeMarker interprets the
<literal>></literal> as the closing character of the FTL tag. To
prevent this, you have to put the expression into <link
linkend="dgui_template_exp_parentheses">parentheses</link>:
<literal><#if (x > y)></literal>. Or, you can use
<literal>&gt;</literal> and <literal>&lt;</literal> on the
place of the problematic relation marks: <literal><#if x &gt;
y></literal>. (Note that in general FTL does not support entity
references (those
<literal>&<replaceable>...</replaceable>;</literal> things) in
FTL tags; it is just an exception with the arithmetical
comparisons.). Also, as an alternative you can use
<literal>lt</literal> instead of <literal><</literal>,
<literal>lte</literal> instead of <literal><=</literal>,
<literal>gt</literal> instead of <literal>></literal> and
<literal>gte</literal> instead of <literal>>=</literal>. And, for
historical reasons FTL also understands <literal>\lt</literal>,
<literal>\lte</literal>, <literal>\gt</literal> and
<literal>\gte</literal> which are the same as the ones without the
backslash.</para>
</section>
<section xml:id="dgui_template_exp_logicalop">
<title>Logical operations</title>
<indexterm>
<primary>boolean</primary>
<secondary>operations</secondary>
</indexterm>
<indexterm>
<primary>logical operations</primary>
</indexterm>
<indexterm>
<primary>or</primary>
</indexterm>
<indexterm>
<primary>and</primary>
</indexterm>
<indexterm>
<primary>not</primary>
</indexterm>
<para>Just the usual logical operators:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Logical or: <literal>||</literal></para>
</listitem>
<listitem>
<para>Logical and: <literal>&&</literal></para>
</listitem>
<listitem>
<para>Logical not: <literal>!</literal></para>
</listitem>
</itemizedlist>
<para>The operators will work with boolean values only. Otherwise an
error will abort the template processing.</para>
<para>Example:</para>
<programlisting role="template"><#if x < 12 <emphasis>&&</emphasis> color = "green">
We have less than 12 things, and they are green.
</#if>
<#if <emphasis>!</emphasis>hot> <#-- here hot must be a boolean -->
It's not hot.
</#if></programlisting>
</section>
<section xml:id="dgui_template_exp_builtin">
<title>Built-ins</title>
<indexterm>
<primary>built-in</primary>
</indexterm>
<para>Built-ins provide, as the name suggest, certain built-in
functionality that is always available. Typically, a built-in
provides a different version of a variable, or some information
about the variable in question. The syntax for accessing a built-in
is like that of accessing a subvariable in a hash, except that you
use the question mark instead of a dot. For example, to get the
upper case version of a string:
<literal>user?upper_case</literal>.</para>
<para>You can find the complete <link linkend="ref_builtins">list of
built-ins in the Reference</link>. For now, just a few of the more
important ones:</para>
<itemizedlist>
<listitem>
<para>Built-ins to use with strings:</para>
<itemizedlist>
<listitem>
<para><literal>html</literal>: The string with all special
HTML characters replaced with entity references (E.g.
<literal><</literal> with
<literal>&lt;</literal>)</para>
</listitem>
<listitem>
<para><literal>cap_first</literal>: The string with the
first letter converted to upper case</para>
</listitem>
<listitem>
<para><literal>lower_case</literal>: The lowercase version
of the string</para>
</listitem>
<listitem>
<para><literal>upper_case</literal>: The uppercase version
of the string</para>
</listitem>
<listitem>
<para><literal>trim</literal>: The string without leading
and trailing <link
linkend="gloss.whiteSpace">white-spaces</link></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Built-ins to use with sequences:</para>
<itemizedlist>
<listitem>
<para><literal>size</literal>: The number of elements in the
sequence</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Built-ins to use with numbers:</para>
<itemizedlist>
<listitem>
<para><literal>int</literal>: The integer part of a number
(e.g. <literal>-1.9?int</literal> is
<literal>-1</literal>)</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting role="template">${test?html}
${test?upper_case?html}</programlisting>
<para>Assuming that <literal>test</literal> stores the string ``Tom
& Jerry'', the output will be:</para>
<programlisting role="output">Tom &amp; Jerry
TOM &amp; JERRY</programlisting>
<para>Note the <literal>test?upper_case?html</literal>. Since the
result of <literal>test?upper_case</literal> is a string, you can
use the <literal>html</literal> built-in with it.</para>
<para>Another example:</para>
<programlisting role="template">${seasons?size}
${seasons[1]?cap_first} <#-- left side can by any expression -->
${"horse"?cap_first}</programlisting>
<para>Assuming that <literal>seasons</literal> stores the sequence
<literal>"winter"</literal>, <literal>"spring"</literal>,
<literal>"summer"</literal>, <literal>"autumn"</literal>, the output
will be:</para>
<programlisting role="output">4
Spring
Horse</programlisting>
</section>
<section xml:id="dgui_template_exp_methodcall">
<title>Method call</title>
<indexterm>
<primary>call a method</primary>
</indexterm>
<indexterm>
<primary>method</primary>
<secondary>call</secondary>
</indexterm>
<para>If you have a method then you can use the method call
operation on it. The method call operation is a comma-separated list
of expressions in parentheses. These values are called parameters.
The method call operation passes these values to the method which
will in turn return a result. This result will be the value of the
whole method call expression.</para>
<para>For example, assume the programmers have made available a
method variable called <literal>repeat</literal>. You give a string
as the first parameter, and a number as the second parameter, and it
returns a string which repeats the first parameter the number of
times specified by the second parameter.</para>
<programlisting role="template">${repeat("What", 3)}</programlisting>
<para>will print:</para>
<programlisting role="output">WhatWhatWhat</programlisting>
<para>Here <literal>repeat</literal> was evaluated to the method
variable (according to how you <link
linkend="dgui_template_exp_var_toplevel">access top-level
variables</link>) and then <literal>("What", 3)</literal> invoked
that method.</para>
<para>I would like to emphasize that method calls are just plain
expressions, like everything else. So this:</para>
<programlisting role="template">${repeat(repeat("x", 2), 3) + repeat("What", 4)?upper_case}</programlisting>
<para>will print this:</para>
<programlisting role="output">xxxxxxWHATWHATWHATWHAT</programlisting>
</section>
<section xml:id="dgui_template_exp_missing">
<title>Handling missing values</title>
<note>
<para>These operators exist since FreeMarker 2.3.7 (replacing the
<literal>default</literal>, <literal>exists</literal> and
<literal>if_exists</literal> built-ins).</para>
</note>
<indexterm>
<primary>undefined variable</primary>
</indexterm>
<indexterm>
<primary>missing variable</primary>
</indexterm>
<indexterm>
<primary>null</primary>
</indexterm>
<indexterm>
<primary>handling null-s</primary>
</indexterm>
<indexterm>
<primary>error handling</primary>
</indexterm>
<para>As we explained earlier, an error will occur and abort the
template processing if you try to access a missing variable. However
two special operators can suppress this error, and handle the
problematic situation. The handled variable can be top-level
variable, hash subvariable, or sequence subvariable as well.
Furthermore these operators handle the situation when a method call
doesn't return a value <phrase role="forProgrammers">(from the
viewpoint of Java programmers: it returns <literal>null</literal> or
it's return type is <literal>void</literal>)</phrase>, so it's more
correct to say that these operators handle missing values in
general, rather than just missing variables.</para>
<para><phrase role="forProgrammers">For those who know what's Java
<literal>null</literal>, FreeMarker 2.3.<replaceable>x</replaceable>
treats them as missing values. Simply, the template language doesn't
know the concept of <literal>null</literal>. For example, if you
have a bean that has a <literal>maidenName</literal> property, and
the value of that property is <literal>null</literal>, then that's
the same as if there were no such property at all, as far as the
template is concerned (assuming you didn't configured FreeMarker to
use some extreme object wrapper, that is). The result of a method
call that returns <literal>null</literal> is also treated as a
missing variable (again, assuming that you use some usual object
wrapper). See more <link linkend="faq_null">in the
FAQ</link>.</phrase></para>
<note>
<para>If you wonder why is FreeMarker so picky about missing
variables, <link linkend="faq_picky_about_missing_vars">read this
FAQ entry</link>.</para>
</note>
<section xml:id="dgui_template_exp_missing_default">
<title>Default value operator</title>
<indexterm>
<primary>default value operator</primary>
</indexterm>
<para>Synopsis:
<literal><replaceable>unsafe_expr</replaceable>!<replaceable>default_expr</replaceable></literal>
or <literal><replaceable>unsafe_expr</replaceable>!</literal> or
<literal>(<replaceable>unsafe_expr</replaceable>)!<replaceable>default_expr</replaceable></literal>
or
<literal>(<replaceable>unsafe_expr</replaceable>)!</literal></para>
<para>This operator allows you to specify a default value for the
case when the value is missing.</para>
<para>Example. Assume no variable called <literal>mouse</literal>
is present:</para>
<programlisting role="template">${mouse!"No mouse."}
<#assign mouse="Jerry">
${mouse!"No mouse."}</programlisting>
<para>The output will be:</para>
<programlisting role="output">No mouse.
Jerry</programlisting>
<para>The default value can be any kind of expression, so it
doesn't have to be a string. For example you can write
<literal>hits!0</literal> or <literal>colors!["red", "green",
"blue"]</literal>. There is no restriction regarding the
complexity of the expression that specifies the default value, for
example you can write: <literal>cargo.weight!(item.weight *
itemCount + 10)</literal>.</para>
<warning>
<para>If you have a composite expression after the
<literal>!</literal>, like <literal>1 + x</literal>,
<emphasis>always</emphasis> use parenthesses, like
<literal>${x!(1 + y)}</literal> or <literal>${(x!1) +
y)}</literal>, depending on which interpretation you meant.
That's needed because due to a programming mistake in FreeMarker
2.3.x, the precedence of <literal>!</literal> (when it's used as
default value operator) is very low at its right side. This
means that, for example, <literal>${x!1 + y}</literal> is
misinterpreted by FreeMarker as <literal>${x!(1 + y)}</literal>
while it should mean <literal>${(x!1) + y}</literal>. This
programming error will be fixed in FreeMarker 2.4, so you should
not utilize this wrong behavior, or else your templates will
break with FreeMarker 2.4!</para>
</warning>
<para>If the default value is omitted, then it will be empty
string and empty sequence and empty hash at the same time. (This
is possible because FreeMarker allows multi-type values.) Note the
consequence that you can't omit the default value if you want it
to be <literal>0</literal> or <literal>false</literal>.
Example:</para>
<programlisting role="template">(${mouse!})
<#assign mouse = "Jerry">
(${mouse!})</programlisting>
<para>The output will be:</para>
<programlisting role="output">()
(Jerry)</programlisting>
<warning>
<para>Due to syntactical ambiguities <literal><@something
a=x! b=y /></literal> will be interpreted as
<literal><@something a=x!(b=y) /></literal>, that is, the
<literal>b=y</literal> will be interpreted as a comparison that
gives the default value for <literal>x</literal>, rather than
the specification of the <literal>b</literal> parameter. To
prevent this, write: <literal><@something a=(x!) b=y
/></literal></para>
</warning>
<para>You can use this operator in two ways with non-top-level
variables:</para>
<programlisting role="template">product.color!"red"</programlisting>
<para>This will handle if <literal>color</literal> is missing
inside <literal>product</literal> (and returns
<literal>"red"</literal> if so), but will not handle if
<literal>product</literal> is missing. That is, the
<literal>product</literal> variable itself must exist, otherwise
the template processing will die with error.</para>
<programlisting role="template">(product.color)!"red"</programlisting>
<para>This will handle if <literal>product.color</literal> is
missing. That is, if <literal>product</literal> is missing, or
<literal>product</literal> exists but it does not contain
<literal>color</literal>, the result will be
<literal>"red"</literal>, and no error will occur. The important
difference between this and the previous example is that when
surrounded with parentheses, it is allowed for any component of
the expression to be undefined, while without parentheses only the
last component of the expression is allowed to be
undefined.</para>
<para>Of course, the default value operator can be used with
sequence subvariables as well:</para>
<programlisting role="template"><#assign seq = ['a', 'b']>
${seq[0]!'-'}
${seq[1]!'-'}
${seq[2]!'-'}
${seq[3]!'-'}</programlisting>
<para>the outpur will be:</para>
<programlisting role="output">a
b
-
-</programlisting>
<para>A negative sequence index (as
<literal>seq[-1]!'-'</literal>) will always cause an error, you
can't suppress that with this or any other operator.</para>
</section>
<section xml:id="dgui_template_exp_missing_test">
<title>Missing value test operator</title>
<indexterm>
<primary>existence test operator</primary>
</indexterm>
<indexterm>
<primary>missing value test operator</primary>
</indexterm>
<indexterm>
<primary>testing for null</primary>
</indexterm>
<indexterm>
<primary>testing for missing</primary>
</indexterm>
<indexterm>
<primary>testing for undefined</primary>
</indexterm>
<indexterm>
<primary>is null</primary>
</indexterm>
<para>Synopsis:
<literal><replaceable>unsafe_expr</replaceable>??</literal> or
<literal>(<replaceable>unsafe_expr</replaceable>)??</literal></para>
<para>This operator tells if a value is missing or not. Depending
on that, the result is either <literal>true</literal> or
<literal>false</literal>.</para>
<para>Example. Assume no variable called <literal>mouse</literal>
is present:</para>
<programlisting role="template"><#if mouse??>
Mouse found
<#else>
No mouse found
</#if>
Creating mouse...
<#assign mouse = "Jerry">
<#if mouse??>
Mouse found
<#else>
No mouse found
</#if></programlisting>
<para>The output will be:</para>
<programlisting role="output"> No mouse found
Creating mouse...
Mouse found</programlisting>
<para>With non-top-level variables the rules are the same as with
the default value operator, that is, you can write
<literal>product.color??</literal> and
<literal>(product.color)??</literal>.</para>
</section>
</section>
<section xml:id="dgui_template_exp_parentheses">
<title>Parentheses</title>
<indexterm>
<primary>parentheses</primary>
</indexterm>
<para>Parentheses can be used to group any expressions. Some
examples:</para>
<programlisting role="template"> <#-- Output will be: -->
${3 * 2 + 2} <#-- 8 -->
${3 * (2 + 2)} <#-- 12 -->
${3 * ((2 + 2) * (1 / 2))} <#-- 6 -->
${"green " + "mouse"?upper_case} <#-- green MOUSE -->
${("green " + "mouse")?upper_case} <#-- GREEN MOUSE -->
<#if !( color = "red" || color = "green")>
The color is nor red nor green
</#if></programlisting>
<para>Note that the parentheses of a <link
linkend="dgui_template_exp_methodcall">method call
expressions</link> have nothing to do with the parentheses used for
grouping.</para>
</section>
<section xml:id="dgui_template_exp_whitespace">
<title>White-space in expressions</title>
<para>FTL ignores superfluous <link
linkend="gloss.whiteSpace">white-space</link> in expressions. So
these are totally equivalent:</para>
<programlisting role="template">${x + ":" + book.title?upper_case}</programlisting>
<para>and</para>
<programlisting role="template">${x+":"+book.title?upper_case}</programlisting>
<para>and</para>
<programlisting role="template">${
x
+ ":" + book . title
? upper_case
}</programlisting>
</section>
<section xml:id="dgui_template_exp_precedence">
<title>Operator precedence</title>
<indexterm>
<primary>precedence</primary>
</indexterm>
<indexterm>
<primary>operator precedence</primary>
</indexterm>
<para>The following table shows the precedence assigned to the
operators. The operators in this table are listed in precedence
order: the higher in the table an operator appears, the higher its
precedence. Operators with higher precedence are evaluated before
operators with a relatively lower precedence. Operators on the same
line have equal precedence. When binary operators (operators with
two ``parameters'', as <literal>+</literal> and
<literal>-</literal>) of equal precedence appear next to each other,
they are evaluated in left-to-right order.</para>
<informaltable border="1">
<thead>
<tr>
<th>Operator group</th>
<th>Operators</th>
</tr>
</thead>
<tbody>
<tr>
<td>highest precedence operators</td>
<td><literal>[<replaceable>subvarName</replaceable>]
[<replaceable>subStringRange</replaceable>] . ?
(<replaceable>methodParams</replaceable>)
<replaceable>expr</replaceable>!
<replaceable>expr</replaceable>??</literal></td>
</tr>
<tr>
<td>unary prefix operators</td>
<td><literal>+<replaceable>expr</replaceable>
-<replaceable>expr</replaceable> !expr</literal></td>
</tr>
<tr>
<td>multiplicative</td>
<td><literal>* / %</literal></td>
</tr>
<tr>
<td>additive</td>
<td><literal>+ -</literal></td>
</tr>
<tr>
<td>relational</td>
<td><literal>< > <= >=</literal> (and quivalents:
<literal>gt</literal>, <literal>lt</literal>, etc.)</td>
</tr>
<tr>
<td>equality</td>
<td><literal>== !=</literal> (and equivalents:
<literal>=</literal>)</td>
</tr>
<tr>
<td>logical AND</td>
<td><literal>&&</literal></td>
</tr>
<tr>
<td>logical OR</td>
<td><literal>||</literal></td>
</tr>
<tr>
<td>numerical range</td>
<td><literal>..</literal></td>
</tr>
</tbody>
</informaltable>
<para>For those of you who master C, Java language or JavaScript,
note that the precedence rules are the same as in those languages,
except that FTL has some operators that do not exist in those
languages.</para>
<para>The default value operator
(<literal><replaceable>exp</replaceable>!<replaceable>exp</replaceable></literal>)
is not yet in the table because of a programming mistake, which will
be only fixed in FreeMarker 2.4 due to backward compatibility
constraints. It meant to be a "highest precedence operator", but in
FreeMarker 2.3.x the precedence on its right side is very low by
accident. So if you have a composite expression on the right side,
always use paranthesses, etiher like <literal>x!(y + 1)</literal> or
like <literal>(x!y) + 1</literal>. Never write just <literal>x!y +
1</literal>.</para>
</section>
</section>
<section xml:id="dgui_template_valueinsertion">
<title>Interpolations</title>
<indexterm>
<primary>interpolation</primary>
</indexterm>
<indexterm>
<primary>${...}</primary>
</indexterm>
<para>The format of interpolations is
<literal>${<replaceable>expression</replaceable>}</literal>, where
<literal><replaceable>expression</replaceable></literal> can be all
kind of expression (e.g. <literal>${100 + x}</literal>).</para>
<para>The interpolation is used to insert the value of the
<literal><replaceable>expression</replaceable></literal> converted to
text (to string). Interpolations can be used only on two places: in
<link linkend="dgui_template_overallstructure"><phrase
role="markedText">text</phrase> sections</link> (e.g.,
<literal><h1>Hello ${name}!</h1></literal>) and <link
linkend="dgui_template_exp_stringop_interpolation">in string literal
expressions</link> (e.g., <literal><#include
"/footer/${company}.html"></literal>).</para>
<warning>
<para>A frequent mistake is the usage of interpolations in places
where it shouldn't/can't be used. A typical bad usage is
<literal><#if ${isBig}>Wow!</#if></literal>, which is
syntactically <emphasis>WRONG</emphasis>. You should simply write
<literal><#if isBig>Wow!</#if></literal>. Also,
<literal><#if "${isBig}">Wow!</#if></literal> is
<emphasis>WRONG</emphasis>, since the parameter value will be a
string, and the <literal>if</literal> directive wants a boolean
value, so it will cause a runtime error.</para>
</warning>
<para>The result of the expression must be a string, number or date
value. This is because only numbers and dates will be converted to
string by the interpolation automatically, other types of values (such
as booleans, sequences) must be converted to string "manually" somehow
(see some advices later), or an error will stop the template
processing.</para>
<para>If the interpolation is in a <link
linkend="dgui_template_overallstructure"><phrase
role="markedText">text</phrase> section</link> (i.e., not in a <link
linkend="dgui_template_exp_stringop_interpolation">string literal
expression</link>), the string that it will insert will be
automatically escaped if an <link
linkend="ref.directive.escape"><literal>escape</literal>
directive</link> is in effect.</para>
<simplesect>
<title>Guide for inserting numerical values</title>
<para>If the expression evaluates to a number then the numerical
value will be converted to string according the default number
format. This may includes the maximum number of decimals, grouping,
and like. Usually the programmer should set the default number
format; the template author don't have to deal with it (but he can
with the <literal>number_format</literal> setting; see in the <link
linkend="ref_directive_setting">documentation of
<literal>setting</literal> directive</link>). You can override the
default number format for a single interpolation with the <link
linkend="ref_builtin_string_for_number"><literal>string</literal>
built-in</link>.</para>
<para>The decimal separator used (and other such symbols, like the
group separator) depends on the current locale (language, country),
that also should be set by the programmer. For example, this
template:</para>
<programlisting role="template">${1.5}</programlisting>
<para>will print something like this if the current locale is
English:</para>
<programlisting role="output">1.5</programlisting>
<para>but if the current locale is Hungarian then it will print
something like:</para>
<programlisting role="output">1,5</programlisting>
<para>since Hungarian people use comma as decimal separator.</para>
<para>You can modify the formatting for a single interpolation with
the <link
linkend="ref_builtin_string_for_number"><literal>string</literal>
built-in</link>.</para>
<warning>
<para>As you can see, interpolations print for human audience (by
default at least), as opposed to ''computer audience''. In some
cases this is not good, like when you print a database record ID-s
as the part of an URL or as an invisible field value in a HTML
form, or when you print CSS/JavaScript numerical literals, because
these printed values will be read by computer programs and not by
humans. Most computer programs are very particular about the
format of the numbers, and understand only a kind of simple US
number formatting. For that, use the <link
linkend="ref_builtin_c"><literal>c</literal></link> (stands for
''computer audience'') built-in, for example:</para>
<programlisting role="template"><a href="/shop/productdetails?id=${product.id?c}">Details...</a></programlisting>
</warning>
</simplesect>
<simplesect xml:id="dgui_template_valueinserion_universal_date">
<title>Guide for inserting date/time values</title>
<para>If the expression evaluates to a date then the numerical value
will be transformed to a text according to a default format. Usually
the programmer should set the default format; you don't have to deal
with it (but if you care, see the <literal>date_format</literal>,
<literal>time_format</literal> and
<literal>datetime_format</literal> settings in the <link
linkend="ref_directive_setting">documentation of the
<literal>setting</literal> directive</link>).</para>
<para>You can override the default formatting for a single
interpolation with the <link
linkend="ref_builtin_string_for_date"><literal>string</literal>
built-in</link>.</para>
<warning>
<para>To display a date as text, FreeMarker must know which parts
of the date are in use, that is, if only the date part (year,
month, day), or only the time part (hour, minute, second,
millisecond), or both. Unfortunately, because of the technical
limitations of Java platform, for some variables it is not
possible to detect this automatically; ask the programmer if the
data-model contains such problematic variables. If it is not
possible to find out which parts of the date are in use, then you
must help FreeMarker with the <link
linkend="ref_builtin_date_datetype"><literal>date</literal>,
<literal>time</literal> and <literal>datetime</literal></link>
built-ins, or it will stop with error.</para>
</warning>
</simplesect>
<simplesect>
<title>Guide for inserting boolean values</title>
<para>An attempt to print boolean values with interpolation causes
an error and aborts template processing. For example this will cause
an error: <literal>${a == 2}</literal> and will not print ''true''
or something like that.</para>
<para>However, you can convert booleans to strings with the <link
linkend="ref_builtin_string_for_boolean"><literal>?string</literal>
built-in</link>. For example, to print the value of the "married"
variable (assuming it's a boolean), you could write
<literal>${married?string("yes", "no")}</literal>.</para>
</simplesect>
<simplesect>
<title>The exact conversion rules</title>
<para>For those who are interested, the exact rules of conversion
from the expression value to string (which is then still subject to
escaping) are these, in this order:</para>
<orderedlist>
<listitem>
<para>If the value is a number, then it is converted to string
in the format specified with the
<literal>number_format</literal> setting. So this usually
formats for human audience, as opposed to computer
audience.</para>
</listitem>
<listitem>
<para>Else if the value is whatever kind of date, time or
date-time, then it is converted to string in the format
specified with the <literal>time_format</literal>,
<literal>date_format</literal>, or
<literal>datetime_format</literal> setting, depending on whether
the date information is time-only, date-only, or a date-time. If
it can't be detected what kind of date it is (date vs time vs
date-time), an error will occur.</para>
</listitem>
<listitem>
<para>Else if the value is a string, then there is no
conversion.</para>
</listitem>
<listitem>
<para>Else if the engine is in classic compatibility
mode:</para>
<orderedlist>
<listitem>
<para>If the value is a boolean, true values are converted
to "true", false values are converted to an empty
string.</para>
</listitem>
<listitem>
<para>If the expression is undefined
(<literal>null</literal> or a variable is undefined), it is
converted to an empty string.</para>
</listitem>
<listitem>
<para>Else an error will abort the template
processing.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Else an error will abort the template processing.</para>
</listitem>
</orderedlist>
</simplesect>
</section>
</chapter>
<chapter xml:id="dgui_misc">
<title>Miscellaneous</title>
<remark>Do we need a short chapter on i18n/charset issues in general,
with the introduction of FreeMarker facilities on this field at the
end?</remark>
<section xml:id="dgui_misc_userdefdir">
<title>Defining your own directives</title>
<indexterm>
<primary>macro</primary>
</indexterm>
<indexterm>
<primary>transform</primary>
</indexterm>
<indexterm>
<primary>custom directive</primary>
</indexterm>
<indexterm>
<primary>user-defined directive</primary>
</indexterm>
<indexterm>
<primary>directive</primary>
<secondary>user-defined</secondary>
</indexterm>
<indexterm>
<primary>tag</primary>
<secondary>user-defined</secondary>
</indexterm>
<para>As far as template authors are concerned, user-defined
directives can be defined using the <literal>macro</literal>
directive. <phrase role="forProgrammers">Java programmers who want to
implement directives in Java Language, rather than in a template,
should use
<literal>freemarker.template.TemplateDirectiveModel</literal> (see
<link linkend="pgui_datamodel_directive">more
here...</link>).</phrase></para>
<section>
<title>Basics</title>
<indexterm>
<primary>defining macro</primary>
</indexterm>
<para>A macro is a template fragment associated with a variable. You
can use that variable in your template as a user-defined directive,
so it helps in repetitive tasks. For example, this creates a macro
variable that prints a big ``Hello Joe!'':</para>
<programlisting role="template"><emphasis><#macro greet></emphasis>
<font size="+2">Hello Joe!</font>
<emphasis></#macro></emphasis></programlisting>
<para>The <literal>macro</literal> directive itself does not print
anything; it just creates the macro variable, so there will be a
variable called <literal>greet</literal>. Things between the
<literal><#macro greet></literal> and
<literal></#macro></literal> (called <emphasis
role="term">macro definition body</emphasis>) will be executed only
when you use the variable as directive. You use user-defined
directives by writing <literal>@</literal> instead of
<literal>#</literal> in the FTL tag. Use the variable name as the
directive name. Also, the <link
linkend="gloss.endTag">end-tag</link> for user-defined directives is
mandatory. So you use <literal>greet</literal> like this:</para>
<programlisting role="template"><@greet></@greet></programlisting>
<para>But since
<literal><<replaceable>anything</replaceable>></<replaceable>anything</replaceable>></literal>
is equivalent with
<literal><<replaceable>anything</replaceable>/></literal> you
should use this shorter form (that is familiar for you if you know
<link linkend="gloss.XML">XML</link>):</para>
<programlisting role="template"><@greet/></programlisting>
<para>This will print:</para>
<programlisting role="output"> <font size="+2">Hello Joe!</font>
</programlisting>
<para>But macros can do much more, since the thing between
<literal><#macro <replaceable>...</replaceable>></literal> and
<literal></#macro></literal> is a template fragment, thus it
can contain interpolations
(<literal>${<replaceable>...</replaceable>}</literal>) and FTL tags
(e.g. <literal><#if
<replaceable>...</replaceable>><replaceable>...</replaceable></#if></literal>).</para>
<note>
<para>Programmers will say on
<literal><@<replaceable>...</replaceable>></literal> that
you <emphasis role="term">call</emphasis> the macro.</para>
</note>
</section>
<section>
<title>Parameters</title>
<para>Let's improve the <literal>greet</literal> macro so it can use
arbitrary name, not only ``Joe''. For this purpose you can use
<emphasis role="term">parameters</emphasis>. You define the
parameters after the name of the macro in the
<literal>macro</literal> directive. Here we define one parameter for
the <literal>greet</literal> macro,
<literal>person</literal>:</para>
<programlisting role="template"><#macro greet <emphasis>person</emphasis>>
<font size="+2">Hello <emphasis>${person}</emphasis>!</font>
</#macro></programlisting>
<para>and then you can use this macro as:</para>
<programlisting role="template"><@greet <emphasis>person="Fred"</emphasis>/> and <@greet <emphasis>person="Batman"</emphasis>/>
</programlisting>
<para>which is similar to HTML syntax. This will print:</para>
<programlisting role="output"> <font size="+2">Hello <emphasis>Fred</emphasis>!</font>
and <font size="+2">Hello <emphasis>Batman</emphasis>!</font>
</programlisting>
<para>As you can see, the actual value of the macro parameter is
accessible in the macro definition body as a variable
(<literal>person</literal>). As with <link
linkend="gloss.predefinedDirective">predefined directives</link>,
the value of a parameter (the right side of <literal>=</literal>) is
an <link linkend="dgui_template_exp">FTL expression</link>. Thus,
unlike with HTML, the quotation marks around
<literal>"Fred"</literal> and <literal>"Batman"</literal> are not
optional. <literal><@greet person=Fred/></literal> would mean
that you use the value of variable <literal>Fred</literal> for the
<literal>person</literal> parameter, rather than the string
<literal>"Fred"</literal>. Of course parameter value need not be a
string, it can be number, boolean, hash, sequence, ...etc., also you
can use complex expression on the left side of <literal>=</literal>
(e.g. <literal>someParam=(price + 50)*1.25</literal>).</para>
<para>User-defined directives can have multiple parameters. For
example, add a new parameter <literal>color</literal>:</para>
<programlisting role="template"><#macro greet person <emphasis>color</emphasis>>
<font size="+2" color="${color}">Hello ${person}!</font>
</#macro></programlisting>
<para>and then you can use this macro like:</para>
<programlisting role="template"><@greet person="Fred" color="black"/></programlisting>
<para>The order of parameters is not important, so this is
equivalent with the previous:</para>
<programlisting role="template"><@greet color="black" person="Fred"/></programlisting>
<para>When you call the macro, you can use only parameters that you
have defined in the <literal>macro</literal> directive (in this
case: <literal>person</literal> and <literal>color</literal>). So if
you try <literal><@greet person="Fred" color="black"
background="green"/></literal> then you will get an error, since
you haven't mentioned parameter <literal>background</literal> in the
<literal><#macro
<replaceable>...</replaceable>></literal>.</para>
<para>Also, you must give value for all parameters that you have
defined for the macro. So if you try <literal><@greet
person="Fred"/></literal> then you will get an error, since you
forgot to specify the value of <literal>color</literal>. However, it
often happens that you would specify the same value for a parameter
in most cases, so you want to specify the value only when you want a
different value for it than the usual. This can be achieved if you
specify the parameter in the <literal>macro</literal> directive as
<literal><replaceable>param_name</replaceable>=<replaceable>usual_value</replaceable></literal>.
For example, you want to use <literal>"black"</literal> for
<literal>color</literal> if you don't specify value for that
parameter when you use the <literal>greet</literal>
directive:</para>
<programlisting role="template"><#macro greet person color<emphasis>="black"</emphasis>>
<font size="+2" color="${color}">Hello ${person}!</font>
</#macro></programlisting>
<para>Now <literal><@greet person="Fred"/></literal> is OK,
since it is equivalent with <literal><@greet person="Fred"
color="black"/></literal>, thus the value of
<literal>color</literal> parameter is known. If you want
<literal>"red"</literal> for <literal>color</literal>, then you
write <literal><@greet person="Fred" color="red"/></literal>,
and this value will override the usual value specified with the
<literal>macro</literal> directive, so the value of
<literal>color</literal> parameter will be
<literal>"red"</literal>.</para>
<para>Also, it is important to realize that -- according to the
already explained <link linkend="dgui_template_exp">FTL expression
rules</link> -- <literal>someParam=foo</literal> and
<literal>someParam="${foo}"</literal> are very different. In the
fist case, you use the value of variable <literal>foo</literal> as
the value of the parameter. In the second case, you use a <link
linkend="dgui_template_exp_stringop_interpolation">string literal
with interpolation</link>, so the value of the parameter will be a
string -- in this case, the value of <literal>foo</literal> rendered
to text -- regardless of the type (as number, date, etc.) of
<literal>foo</literal>. Or, another example:
<literal>someParam=3/4</literal> and
<literal>someParam="${3/4}"</literal> are different. If the
directive wants a numerical value for <literal>someParam</literal>,
it will not like the second variation. Do not exchange these.</para>
<para>A very important aspect of macro parameters is that they are
local variables. For more information about local variables please
read: <xref linkend="dgui_misc_var" /></para>
</section>
<section>
<title>Nested content</title>
<para>Custom directive can have nested content, similarly as
predefined directives like <literal><#if
<replaceable>...</replaceable>><replaceable>nested
content</replaceable></#if></literal> can have. For example,
this creates a macro that draws borders around its nested
content:</para>
<programlisting role="template"><#macro border>
<table border=4 cellspacing=0 cellpadding=4><tr><td>
<emphasis><#nested></emphasis>
</tr></td></table>
</#macro></programlisting>
<para>The <literal><#nested></literal> directive executes the
template fragment between the start-tag and end-tags of the
directive. So if you do this:</para>
<programlisting role="template"><@border>The bordered text</@border></programlisting>
<para>the output will be:</para>
<programlisting role="output"> <table border=4 cellspacing=0 cellpadding=4><tr><td>
The bordered text
</td></tr></table>
</programlisting>
<para>The <literal>nested</literal> directive can be called for
multiple times, for example:</para>
<programlisting role="template"><#macro do_thrice><emphasis>
<#nested>
<#nested>
<#nested></emphasis>
</#macro>
<@do_thrice>
Anything.
</@do_thrice></programlisting>
<para>will print:</para>
<programlisting role="output"> Anything.
Anything.
Anything.</programlisting>
<para>If you don't use the <literal>nested</literal> directive, then
the nested content will not be executed. Thus, if you accidentally
use the <literal>greet</literal> directive like this:</para>
<programlisting role="template"><@greet person="Joe">
Anything.
</@greet></programlisting>
<para>then FreeMarker will not see this as an error, and simply
prints:</para>
<programlisting role="output"><font size="+2">Hello Joe!</font></programlisting>
<para>and the nested content will be ignored, since the
<literal>greet</literal> macro never uses <literal>nested</literal>
directive.</para>
<para>The nested content can be anything that is valid FTL,
including other user-defined directives. Thus this is OK:</para>
<programlisting role="template"><@border>
<ul>
<@do_thrice>
<li><@greet person="Joe"/>
</@do_thrice>
</ul>
</@border></programlisting>
<para>and will print:</para>
<programlisting role="output"> <table border=4 cellspacing=0 cellpadding=4><tr><td>
<ul>
<li><font size="+2">Hello Joe!</font>
<li><font size="+2">Hello Joe!</font>
<li><font size="+2">Hello Joe!</font>
</ul>
</tr></td></table></programlisting>
<para>The <link linkend="dgui_misc_var">local variables</link> of a
macro are not visible in the nested content. Say, this:</para>
<programlisting role="template"><#macro repeat count>
<#local y = "test">
<#list 1..count as x>
${y} ${count}/${x}: <#nested>
</#list>
</#macro>
<@repeat count=3>${y!"?"} ${x!"?"} ${count!"?"}</@repeat></programlisting>
<para>will print this:</para>
<programlisting role="output"> test 3/1: ? ? ?
test 3/2: ? ? ?
test 3/3: ? ? ?</programlisting>
<para>because the <literal>y</literal>, <literal>x</literal> and
<literal>count</literal> are the local (private) variables of the
macro, and are not visible from outside the macro definition.
Furthermore, a different set of local variables is used for each
macro call, so this will not cause confusion:</para>
<programlisting role="template"><#macro test foo>${foo} (<#nested>) ${foo}</#macro>
<@test foo="A"><@test foo="B"><@test foo="C"/></@test></@test>
</programlisting>
<para>and will print this:</para>
<programlisting role="output">A (B (C () C) B) A</programlisting>
</section>
<section xml:id="dgui_misc_userdefdir_loopvar">
<title>Macros with loop variables</title>
<indexterm>
<primary>loop variable</primary>
</indexterm>
<para>Predefined directives like <literal>list</literal> can use
so-called loop variables; you should read <xref
linkend="dgui_misc_var" /> to understand loop variables.</para>
<para>User-defined directives can also have loop variables. For
example, let's extend the <literal>do_thrice</literal> directive of
the earlier examples so it exposes the current repetition number as
a loop variable. As with the predefined directives (as
<literal>list</literal>) the <emphasis>name</emphasis> of loop
variables is given when you call the directive (as
<literal>foo</literal> in <literal><#list foos as
foo><replaceable>...</replaceable></#list></literal>),
while the <emphasis>value</emphasis> of the variables is set by the
directive itself.</para>
<programlisting role="template"><#macro do_thrice>
<#nested <emphasis>1</emphasis>>
<#nested <emphasis>2</emphasis>>
<#nested <emphasis>3</emphasis>>
</#macro>
<@do_thrice <emphasis>; x</emphasis>> <#-- user-defined directive uses ";" instead of "as" -->
${<emphasis>x</emphasis>} Anything.
</@do_thrice></programlisting>
<para>This will print:</para>
<programlisting role="output"> 1 Anything.
2 Anything.
3 Anything.
</programlisting>
<para>The syntactical rule is that you pass the actual value of the
loop variable for a certain "loop" (i.e. repetition of the nested
content) as the parameter of <literal>nested</literal> directive (of
course the parameter can by arbitrary expression). The name of the
loop variable is specified in the user-defined directive open tag
(<literal><@...></literal>) after the parameters and a
semicolon.</para>
<para>A macro can use more the one loop variable (the order of
variables is significant):</para>
<programlisting role="template"><#macro repeat count>
<#list 1..count as x>
<#nested <emphasis>x, x/2, x==count</emphasis>>
</#list>
</#macro>
<@repeat count=4 ; <emphasis>c, halfc, last</emphasis>>
${<emphasis>c</emphasis>}. ${<emphasis>halfc</emphasis>}<#if <emphasis>last</emphasis>> Last!</#if>
</@repeat></programlisting>
<para>The output will be:</para>
<programlisting role="output"> 1. 0.5
2. 1
3. 1.5
4. 2 Last!
</programlisting>
<para>It is not a problem if you specify different number of loop
variables in the user-defined directive start-tag (that is, after
the semicolon) than with the <literal>nested</literal> directive. If
you specify less loop variables after the semicolon, then simply you
will not see the last few values that the <literal>nested</literal>
directive provides, since there is no loop variable to hold those
values. So these are all OK:</para>
<programlisting role="template"><@repeat count=4 ; <emphasis>c, halfc, last</emphasis>>
${c}. ${halfc}<#if last> Last!</#if>
</@repeat>
<@repeat count=4 ; <emphasis>c, halfc</emphasis>>
${c}. ${halfc}
</@repeat>
<@repeat count=4>
Just repeat it...
</@repeat></programlisting>
<para>If you specify more variables after the semicolon than with
the <literal>nested</literal> directive, then the last few loop
variables will not be created (i.e. will be undefined in the nested
content).</para>
</section>
<section>
<title>More about user-defined directives and macros</title>
<para>Now you may read the relevant parts of the FreeMarker
Reference:</para>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="ref.directive.userDefined">user-defined
directive call</link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.macro"><literal>macro</literal>
directive</link></para>
</listitem>
</itemizedlist>
<para>You can define methods in FTL as well, see <link
linkend="ref.directive.function">the <literal>function</literal>
directive</link>.</para>
<para>Also, you may interested in namespaces: <xref
linkend="dgui_misc_namespace" />. Namespaces help you to organize
and reuse your commonly used macros.</para>
</section>
</section>
<section xml:id="dgui_misc_var">
<title>Defining variables in the template</title>
<indexterm>
<primary>variable</primary>
</indexterm>
<indexterm>
<primary>loop variable</primary>
</indexterm>
<indexterm>
<primary>local variable</primary>
</indexterm>
<indexterm>
<primary>temporary variable</primary>
</indexterm>
<para>As we have described, a template can use the variables defined
in the data-model. A template can also define variables outside the
data-model for its own use. These temporary variables can be created
and replaced using FTL directives. Note that each <link
linkend="gloss.templateProcessingJob">template processing job</link>
has its own private set of these variables that exists while the given
page is being rendered. This variable set is initially empty, and will
be thrown away when the template processing job has been
finished.</para>
<para>You access a variable that you have defined in the template
exactly as if it were a variable in the data-model root. The variable
has precedence over any variable of the same name defined in the
data-model. That is, if you define a variable called ``foo'' and
coincidentally, there is a ``foo'' in the data-model as well, then the
variable created in the template will hide (not overwrite!) the
variable in the data-model root. For example,
<literal>${foo}</literal> will print the value of the variable created
in the template.</para>
<para>There are 3 kind of variables that are defined in a
template:</para>
<itemizedlist>
<listitem>
<para><emphasis role="term">``plain'' variables</emphasis>: They
are accessible from everywhere in the template, or from the
templates inserted with <literal>include</literal> directive. You
can create and replace these variables with the <link
linkend="ref.directive.assign"><literal>assign</literal></link> or
<link linkend="ref.directive.macro"><literal>macro</literal>
directives</link>.</para>
</listitem>
<listitem>
<para><emphasis role="term">Local variables</emphasis>: They can
only be set inside a <link
linkend="gloss.macroDefinitionBody">macro definition body</link>,
and are only visible from there. A local variable only exists for
the duration of a macro call. You can create and replace local
variables inside macro definition bodies with the <link
linkend="ref.directive.local"><literal>local</literal>
directive</link>.</para>
</listitem>
<listitem>
<para><emphasis role="term">Loop variables</emphasis>: Loop
variables are created automatically by directives like <link
linkend="ref.directive.list"><literal>list</literal></link>, and
they only exist between the start-tag and end-tag of the
directive. <link linkend="ref.directive.macro">Macro</link>
parameters are local variables, not loop variables.</para>
</listitem>
</itemizedlist>
<para>Example: Create and replace variables with
<literal>assign</literal>:</para>
<programlisting role="template"><#assign x = 1> <#-- create variable x -->
${x}
<#assign x = x + 3> <#-- replace variable x -->
${x}</programlisting>
<para>Output:</para>
<programlisting role="output">1
4</programlisting>
<para>Local variables hide (not overwrite) ``plain'' variables of the
same name. Loop variables hide (not overwrite) local and ``plain''
variables of the same name. For example:</para>
<programlisting role="template"><#assign x = "plain">
1. ${x} <#-- we see the plain var. here -->
<@test/>
6. ${x} <#-- the value of plain var. was not changed -->
<#list ["loop"] as x>
7. ${x} <#-- now the loop var. hides the plain var. -->
<#assign x = "plain2"> <#-- replace the plain var, hiding does not mater here -->
8. ${x} <#-- it still hides the plain var. -->
</#list>
9. ${x} <#-- the new value of plain var. -->
<#macro test>
2. ${x} <#-- we still see the plain var. here -->
<#local x = "local">
3. ${x} <#-- now the local var. hides it -->
<#list ["loop"] as x>
4. ${x} <#-- now the loop var. hides the local var. -->
</#list>
5. ${x} <#-- now we see the local var. again -->
</#macro></programlisting>
<para>the output:</para>
<programlisting role="output">1. plain
2. plain
3. local
4. loop
5. local
6. plain
7. loop
8. loop
9. plain2
</programlisting>
<para>An inner loop variable can hide an outer loop variable:</para>
<programlisting role="template"><#list ["loop 1"] as x>
${x}
<#list ["loop 2"] as x>
${x}
<#list ["loop 3"] as x>
${x}
</#list>
${x}
</#list>
${x}
</#list></programlisting>
<para>the output:</para>
<programlisting role="output"> loop 1
loop 2
loop 3
loop 2
loop 1</programlisting>
<para>Note that the value of a loop variable is set by the directive
invocation that has created it (the <literal><list
<replaceable>...</replaceable>></literal> tags in this case). There
is no other way to change the value of a loop variable (say, you can't
change its value with some kind of assignment directive). You can hide
temporarily a loop variable with another loop variable though, as you
have seen above.</para>
<para>Sometimes it happens that a variable hides the variable in the
data-model with the same name, but you want to read the variable of
the data-model. In this case you can use the <link
linkend="dgui_template_exp_var_special">special variable</link>
<literal>globals</literal>. For example, assume we have a variable
called <literal>user</literal> in the data-model with value ``Big
Joe'':</para>
<programlisting role="template"><#assign user = "Joe Hider">
${user} <#-- prints: Joe Hider -->
${.globals.user} <#-- prints: Big Joe --></programlisting>
<para>For information about syntax of variables please read: <xref
linkend="dgui_template_exp" /></para>
</section>
<section xml:id="dgui_misc_namespace">
<title>Namespaces</title>
<indexterm>
<primary>namespaces</primary>
</indexterm>
<indexterm>
<primary>libraries</primary>
</indexterm>
<para>When you run FTL templates, you have a (possibly empty) set of
variables that you have created with <literal>assign</literal> and
<literal>macro</literal> directives, as can be seen from the <link
linkend="dgui_misc_var">previous chapter</link>. A set of variables
like this is called a <emphasis role="term">namespace</emphasis>. In
simple cases you use only one namespace, the so-called <emphasis
role="term">main namespace</emphasis>. You don't realize this, since
normally you use only this namespace.</para>
<para>But if you want to build reusable collection of macros,
functions and other variables -- usually referred as <emphasis
role="term">library</emphasis> by lingo -- the usage of multiple
namespaces becomes inevitable. Just consider if you have a big
collection of macros, that you use in several projects, or even you
want to share it with other people. It becomes impossible to be sure
that the library does not have a macro (or other variable) with the
same name as the name of a variable in the data-model, or with the
same name as a the name of a variable in another library used in the
template. In general, variables can clobber each other because of the
name clashes. So you should use a separate namespace for the variables
of each library.</para>
<section>
<title>Creating a library</title>
<para>Let's create a simple library. Assume you commonly need the
variables <literal>copyright</literal> and <literal>mail</literal>
(before you ask, macros <emphasis>are</emphasis> variables):</para>
<programlisting role="template"><#macro copyright date>
<p>Copyright (C) ${date} Julia Smith. All rights reserved.</p>
</#macro>
<#assign mail = "[email protected]"></programlisting>
<para>Store the above in the file <literal>lib/my_test.ftl</literal>
(in the directory where you store the templates). Assume you want to
use this in <literal>aWebPage.ftl</literal>. If you use
<literal><#include "/lib/my_test.ftl"></literal> in the
<literal>aWebPage.ftl</literal>, then it will create the two
variables in the main namespace, and it is not good now, since you
want them to be in a namespace that is used exclusively by the ``My
Test Library''. Instead of <literal>include</literal> you have to
use <link linkend="ref.directive.import"><literal>import</literal>
directive</link>. This directive is, at the first glance, similar to
<literal>include</literal>, but it will create an empty namespace
for <literal>lib/my_test.ftl</literal> and will execute that there.
<literal>lib/my_test.ftl</literal> will find itself in an clean new
world, where only the variables of data-model are present (since
they are visible from everywhere), and will create the two variables
in this new world. That's fine for now, but you want to access the
two variables from <literal>aWebPage.ftl</literal>, and that uses
the main namespace, so it can't see the variables of the other
namespace. The solution is that the <literal>import</literal>
directive not only creates the new namespace, but a new hash
variable in the namespace used by the caller of
<literal>import</literal> (the main namespace in this case), that
will act as a gate into the newly created namespace. So this is how
<literal>aWebPage.ftl</literal> will look like:</para>
<programlisting role="template"><#import "/lib/my_test.ftl" as <emphasis>my</emphasis>> <#-- the hash called "my" will be the "gate" -->
<@<emphasis>my</emphasis>.copyright date="1999-2002"/>
${<emphasis>my</emphasis>.mail}</programlisting>
<para>Note how it accesses the variables in the namespace created
for <literal>/lib/my_test.ftl</literal> using the newly created
namespace accessing hash, <literal>my</literal>. This will
print:</para>
<programlisting role="output"> <p>Copyright (C) 1999-2002 Julia Smith. All rights reserved.</p>
[email protected]</programlisting>
<para>If you would have a variable called <literal>mail</literal> or
<literal>copyright</literal> in the main namespace, that would not
cause any confusion, since the two templates use separated
namespaces. For example, modify the <literal>copyright</literal>
macro in <literal>lib/my_test.ftl</literal> to this:</para>
<programlisting role="template"><#macro copyright date>
<p>Copyright (C) ${date} Julia Smith. All rights reserved.
<br>Email: <emphasis>${mail}</emphasis></p>
</#macro></programlisting>
<para>and then replace <literal>aWebPage.ftl</literal> with
this:</para>
<programlisting role="template"><#import "/lib/my_test.ftl" as my>
<emphasis><#assign mail="[email protected]"></emphasis>
<@my.copyright date="1999-2002"/>
${my.mail}
${mail}</programlisting>
<para>and the output will be this:</para>
<programlisting role="output"> <p>Copyright (C) 1999-2002 Julia Smith. All rights reserved.
<br>Email: <emphasis>[email protected]</emphasis></p>
[email protected]
[email protected]</programlisting>
<para>This is like that because when you have called the
<literal>copyright</literal> macro, FreeMarker has temporarily
switch to the namespace that was created by the
<literal>import</literal> directive for
<literal>/lib/my_test.ftl</literal>. Thus, the
<literal>copyright</literal> macro always sees the
<literal>mail</literal> variable that exists there, and not the
other <literal>mail</literal> that exists in the main
namespace.</para>
</section>
<section>
<title>Writing the variables of imported namespaces</title>
<para>Occasionally you may want to create or replace a variable in
an imported namespace. You can do this with the
<literal>assign</literal> directive, if you use its
<literal>namespace</literal> parameter. For example, this:</para>
<programlisting role="template"><#import "/lib/my_test.ftl" as my>
${my.mail}
<#assign mail="[email protected]" <emphasis>in my</emphasis>>
${my.mail}</programlisting>
<para>will output this:</para>
<programlisting role="output">[email protected]
[email protected]</programlisting>
</section>
<section>
<title>Namespaces and data-model</title>
<para>The variables of the data-model are visible from everywhere.
For example, if you have a variable called <literal>user</literal>
in the data-model, <literal>lib/my_test.ftl</literal> will access
that, exactly as <literal>aWebPage.ftl</literal> does:</para>
<programlisting role="template"><#macro copyright date>
<p>Copyright (C) ${date} <emphasis>${user}</emphasis>. All rights reserved.</p>
</#macro>
<#assign mail = "<emphasis>${user}</emphasis>@acme.com"></programlisting>
<para>If <literal>user</literal> is ``Fred'', then the usual
example:</para>
<programlisting role="template"><#import "/lib/my_test.ftl" as my>
<@my.copyright date="1999-2002"/>
${my.mail}</programlisting>
<para>will print this:</para>
<programlisting role="output"> <p>Copyright (C) 1999-2002 Fred. All rights reserved.</p>
[email protected]</programlisting>
<para>Don't forget that the variables in the namespace (the
variables you create with <literal>assign</literal> or
<literal>macro</literal> directives) have precedence over the
variables of the data-model when you are in that namespace. Thus,
the contents of data-model does not interfere with the variables
created by the library.</para>
<note>
<para>In some unusual applications you want to create variables in
the template those are visible from all namespaces, exactly like
the variables of the data-model. But you can't change the
data-model with templates. Still, it is possible to achieve
similar result with the <literal>global</literal> directive; read
the <link linkend="ref.directive.global">reference</link> for more
details.</para>
</note>
</section>
<section>
<title>The life-cycle of namespaces</title>
<para>A namespace is identified by the path that was used with the
<literal>import</literal> directive. If you try to
<literal>import</literal> with the same path for multiple times, it
will create the namespace and run the template specified by the path
for the very first invocation of <literal>import</literal> only. The
later <literal>import</literal>s with the same path will just create
a ``gate'' hash to the same namespace. For example, let this be the
<literal>aWebPage.ftl</literal>:</para>
<programlisting role="template"><#import "/lib/my_test.ftl" as my>
<#import "/lib/my_test.ftl" as foo>
<#import "/lib/my_test.ftl" as bar>
${my.mail}, ${foo.mail}, ${bar.mail}
<#assign mail="[email protected]" in my>
${my.mail}, ${foo.mail}, ${bar.mail}</programlisting>
<para>The output will be:</para>
<programlisting role="output">[email protected], [email protected], [email protected]
[email protected], [email protected], [email protected]</programlisting>
<para>since you see the same namespace through
<literal>my</literal>, <literal>foo</literal> and
<literal>bar</literal>.</para>
<para>Note that namespaces are not hierarchical, they exist
independently of each other. That is, if you
<literal>import</literal> namespace N2 while you are in name space
N1, N2 will not be inside N1. N1 just gets a hash by which it can
access N2. This is the same N2 namespace that you would access if,
say, you <literal>import</literal> N2 when you are in the main
namespace.</para>
<para>Each <link linkend="gloss.templateProcessingJob">template
processing job</link> has its own private set of namespaces. Each
template-processing job is a separated cosmos that exists only for
the short period of time while the given page is being rendered, and
then it vanishes with all its populated namespaces. Thus, whenever
we say that ``<literal>import</literal> is called for the first
time'' and such, we are always talking in the context of a single
template processing job.</para>
</section>
<section>
<title>Writing libraries for other people</title>
<indexterm>
<primary>library path</primary>
</indexterm>
<para>If you have written a good quality library that can be useful
for other people, you may want to make it available on the Internet
(like on <link
xlink:href="http://freemarker.org/libraries.html">http://freemarker.org/libraries.html</link>).
To prevent clashes with the names of libraries used by other
authors, and to make it easy to write libraries that import other
published libraries, there is a de-facto standard that specifies the
format of library paths. The standard is that the library must be
available (importable) for templates and other libraries with a path
like this:</para>
<para><literal>/lib/<replaceable>yourcompany.com</replaceable>/<replaceable>your_library</replaceable>.ftl</literal></para>
<para>For example if you work for Example Inc. that owns the
www.example.com homepage, and you develop a widget library, then the
path of the FTL file to import should be:</para>
<para><literal>/lib/example.com/widget.ftl</literal></para>
<para>Note that the www is omitted. The part after the 3rd slash can
contain subdirectories such as:</para>
<para><literal>/lib/example.com/commons/string.ftl</literal></para>
<para>An important rule is that the path should not contain
upper-case letters. To separate words, use <literal>_</literal>, as
in <literal>wml_form</literal> (not
<literal>wmlForm</literal>).</para>
<para>Note that if you do not develop the library for a company or
organization, you should use the URL of the project homepage, such
as <literal>/lib/example.sourceforge.net/example.ftl</literal>, or
<literal>/lib/geocities.com/jsmith/example.ftl</literal>.</para>
</section>
</section>
<section xml:id="dgui_misc_whitespace">
<title>White-space handling</title>
<indexterm>
<primary>white-space removal</primary>
</indexterm>
<para>The control of the <link
linkend="gloss.whiteSpace">white-space</link> in a template is a
problem that to some extent haunts every template engine in the
business.</para>
<para>Let see this template. I have marked the components of template
with colors: <phrase role="markedText">text</phrase>, <phrase
role="markedInterpolation">interpolation</phrase>, <phrase
role="markedFTLTag">FTL tag</phrase>. With the <phrase
role="markedInvisibleText">[BR]</phrase>-s I visualize the <link
linkend="gloss.lineBreak">line breaks</link>.</para>
<programlisting role="template"><phrase role="markedText"><p>List of users:<phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#assign users = [{"name":"Joe", "hidden":false},<phrase
role="markedInvisibleText">[BR]</phrase>
{"name":"James Bond", "hidden":true},<phrase
role="markedInvisibleText">[BR]</phrase>
{"name":"Julia", "hidden":false}]></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<ul><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#list users as user></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#if !user.hidden></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<li><phrase role="markedInterpolation">${user.name}</phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"></#if></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"></#list></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
</ul><phrase role="markedInvisibleText">[BR]</phrase>
<p>That's all.</phrase></programlisting>
<para>If FreeMarker were to output all <phrase
role="markedText">text</phrase> as is, the output would be:</para>
<programlisting role="output"><phrase role="markedText"><p>List of users:<phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<ul><phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<li></phrase>Joe<phrase role="markedText"><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<li></phrase>Julia<phrase role="markedText"><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
<phrase role="markedInvisibleText">[BR]</phrase>
</ul><phrase role="markedInvisibleText">[BR]</phrase>
<p>That's all.</phrase></programlisting>
<para>You have a lot of unwanted spaces and line breaks here.
Fortunately neither HTML nor XML is typically white-space sensitive,
but this amount of superfluous white-space can be annoying, and
needlessly increases the size of produced HTML. Of course, it is even
bigger problem when outputting white-space-sensitive formats.</para>
<para>FreeMarker provides the following tools to cope with this
problem:</para>
<itemizedlist>
<listitem>
<para>Tools to ignore certain white-space of the template files
<phrase role="forProgrammers">(parse time white-space
removal)</phrase>:</para>
<itemizedlist>
<listitem>
<para>White-space stripping: This feature automatically
ignores typical superfluous white-space around FTL tags. It
can be enabled or disabled on per template manner.</para>
</listitem>
<listitem>
<para>Trimmer directives: <literal>t</literal>,
<literal>rt</literal>, <literal>lt</literal>. With these
directives you can explicitly tell FreeMarker to ignore
certain white-space. Read <link linkend="ref.directive.t">the
reference</link> for more information.</para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.ftl"><literal>ftl</literal></link>
parameter <literal>strip_text</literal>: This removes all
top-level text from the template. It is useful for templates
that contain macro definitions only (and some other
non-outputting directives), because it removes the line-breaks
that you use between the macro definitions and between the
other top-level directives to improve the readability of the
template.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Tools that remove white-space from the output <phrase
role="forProgrammers">(on-the-fly white-space
removal)</phrase>:</para>
<itemizedlist>
<listitem>
<para><literal>compress</literal> directive.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<section xml:id="dgui_misc_whitespace_stripping">
<title>White-space stripping</title>
<indexterm>
<primary>white-space removal</primary>
<secondary>stripping</secondary>
</indexterm>
<para>If this feature is enabled for a template, then it
automatically ignores (i.e. does not print to the output) two kind
of typical superfluous white-space:</para>
<itemizedlist>
<listitem>
<para>Indentation white-space, and trailing white-space at the
end of the line (includes the line break) will be ignored in
lines that contains only FTL tags (e.g.
<literal><@myMacro/></literal>, <literal><#if
<replaceable>...</replaceable>></literal>) and/or FTL
comments (e.g. <literal><#-- blah --></literal>), apart
from the the ignored white-space itself. For example, if a line
contains only an <literal><#if
<replaceable>...</replaceable>></literal>, then the
indentation before the tag and the line break after the tag will
be ignored. However, if the line contains <literal><#if
<replaceable>...</replaceable>>x</literal>, then the
white-space in that line will not be ignored, because of the
<literal>x</literal>, as that is not FTL tag. Note that
according these rules, a line that contains <literal><#if
<replaceable>...</replaceable>><#list
<replaceable>...</replaceable>></literal> is subject to
white-space ignoring, while a line that contains
<literal><#if <replaceable>...</replaceable>> <#list
<replaceable>...</replaceable>></literal> is not, because the
white-space between the two FTL tags is embedded white-space,
not indentation or trailing white-space.</para>
</listitem>
<listitem>
<para>White-space sandwiched between the following directives is
ignored: <literal>macro</literal>, <literal>function</literal>,
<literal>assign</literal>, <literal>global</literal>,
<literal>local</literal>, <literal>ftl</literal>,
<literal>import</literal>, but only if there is
<emphasis>only</emphasis> white-space and/or FTL comments
between the directives. In practice it means that you can put
empty lines between macro definitions and assignments as spacing
for better readability, without printing needless empty lines
(line breaks) to the output.</para>
</listitem>
</itemizedlist>
<para>The output of the last example with white-space stripping
enabled will be:</para>
<programlisting role="output"><phrase role="markedText"><p>List of users:<phrase
role="markedInvisibleText">[BR]</phrase>
<ul><phrase role="markedInvisibleText">[BR]</phrase>
<li></phrase>Joe<phrase role="markedText"><phrase
role="markedInvisibleText">[BR]</phrase>
<li></phrase>Julia<phrase role="markedText"><phrase
role="markedInvisibleText">[BR]</phrase>
</ul><phrase role="markedInvisibleText">[BR]</phrase>
<p>That's all.</phrase></programlisting>
<para>This is because after stripping the template becomes the
following; the ignored text is not <phrase
role="markedText">colored</phrase>:</para>
<programlisting role="template"><phrase role="markedText"><p>List of users:<phrase
role="markedInvisibleText">[BR]</phrase></phrase>
<phrase role="markedFTLTag"><#assign users = [{"name":"Joe", "hidden":false},<phrase
role="markedInvisibleText">[BR]</phrase>
{"name":"James Bond", "hidden":true},<phrase
role="markedInvisibleText">[BR]</phrase>
{"name":"Julia", "hidden":false}]></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedText"><ul><phrase role="markedInvisibleText">[BR]</phrase></phrase>
<phrase role="markedFTLTag"><#list users as user></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"><#if !user.hidden></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedText"> <li><phrase role="markedInterpolation">${user.name}</phrase><phrase
role="markedInvisibleText">[BR]</phrase></phrase>
<phrase role="markedFTLTag"></#if></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedFTLTag"></#list></phrase><phrase
role="markedInvisibleText">[BR]</phrase>
<phrase role="markedText"></ul><phrase role="markedInvisibleText">[BR]</phrase>
<p>That's all.</phrase></programlisting>
<para>White-space stripping can be enabled/disabled in per template
manner with the <link
linkend="ref.directive.ftl"><literal>ftl</literal> directive</link>.
If you don't specify this with the <literal>ftl</literal> directive,
then white-space stripping will be enabled or disabled depending on
how the programmer has configured FreeMarker. The factory default is
white-space stripping enabled, and the programmers probably left it
so (<phrase role="forProgrammers">recommended</phrase>). <phrase
role="forProgrammers">Note that enabling white-space stripping does
<emphasis>not</emphasis> degrade the performance of template
execution; white-space stripping is done during template
loading.</phrase></para>
<para>White-space stripping can be disabled for a single line with
the <link linkend="ref.directive.nt"><literal>nt</literal></link>
directive (for No Trim).</para>
</section>
<section>
<title>Using compress directive</title>
<indexterm>
<primary>white-space removal</primary>
<secondary>compress</secondary>
</indexterm>
<para>Another solution is to use the <link
linkend="ref.directive.compress"><literal>compress</literal>
directive</link>. As opposed to white-space stripping, this works
directly on the generated output, not on the template. That is, it
will investigate the printed output on the fly, and does not
investigate the FTL program that creates the output. It aggressively
removes indentations, empty lines and repeated spaces/tabs (for more
information read the <link
linkend="ref.directive.compress">reference</link>). So the output
of:</para>
<programlisting role="template"><emphasis><#compress></emphasis>
<#assign users = [{"name":"Joe", "hidden":false},
{"name":"James Bond", "hidden":true},
{"name":"Julia", "hidden":false}]>
List of users:
<#list users as user>
<#if !user.hidden>
- ${user.name}
</#if>
</#list>
That's all.
<emphasis></#compress></emphasis></programlisting>
<para>will be:</para>
<programlisting role="output">List of users:
- Joe
- Julia
That's all.</programlisting>
<para>Note that <literal>compress</literal> is totally independent
of white-space stripping. So it is possible that the white-space of
template is stripped, and later the produced output is
<literal>compress</literal>-ed.</para>
<para>Also, by default a user-defined directve called
<literal>compress</literal> is available in the data-model (due to
backward compatibility). This is the same as the directive, except
that you may optionally set the <literal>single_line</literal>
parameter, which will remove all intervening line breaks. If you
replace
<literal><#compress><replaceable>...</replaceable></#compress></literal>
on the last example with <literal><@compress
single_line=true><replaceable>...</replaceable></@compress></literal>,
then you get this output:</para>
<programlisting role="output">List of users: - Joe - Julia That's all.</programlisting>
</section>
</section>
<section xml:id="dgui_misc_alternativesyntax">
<title>Alternative (square bracket) syntax</title>
<indexterm>
<primary>alternative syntax</primary>
</indexterm>
<indexterm>
<primary>square bracket syntax</primary>
</indexterm>
<note>
<para>This feature exists since FreeMarker 2.3.4.</para>
</note>
<para>FreeMarker supports an alternative syntax, where
<literal>[</literal> and <literal>]</literal> is used instead of
<literal><</literal> and <literal>></literal> in FreeMarker
directives and comments, for example:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Calling predefined directive: <literal>[#list animals as
being]<replaceable>...</replaceable>[/#list]</literal></para>
</listitem>
<listitem>
<para>Calling user-defined directive: <literal>[@myMacro
/]</literal></para>
</listitem>
<listitem>
<para>Comment: <literal>[#-- the comment --]</literal></para>
</listitem>
</itemizedlist>
<para>To use the alternative syntax instead of the default one, start
the template with the <link
linkend="ref_directive_ftl"><literal>ftl</literal> directive</link>
using the alternative syntax. If you don't know what is the
<literal>ftl</literal> directive, just start the template with
<literal>[#ftl]</literal>, and remember that it should be the very
first thing in the file (except that <link
linkend="gloss.whiteSpace">white-space</link> can precede it). For
example, this is how the last example of the <link
linkend="dgui_quickstart_template">Getting Started</link> looks with
the alternative syntax (assuming it's a complete template, not just a
fragment):</para>
<programlisting role="template"><emphasis>[#ftl]</emphasis>
<p>We have these animals:
<table border=1>
<tr><th>Name<th>Price
<emphasis>[#list animals as being]</emphasis>
<tr>
<td>
<emphasis>[#if being.size = "large"]</emphasis><b><emphasis>[/#if]</emphasis>
${being.name}
<emphasis>[#if being.size = "large"]</emphasis></b><emphasis>[/#if]</emphasis>
<td>${being.price} Euros
<emphasis>[/#list]</emphasis>
</table></programlisting>
<para>The alternative (square bracket) and the default (angle bracket)
syntax are mutually exclusive within a template. That is, either the
whole template uses alternative syntax, or the whole template uses the
default syntax. If the template uses alternative syntax, things like
<literal><#if <replaceable>...</replaceable>></literal> are
count as static text, not as FTL tags. Similarly, if the template uses
the default syntax, things like <literal>[#if
<replaceable>...</replaceable>]</literal> count as static text, not as
FTL tags.</para>
<para>If you start the file with <literal>[#ftl
<replaceable>...</replaceable>]</literal> (where the
<literal><replaceable>...</replaceable></literal> stands for the
optional parameters; of course <literal>[#ftl]</literal> works too)
the file will surely use the alternative (square bracket) syntax. If
you start the file with <literal><#ftl
<replaceable>...</replaceable>></literal> the file will surely use
the normal (angle bracket) syntax. If there is no
<literal>ftl</literal> directive in the file, then the programmer
decides what the syntax will be by configuring FreeMarker <phrase
role="forProgrammers">(programmers see
<literal>Configuration.setTagSyntax(int)</literal> in the API
javadocs)</phrase>. Most probably the programmers use the factory
default however. The factory default in 2.3.x is using the normal
syntax. The factory default in 2.4.x will be auto-detection, which
means that the first FreeMarker tag determines the syntax (it can be
anything, not just <literal>ftl</literal>).</para>
</section>
</chapter>
</part>
<part xml:id="pgui">
<title>Programmer's Guide</title>
<chapter xml:id="pgui_quickstart">
<title>Getting Started</title>
<para>Note that, if you are new to FreeMarker, you should read at least
the <xref linkend="dgui_quickstart" /> before this chapter.</para>
<section xml:id="pgui_quickstart_createconfiguration">
<title>Create a configuration instance</title>
<indexterm>
<primary>configuration</primary>
</indexterm>
<para>First you have to create a
<literal>freemarker.template.Configuration</literal> instance and
adjust its settings. A <literal>Configuration</literal> instance is a
central place to store the application level settings of FreeMarker.
Also, it deals with the creation and caching of pre-parsed
templates.</para>
<para>Probably you will <emphasis>do it only once</emphasis> at the
beginning of the application (possibly servlet) life-cycle:</para>
<programlisting role="unspecified">Configuration cfg = new Configuration();
// Specify the data source where the template files come from.
// Here I set a file directory for it:
cfg.setDirectoryForTemplateLoading(
new File("<replaceable>/where/you/store/templates</replaceable>"));
// Specify how templates will see the data-model. This is an advanced topic...
// but just use this:
cfg.setObjectWrapper(new DefaultObjectWrapper());</programlisting>
<para>From now you should use this single configuration instance. Note
however that if a system has multiple independent components that use
FreeMarker, then of course they will use their own private
<literal>Configuration</literal> instance.</para>
</section>
<section xml:id="pgui_quickstart_createdatamodel">
<title>Create a data-model</title>
<indexterm>
<primary>data-model</primary>
<secondary>assembling with Java</secondary>
</indexterm>
<para>In simple cases you can build data-models using
<literal>java.lang</literal> and <literal>java.util</literal> classes
and custom Java Beans:</para>
<itemizedlist>
<listitem>
<para>Use <literal>java.lang.String</literal> for strings.</para>
</listitem>
<listitem>
<para>Use <literal>java.lang.Number</literal> descents for
numbers.</para>
</listitem>
<listitem>
<para>Use <literal>java.lang.Boolean</literal> for boolean
values.</para>
</listitem>
<listitem>
<para>Use <literal>java.util.List</literal> or Java arrays for
sequences.</para>
</listitem>
<listitem>
<para>Use <literal>java.util.Map</literal> for hashes.</para>
</listitem>
<listitem>
<para>Use your custom bean class for hashes where the items
correspond to the bean properties. For example the
<literal>price</literal> property of <literal>product</literal>
can be get as <literal>product.price</literal>. (The actions of
the beans can be exposed as well; see much later <link
linkend="pgui_misc_beanwrapper">here</link>)</para>
</listitem>
</itemizedlist>
<para>For example, let's build the data-model of the <link
linkend="example.first">first example of the Template Author's
Guide</link>. For convenience, here it is again:</para>
<programlisting role="dataModel">(root)
|
+- user = "Big Joe"
|
+- latestProduct
|
+- url = "products/greenmouse.html"
|
+- name = "green mouse"</programlisting>
<para>This is the Java code fragment that builds this
data-model:</para>
<programlisting role="unspecified">// Create the root hash
Map root = new HashMap();
// Put string ``user'' into the root
root.put("user", "Big Joe");
// Create the hash for ``latestProduct''
Map latest = new HashMap();
// and put it into the root
root.put("latestProduct", latest);
// put ``url'' and ``name'' into latest
latest.put("url", "products/greenmouse.html");
latest.put("name", "green mouse");</programlisting>
<para>For the <literal>latestProduct</literal> you migh as well use a
Java Bean that has <literal>url</literal> and <literal>name</literal>
properties (that is, an object that has public <literal>String
getURL()</literal> and <literal>String getName()</literal> methods);
it's the same from viewpoint of the template.</para>
</section>
<section xml:id="pgui_quickstart_gettemplate">
<title>Get the template</title>
<indexterm>
<primary>template</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Templates are represented by
<literal>freemarker.template.Template</literal> instances. Typically
you obtain a <literal>Template</literal> instance from the
<literal>Configuration</literal> instance. Whenever you need a
template instance you can get it with its
<literal>getTemplate</literal> method. Store <link
linkend="example.first">the example template</link> in the
<literal>test.ftl</literal> file of the <link
linkend="pgui_quickstart_createconfiguration">earlier</link> set
directory, then you can do this:</para>
<programlisting role="unspecified">Template temp = cfg.getTemplate("test.ftl");</programlisting>
<para>When you call this, it will create a <literal>Template</literal>
instance corresponds to <literal>test.ftl</literal>, by reading
<literal><replaceable>/where/you/store/templates/</replaceable>test.ftl</literal>
and parsing (compile) it. The <literal>Template</literal> instance
stores the template in the parsed form, and not as text.</para>
<para><literal>Configuration</literal> caches
<literal>Template</literal> instances, so when you get
<literal>test.ftl</literal> again, it probably will not create new
<literal>Template</literal> instance (thus doesn't read and parse the
file), just returns the same instance as for the first time.</para>
</section>
<section xml:id="pgui_quickstart_merge">
<title>Merging the template with the data-model</title>
<indexterm>
<primary>output</primary>
<secondary>generate with Java</secondary>
</indexterm>
<indexterm>
<primary>merging</primary>
</indexterm>
<para>As we know, data-model + template = output, and we have a
data-model (<literal>root</literal>) and a template
(<literal>temp</literal>), so to get the output we have to merge them.
This is done by the <literal>process</literal> method of the template.
It takes the data-model root and a <literal>Writer</literal> as
parameters. It writes the produced output to the
<literal>Writer</literal>. For the sake of simplicity here I write to
the standard output:</para>
<programlisting role="unspecified">Writer out = new OutputStreamWriter(System.out);
temp.process(root, out);
out.flush();</programlisting>
<para>This will print to your terminal the output what you have seen
in the <link linkend="example.first">first example</link> of the
Template Author's Guide.</para>
<para>Once you have obtained a <literal>Template</literal> instance,
you can merge it with different data-models for unlimited times
(<literal>Template</literal> instances are basically stateless). Also,
the <literal>test.ftl</literal> file is accessed only while the
<literal>Template</literal> instance is created, not when you call the
process method.</para>
</section>
<section xml:id="pgui_quickstart_all">
<title>Putting all together</title>
<para>This is a working source file assembled from the previous
fragments. Don't forget to put <literal>freemarker.jar</literal> into
the <literal>CLASSPATH</literal>.</para>
<programlisting role="unspecified">import freemarker.template.*;
import java.util.*;
import java.io.*;
public class Test {
public static void main(String[] args) throws Exception {
/* ------------------------------------------------------------------- */
/* You should do this ONLY ONCE in the whole application life-cycle: */
/* Create and adjust the configuration */
Configuration cfg = new Configuration();
cfg.setDirectoryForTemplateLoading(
new File("<replaceable>/where/you/store/templates</replaceable>"));
cfg.setObjectWrapper(new DefaultObjectWrapper());
/* ------------------------------------------------------------------- */
/* You usually do these for many times in the application life-cycle: */
/* Get or create a template */
Template temp = cfg.getTemplate("test.ftl");
/* Create a data-model */
Map root = new HashMap();
root.put("user", "Big Joe");
Map latest = new HashMap();
root.put("latestProduct", latest);
latest.put("url", "products/greenmouse.html");
latest.put("name", "green mouse");
/* Merge data-model with template */
Writer out = new OutputStreamWriter(System.out);
temp.process(root, out);
out.flush();
}
}</programlisting>
<note>
<para>I have suppressed the exceptions for the sake of simplicity.
Don't do it in real products.</para>
</note>
</section>
</chapter>
<chapter xml:id="pgui_datamodel">
<title>The Data Model</title>
<para>This is just an introductory explanation. See the <olink
targetdoc="api">FreeMarker Java API documentation</olink> for more
detailed information.</para>
<section xml:id="pgui_datamodel_basics">
<title>Basics</title>
<indexterm>
<primary>object wrapper</primary>
</indexterm>
<indexterm>
<primary>wrapper</primary>
</indexterm>
<indexterm>
<primary>data-model</primary>
<secondary>assembling with Java, without object wrapper</secondary>
</indexterm>
<para>You have seen how to build a data-model in the <link
linkend="pgui_quickstart">Getting Started</link> using the standard
Java classes (<literal>Map</literal>, <literal>String</literal>,
etc.). Internally, the variables available in the template are java
objects that implement the
<literal>freemarker.template.TemplateModel</literal> interface. But
you could use standard java collections as variables in your
data-model, because these were replaced with the appropriate
<literal>TemplateModel</literal> instances behind the scenes. This
facility is called <emphasis role="term">object wrapping</emphasis>.
The object wrapping facility can convert <emphasis>any</emphasis> kind
of object transparently to the instances of classes that implement
<literal>TemplateModel</literal> interface. This makes it possible,
for example, to access <literal>java.sql.ResultSet</literal> as
sequence variable in templates, or to access
<literal>javax.servlet.ServletRequest</literal> objects as a hash
variable that contains the request attributes, or even to traverse XML
documents as FTL variables (<link linkend="xgui">see here</link>). To
wrap (convert) these objects, however, you need to plug the proper, so
called, object wrapper implementation (possibly your custom
implementation); this will be discussed <link
linkend="pgui_datamodel_objectWrapper">later</link>. The meat for now
is that any object that you want to access from the templates, sooner
or later must be converted to an object that implements
<literal>TemplateModel</literal> interface. So first you should
familiarize yourself with writing of <literal>TemplateModel</literal>
implementations.</para>
<para>There is roughly one
<literal>freemarker.template.TemplateModel</literal> descendant
interface corresponding to each basic type of variable
(<literal>TemplateHashModel</literal> for hashes,
<literal>TemplateSequenceModel</literal> sequences,
<literal>TemplateNumberModel</literal> for numbers, etc.). For
example, if you want to expose a <literal>java.sql.ResultSet</literal>
as a sequence for the templates, then you have to write a
<literal>TemplateSequenceModel</literal> implementation that can read
<literal>java.sql.ResultSet</literal>-s. We used to say on this, that
you <emphasis>wrap</emphasis> the
<literal>java.sql.ResultSet</literal> with your
<literal>TemplateModel</literal> implementation, as basically you just
encapsulate the <literal>java.sql.ResultSet</literal> to provide
access to it with the common <literal>TemplateSequenceModel</literal>
interface. Note that a class can implement multiple
<literal>TemplateModel</literal> interfaces; this is why FTL variables
can have multiple types (see: <xref
linkend="dgui_datamodel_basics" />)</para>
<para>Note that a trivial implementation of these interfaces is
provided with the <literal>freemarker.template</literal> package. For
example, to convert a <literal>String</literal> to FTL string
variable, you can use <literal>SimpleScalar</literal>, to convert a
<literal>java.util.Map</literal> to FTL hash variable, you can use
<literal>SimpleHash</literal>, etc.</para>
<para>An easy way to try your own <literal>TemplateModel</literal>
implementation, is to create an instance of that, and drop it directly
into the data-model (as <literal>put</literal> it into the root hash).
The object wrapper will expose it untouched for the template, as it
already implements <literal>TemplateModel</literal>, so no conversion
(wrapping) needed. (This trick is also useful in cases when you do not
want the object wrapper to try to wrap (convert) a certain
object.)</para>
</section>
<section xml:id="pgui_datamodel_scalar">
<title>Scalars</title>
<indexterm>
<primary>scalar</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>string</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>number</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>boolean</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>date</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>time</primary>
<secondary>Java side</secondary>
</indexterm>
<para>There are 4 scalar types:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Boolean</para>
</listitem>
<listitem>
<para>Number</para>
</listitem>
<listitem>
<para>String</para>
</listitem>
<listitem>
<para>Date</para>
</listitem>
</itemizedlist>
<para>For each scalar type is a
<literal>Template<replaceable>Type</replaceable>Model</literal>
interface, where <literal><replaceable>Type</replaceable></literal> is
the name of the type. These interfaces define only one method:
<literal><replaceable>type</replaceable>
getAs<replaceable>Type</replaceable>();</literal>. This returns the
value of the variable with the Java type (<literal>boolean</literal>,
<literal>Number</literal>, <literal>String</literal> and
<literal>Date</literal> respectively).</para>
<note>
<para>For historical reasons the interface for string scalars is
called <literal>TemplateScalarModel</literal>, not
<literal>TemplateStringModel</literal>.</para>
</note>
<para>A trivial implementation of these interfaces are available in
<literal>freemarker.template</literal> package with
<literal>Simple<replaceable>Type</replaceable></literal> class name.
However, there is no <literal>SimpleBooleanModel</literal>; to
represent the boolean values you can use the
<literal>TemplateBooleanModel.TRUE</literal> and
<literal>TemplateBooleanModel.FALSE</literal> singletons.</para>
<note>
<para>For historical reasons the class for string scalars is called
<literal>SimpleScalar</literal>, not
<literal>SimpleString</literal>.</para>
</note>
<para>Scalars are immutable within FTL. When you set the value of a
variable in a template, then you replace the
<literal>Template<replaceable>Type</replaceable>Model</literal>
instance with another instance, and don't change the value stored in
the original instance.</para>
<section>
<title>Difficulties with the date type</title>
<indexterm>
<primary>date</primary>
<secondary>Java API related difficulties</secondary>
</indexterm>
<indexterm>
<primary>time</primary>
<secondary>Java API related difficulties</secondary>
</indexterm>
<para>There is a complication around date types, because Java API
usually does not differentiate <literal>java.util.Date</literal>-s
that store only the date part (April 4, 2003), only the time part
(10:19:18 PM), or both (April 4, 2003 10:19:18 PM). To display a
date variable as text correctly, FreeMarker must know what parts of
the <literal>java.util.Date</literal> stores meaningful information,
and what parts are unused. Unfortunately, the only place where the
Java API cleanly tells this, is with database handling (SQL),
because databases typically has separated date, time and timestamp
(aka date-time) types, and <literal>java.sql</literal> has 3
corresponding <literal>java.util.Date</literal> subclasses for
them.</para>
<para><literal>TemplateDateModel</literal> interface has two
methods: <literal>java.util.Date getAsDate()</literal> and
<literal>int getDateType()</literal>. A typical implementation of
this interface, stores a <literal>java.util.Date</literal> object,
plus an integer that tells the "database style type". The value of
this integer must be a constant from the
<literal>TemplateDateModel</literal> interface:
<literal>DATE</literal>, <literal>TIME</literal>,
<literal>DATETIME</literal> and <literal>UNKNOWN</literal>.</para>
<para>What is <literal>UNKNOWN</literal>? As we told earlier,
<literal>java.lang</literal> and <literal>java.util</literal>
classes are usually converted automatically into
<literal>TemplateModel</literal> implementations, be so called
object wrappers. If the object wrapper faces a
<literal>java.util.Date</literal>, that is not an instance of a
<literal>java.sql</literal> date class, it can't decide what the
"database style type" is, so it uses <literal>UNKNOWN</literal>.
Later, if the template has to use this variable, and the "database
style type" is needed for the operation, it will stop with error. To
prevent this, for the problematic variables the template author must
help FreeMarker to decide the "database style type", by using the
<link linkend="ref_builtin_date_datetype"><literal>date</literal>,
<literal>time</literal> or <literal>datetime</literal>
built-ins</link>. Note that if you use <literal>string</literal>
built-in with format parameter, as
<literal>foo?string("MM/dd/yyyy")</literal>, then FreeMarker don't
need to know the "database style type".</para>
</section>
</section>
<section xml:id="pgui_datamodel_parent">
<title>Containers</title>
<indexterm>
<primary>containers</primary>
<secondary>Java side</secondary>
</indexterm>
<para>These are hashes, sequences, and collections.</para>
<section>
<title>Hashes</title>
<indexterm>
<primary>hash</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Hashes are java objects that implement
<literal>TemplateHashModel</literal> interface.
<literal>TemplateHashModel</literal> contains two methods:
<literal>TemplateModel get(String key)</literal>, which returns the
subvariable of the given name, and <literal>boolean
isEmpty()</literal>, which indicates if the hash has zero
subvariable or not. The <literal>get</literal> method returns null
if no subvariable with the given name exists.</para>
<para>The <literal>TemplateHashModelEx</literal> interface extends
<literal>TemplateHashModel</literal>. It adds methods by which <link
linkend="ref_builtin_values">values</link> and <link
linkend="ref_builtin_keys">keys</link> built-ins can enumerate the
subvariables of the hash.</para>
<para>The commonly used implementation is
<literal>SimpleHash</literal>, which implements
<literal>TemplateHashModelEx</literal>. Internally it uses a
<literal>java.util.Hash</literal> to store the subvariables.
<literal>SimpleHash</literal> has methods by which you can add and
remove subvariable. These methods should be used to initialize the
variable directly after its creation.</para>
<para>Containers are immutable within FTL. That is, you can't add,
replace or remove the subvariables they contain.</para>
</section>
<section>
<title>Sequences</title>
<indexterm>
<primary>sequence</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Sequences are java objects that implement
<literal>TemplateSequenceModel</literal>. It contains two methods:
<literal>TemplateModel get(int index)</literal> and <literal>int
size()</literal>.</para>
<para>The commonly used implementation is
<literal>SimpleSequence</literal>. It uses internally a
<literal>java.util.List</literal> to store its subvariables.
<literal>SimpleSequence</literal> has methods by which you can add
subvariables. These methods should be used to populate the sequence
directly after its creation.</para>
</section>
<section>
<title>Collections</title>
<indexterm>
<primary>collection</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Collections are java objects that implement the
<literal>TemplateCollectionModel</literal> interface. That interface
has one method: <literal>TemplateModelIterator iterator()</literal>.
The <literal>TemplateModelIterator</literal> interface is similar to
<literal>java.util.Iterator</literal>, but it returns
<literal>TemplateModels</literal> instead of
<literal>Object</literal>-s, and it can throw
<literal>TemplateModelException</literal>s.</para>
<para>The commonly used implementation is
<literal>SimpleCollection</literal>.</para>
</section>
</section>
<section xml:id="pgui_datamodel_method">
<title>Methods</title>
<indexterm>
<primary>method</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Method variables exposed to a template implement the
<literal>TemplateMethodModel</literal> interface. This contains one
method: <literal>TemplateModel exec(java.util.List
arguments)</literal>. When you call a method with a <link
linkend="dgui_template_exp_methodcall">method call expression</link>,
then the <literal>exec</literal> method will be called. The arguments
parameter will contain the values of the FTL method call arguments.
The return value of <literal>exec</literal> gives the value of the FTL
method call expression.</para>
<para>The <literal>TemplateMethodModelEx</literal> interface extends
<literal>TemplateMethodModel</literal>. It does not add any new
methods. The fact that the object implements this
<emphasis>marker</emphasis> interface indicates to the FTL engine that
the arguments should be put to the <literal>java.util.List</literal>
directly as <literal>TemplateModel</literal>-s. Otherwise they will be
put to the list as <literal>String</literal>-s.</para>
<para>For obvious reasons there is no default implementation for these
interfaces.</para>
<para>Example: This is a method, which returns the index within the
second string of the first occurrence of the first string, or -1 if
the second string doesn't contains the first.</para>
<programlisting role="unspecified">public class IndexOfMethod implements TemplateMethodModel {
public TemplateModel exec(List args) throws TemplateModelException {
if (args.size() != 2) {
throw new TemplateModelException("Wrong arguments");
}
return new SimpleNumber(
((String) args.get(1)).indexOf((String) args.get(0)));
}
}</programlisting>
<para>If you put an instance of this, say, into the root:</para>
<programlisting role="unspecified">root.put("indexOf", new IndexOfMethod());</programlisting>
<para>then you can call it in the template:</para>
<programlisting role="template"><#assign x = "something">
${indexOf("met", x)}
${indexOf("foo", x)}</programlisting>
<para>and then the output will be:</para>
<programlisting role="output">2
-1</programlisting>
<para>If you need to access the runtime FTL environment (read/write
variables, get the current locale, etc.), you can get it with
<literal>Environment.getCurrentEnvironment()</literal>.</para>
</section>
<section xml:id="pgui_datamodel_directive">
<title>Directives</title>
<indexterm>
<primary>directives</primary>
<secondary>Java side</secondary>
</indexterm>
<para>Java programmers can implement user-defined directives in Java
using the <literal>TemplateDirectiveModel</literal> interface. See in
the API documentation.</para>
<note>
<para><literal>TemplateDirectiveModel</literal> was introduced in
FreeMarker 2.3.11, replacing the soon to be depreciated
<literal>TemplateTransformModel</literal>.</para>
</note>
<section>
<title>Example 1</title>
<para>We will implement a directive which converts all output
between its start-tag and end-tag to upper case. Like, this
template:</para>
<programlisting role="template">foo
<emphasis><@upper></emphasis>
bar
<#-- All kind of FTL is allowed here -->
<#list ["red", "green", "blue"] as color>
${color}
</#list>
baaz
<emphasis></@upper></emphasis>
wombat</programlisting>
<para>will output this:</para>
<programlisting role="output">foo
BAR
RED
GREEN
BLUE
BAAZ
wombat</programlisting>
<para>This is the source code of the directive class:</para>
<programlisting role="unspecified">package com.example;
import java.io.IOException;
import java.io.Writer;
import java.util.Map;
import freemarker.core.Environment;
import freemarker.template.TemplateDirectiveBody;
import freemarker.template.TemplateDirectiveModel;
import freemarker.template.TemplateException;
import freemarker.template.TemplateModel;
import freemarker.template.TemplateModelException;
/**
* FreeMarker user-defined directive that progressively transforms
* the output of its nested content to upper-case.
*
*
* <p><b>Directive info</b></p>
*
* <p>Directive parameters: None
* <p>Loop variables: None
* <p>Directive nested content: Yes
*/
public class UpperDirective implements TemplateDirectiveModel {
public void execute(Environment env,
Map params, TemplateModel[] loopVars,
TemplateDirectiveBody body)
throws TemplateException, IOException {
// Check if no parameters were given:
if (!params.isEmpty()) {
throw new TemplateModelException(
"This directive doesn't allow parameters.");
}
if (loopVars.length != 0) {
throw new TemplateModelException(
"This directive doesn't allow loop variables.");
}
// If there is non-empty nested content:
if (body != null) {
// Executes the nested body. Same as <#nested> in FTL, except
// that we use our own writer instead of the current output writer.
body.render(new UpperCaseFilterWriter(env.getOut()));
} else {
throw new RuntimeException("missing body");
}
}
/**
* A {@link Writer} that transforms the character stream to upper case
* and forwards it to another {@link Writer}.
*/
private static class UpperCaseFilterWriter extends Writer {
private final Writer out;
UpperCaseFilterWriter (Writer out) {
this.out = out;
}
public void write(char[] cbuf, int off, int len)
throws IOException {
char[] transformedCbuf = new char[len];
for (int i = 0; i < len; i++) {
transformedCbuf[i] = Character.toUpperCase(cbuf[i + off]);
}
out.write(transformedCbuf);
}
public void flush() throws IOException {
out.flush();
}
public void close() throws IOException {
out.close();
}
}
}</programlisting>
<para>Now we still need to create an instance of this class, and
make this directive available to the template with the name "upper"
(or with whatever name we want) somehow. A possible solution is to
put the directive in the data-model:</para>
<programlisting role="unspecified">root.put("upper", new com.example.UpperDirective());</programlisting>
<para>But typically it is better practice to put commonly used
directives into the <literal>Configuration</literal> as <link
linkend="pgui_config_sharedvariables">shared
variables</link>.</para>
<para>It is also possible to put the directive into an FTL library
(collection of macros and like in a template, that you
<literal>include</literal> or <literal>import</literal> in other
templates) using the <link
linkend="ref_builtin_new"><literal>new</literal>
built-in</link>:</para>
<programlisting role="template"><#-- Maybe you have directives that you have implemented in FTL -->
<#macro something>
...
</#macro>
<#-- Now you can't use <#macro upper>, but instead you can: -->
<#assign upper = "com.example.UpperDirective"?new()>
</programlisting>
</section>
<section>
<title>Example 2</title>
<para>We will create a directive that executes its nested content
again and again for the specified number of times (similarly to
<literal>list</literal> directive), optionally separating the the
output of the repetations with a <literal><hr></literal>-s.
Let's call this directive "repeat". Example template:</para>
<programlisting role="template"><#assign x = 1>
<emphasis><@repeat count=4></emphasis>
Test ${x}
<#assign x = x + 1>
<emphasis></@repeat></emphasis>
<emphasis><@repeat count=3 hr=true></emphasis>
Test
<emphasis></@repeat></emphasis>
<emphasis><@repeat count=3; cnt></emphasis>
${cnt}. Test
<emphasis></@repeat></emphasis></programlisting>
<para>Output:</para>
<programlisting role="output"> Test 1
Test 2
Test 3
Test 4
Test
<hr> Test
<hr> Test
1. Test
2. Test
3. Test
</programlisting>
<para>The class:</para>
<programlisting role="unspecified">package com.example;
import java.io.IOException;
import java.io.Writer;
import java.util.Iterator;
import java.util.Map;
import freemarker.core.Environment;
import freemarker.template.SimpleNumber;
import freemarker.template.TemplateBooleanModel;
import freemarker.template.TemplateDirectiveBody;
import freemarker.template.TemplateDirectiveModel;
import freemarker.template.TemplateException;
import freemarker.template.TemplateModel;
import freemarker.template.TemplateModelException;
import freemarker.template.TemplateNumberModel;
/**
* FreeMarker user-defined directive for repeating a section of a template,
* optionally with separating the output of the repetations with
* <tt>&lt;hr></tt>-s.
*
*
* <p><b>Directive info</b></p>
*
* <p>Parameters:
* <ul>
* <li><code>count</code>: The number of repetations. Required!
* Must be a non-negative number. If it is not a whole number then it will
* be rounded <em>down</em>.
* <li><code>hr</code>: Tells if a HTML "hr" element could be printed between
* repetations. Boolean. Optional, defaults to <code>false</code>.
* </ul>
*
* <p>Loop variables: One, optional. It gives the number of the current
* repetation, starting from 1.
*
* <p>Nested content: Yes
*/
public class RepeatDirective implements TemplateDirectiveModel {
private static final String PARAM_NAME_COUNT = "count";
private static final String PARAM_NAME_HR = "hr";
public void execute(Environment env,
Map params, TemplateModel[] loopVars,
TemplateDirectiveBody body)
throws TemplateException, IOException {
// ---------------------------------------------------------------------
// Processing the parameters:
int countParam = 0;
boolean countParamSet = false;
boolean hrParam = false;
Iterator paramIter = params.entrySet().iterator();
while (paramIter.hasNext()) {
Map.Entry ent = (Map.Entry) paramIter.next();
String paramName = (String) ent.getKey();
TemplateModel paramValue = (TemplateModel) ent.getValue();
if (paramName.equals(PARAM_NAME_COUNT)) {
if (!(paramValue instanceof TemplateNumberModel)) {
throw new TemplateModelException(
"The \"" + PARAM_NAME_HR + "\" parameter "
+ "must be a number.");
}
countParam = ((TemplateNumberModel) paramValue)
.getAsNumber().intValue();
countParamSet = true;
if (countParam < 0) {
throw new TemplateModelException(
"The \"" + PARAM_NAME_HR + "\" parameter "
+ "can't be negative.");
}
} else if (paramName.equals(PARAM_NAME_HR)) {
if (!(paramValue instanceof TemplateBooleanModel)) {
throw new TemplateModelException(
"The \"" + PARAM_NAME_HR + "\" parameter "
+ "must be a boolean.");
}
hrParam = ((TemplateBooleanModel) paramValue)
.getAsBoolean();
} else {
throw new TemplateModelException(
"Unsupported parameter: " + paramName);
}
}
if (!countParamSet) {
throw new TemplateModelException(
"The required \"" + PARAM_NAME_COUNT + "\" paramter"
+ "is missing.");
}
if (loopVars.length > 1) {
throw new TemplateModelException(
"At most one loop variable is allowed.");
}
// Yeah, it was long and boring...
// ---------------------------------------------------------------------
// Do the actual directive execution:
Writer out = env.getOut();
if (body != null) {
for (int i = 0; i < countParam; i++) {
// Prints a <hr> between all repetations if the "hr" parameter
// was true:
if (hrParam && i != 0) {
out.write("<hr>");
}
// Set the loop variable, if there is one:
if (loopVars.length > 0) {
loopVars[0] = new SimpleNumber(i + 1);
}
// Executes the nested body (same as <#nested> in FTL). In this
// case we don't provide a special writer as the parameter:
body.render(env.getOut());
}
}
}
}</programlisting>
</section>
<section>
<title>Notices</title>
<para>It's important that a
<literal>TemplateDirectiveModel</literal> object usually should not
be stateful. The typical mistake is the storing of the state of the
directive call execution in the fields of the object. Think of
nested calls of the same directive, or directive objects used as
shared variables accessed by multiple threads concurrently.</para>
<para>Unfortunatelly, <literal>TemplateDirectiveModel</literal>-s
don't support passing parameters by position (rather than by name).
This is fixed starting from FreeMarker 2.4.</para>
</section>
</section>
<section xml:id="pgui_datamodel_node">
<title>Node variables</title>
<indexterm>
<primary>node</primary>
<secondary>Java side</secondary>
</indexterm>
<indexterm>
<primary>tree nodes</primary>
</indexterm>
<indexterm>
<primary>trees</primary>
</indexterm>
<para>A node variable embodies a node in a tree structure. Node
variables were introduced to help <link linkend="xgui">the handling of
XML documents in the data-model</link>, but they can be used for the
modeling of other tree structures as well. For more information about
nodes from the point of view of the template language <link
linkend="dgui_datamodel_node">read this earlier section</link>.</para>
<para>A node variable has the following properties, provided by the
methods of <literal>TemplateNodeModel</literal> interface:</para>
<itemizedlist>
<listitem>
<para>Basic properties:</para>
<itemizedlist>
<listitem>
<para><literal>TemplateSequenceModel
getChildNodes()</literal>: A node has sequence of children
(except if the node is a leaf node, in which case the method
return an empty sequence or null). The child nodes should be
node variables as well.</para>
</listitem>
<listitem>
<para><literal>TemplateNodeModel getParentNode()</literal>: A
node has exactly 1 parent node, except if the node is root
node of the tree, in which case the method returns
<literal>null</literal>.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Optional properties. If a property does not make sense in
the concrete use case, the corresponding method should return
<literal>null</literal>:</para>
<itemizedlist>
<listitem>
<para><literal>String getNodeName()</literal>: The node name
is the name of the macro, that handles the node when you use
<link
linkend="ref.directive.recurse"><literal>recurse</literal></link>
and <link
linkend="ref.directive.visit"><literal>visit</literal></link>
directives. Thus, if you want to use these directives with the
node, the node name is <emphasis>required</emphasis>.</para>
</listitem>
<listitem>
<para><literal>String getNodeType()</literal>: In the case of
XML: <literal>"element"</literal>, <literal>"text"</literal>,
<literal>"comment"</literal>, ...etc. This information, if
available, is used by the <literal>recurse</literal> and
<literal>visit</literal> directives to find the default
handler macro for a node. Also it can be useful for other
application specific purposes.</para>
</listitem>
<listitem>
<para><literal>String getNamespaceURI()</literal>: The node
namespace (has nothing to do with FTL namespaces used for
libraries) this node belongs to. For example, in the case of
XML, this is the URI of the XML namespace the element or
attribute belongs to. This information, if available, is used
by the <literal>recurse</literal> and <literal>visit</literal>
directives to find the FTL namespaces that store the handler
macros.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>On the FTL side, the direct utilization of node properties is
done with <link linkend="ref_builtins_node">node built-ins</link>, and
with the <literal>visit</literal> and <literal>recurse</literal>
macros.</para>
<para>In most use cases, variables that implement
<literal>TemplateNodeModel</literal>, implement other interfaces as
well, since node variable properties just provide the basic
infrastructure for navigating between nodes. For a concrete example,
see <link linkend="xgui">how FreeMarker deals with XML</link>.</para>
</section>
<section xml:id="pgui_datamodel_objectWrapper">
<title>Object wrappers</title>
<indexterm>
<primary>object wrapper</primary>
</indexterm>
<indexterm>
<primary>wrapper</primary>
</indexterm>
<para>When you add something to a container, it may receive any java
object as a parameter, not necessarily a
<literal>TemplateModel</literal>, as you could see in the FreeMarker
API. This is because the container implementation can silently replace
that object with the appropriate <literal>TemplateModel</literal>
object. For example if you add a <literal>String</literal> to the
container, perhaps it will be replaced with a
<literal>SimpleScalar</literal> instance which stores the same
text.</para>
<para>As for when the replacement occurs, it's the business of the
container in question (i.e. the business of the class that implements
the container interface), but it must happen at the latest when you
get the subvariable, as the getter methods (according to the
interfaces) return <literal>TemplateModel</literal>, not
<literal>Object</literal>. For example, <literal>SimpleHash</literal>,
<literal>SimpleSequence</literal> and
<literal>SimpleCollection</literal> use the laziest strategy; they
replace a non-<literal>TemplateModel</literal> subvariable with an
appropriate <literal>TemplateModel</literal> object when you get the
subvariable for the first time.</para>
<para>As for what java objects can be replaced, and with what
<literal>TemplateModel</literal> implementations, it is either handled
by the container implementation itself, or it delegates this to an
<literal>ObjectWrapper</literal> instance.
<literal>ObjectWrapper</literal> is an interface that specifies one
method: <literal>TemplateModel wrap(java.lang.Object obj)</literal>.
You pass in an <literal>Object</literal>, and it returns the
corresponding <literal>TemplateModel</literal> object, or throws a
<literal>TemplateModelException</literal> if this is not possible. The
replacement rules are coded into the <literal>ObjectWrapper</literal>
implementation.</para>
<para>The most important <literal>ObjectWrapper</literal>
implementations that the FreeMarker core provides are:</para>
<itemizedlist>
<listitem>
<para><literal>ObjectWrapper.DEFAULT_WRAPPER</literal>: It
replaces <literal>String</literal> with
<literal>SimpleScalar</literal>, <literal>Number</literal> with
<literal>SimpleNumber</literal>, <literal>List</literal> and array
with <literal>SimpleSequence</literal>, <literal>Map</literal>
with <literal>SimpleHash</literal>, <literal>Boolean</literal>
with <literal>TemplateBooleanModel.TRUE</literal> or
<literal>TemplateBooleanModel.FALSE</literal>, W3C DOM nodes with
<literal>freemarker.ext.dom.NodeModel</literal>. For Jython
objects, this wrapper will invoke
<literal>freemarker.ext.jython.JythonWrapper</literal>. For all
other objects, it will invoke <link
linkend="pgui_misc_beanwrapper"><literal>BEANS_WRAPPER</literal></link>.</para>
</listitem>
<listitem>
<para><literal>ObjectWrapper.BEANS_WRAPPER</literal>: It can
expose java Bean properties and other members of arbitrary objects
using Java reflection. At least in FreeMarker 2.3, it is a
<literal>freemarker.ext.beans.BeansWrapper</literal> instance;
there is a separated <link linkend="pgui_misc_beanwrapper">chapter
about it</link>.</para>
</listitem>
</itemizedlist>
<para>For a concrete example, let's see how the
<literal>Simple<replaceable>Xxx</replaceable></literal> classes work.
<literal>SimpleHash</literal>, <literal>SimpleSequence</literal> and
<literal>SimpleCollection</literal> use
<literal>DEFAULT_WRAPPER</literal> to wrap the subvariables (unless
you pass in an alternative wrapper in their constructor). So this
example demonstrates <literal>DEFAULT_WRAPPER</literal> in
action:</para>
<programlisting role="unspecified">Map map = new HashMap();
map.put("anotherString", "blah");
map.put("anotherNumber", new Double(3.14));
List list = new ArrayList();
list.add("red");
list.add("green");
list.add("blue");
SimpleHash root = new SimpleHash(); // will use the default wrapper
root.put("theString", "wombat");
root.put("theNumber", new Integer(8));
root.put("theMap", map);
root.put("theList", list);</programlisting>
<para>Assuming that root is the data-model root, the resulting
data-model is:</para>
<programlisting role="dataModel">(root)
|
+- theString = "wombat"
|
+- theNumber = 8
|
+- theMap
| |
| +- anotherString = "blah"
| |
| +- anotherNumber = 3.14
|
+- theList
|
+- (1st) = "red"
|
+- (2nd) = "green"
|
+- (3rd) = "blue"</programlisting>
<para>Note that the <literal>Object</literal>-s inside
<literal>theMap</literal> and <literal>theList</literal> are
accessible as subvariables too. This is because when you, say, try to
access <literal>theMap.anotherString</literal>, then the
<literal>SimpleHash</literal> (which is used as root hash here) will
silently replace the <literal>Map</literal>
(<literal>theMap</literal>) with a <literal>SimpleHash</literal>
instance that uses the same wrapper as the root hash, so when you try
to access the <literal>anotherString</literal> subvariable of it, it
will replace that with a <literal>SimpleScalar</literal>.</para>
<para>If you drop an ``arbitrary'' object into the data-model,
<literal>DEFAULT_WRAPPER</literal> will invoke
<literal>BEANS_WRAPPER</literal> to wrap the object:</para>
<programlisting role="unspecified">SimpleHash root = new SimpleHash();
// expose a "simple" java objects:
root.put("theString", "wombat");
// expose an "arbitrary" java objects:
root.put("theObject", new TestObject("green mouse", 1200));
</programlisting>
<para>Assuming this is <literal>TestObject</literal>:</para>
<programlisting role="unspecified">public class TestObject {
private String name;
private int price;
public TestObject(String name, int price) {
this.name = name;
this.price = price;
}
// JavaBean properties
// Note that public fields are not visible directly;
// you must write a getter method for them.
public String getName() {return name;}
public int getPrice() {return price;}
// A method
public double sin(double x) {
return Math.sin(x);
}
}</programlisting>
<para>The data-model will be:</para>
<programlisting role="dataModel">(root)
|
+- theString = "wombat"
|
+- theObject
|
+- name = "green mouse"
|
+- price = 1200
|
+- number sin(number)</programlisting>
<para>So we can merge it with this template:</para>
<programlisting role="template">${theObject.name}
${theObject.price}
${theObject.sin(123)}</programlisting>
<para>Which will output:</para>
<programlisting role="output">green mouse
1200
-0,45990349068959124</programlisting>
<para>You have seen in earlier examples of this manual that we have
used <literal>java.util.HashMap</literal> as root hash, and not
<literal>SimpleHash</literal> or other FreeMarker specific class. It
works because
<literal>Template.process(<replaceable>...</replaceable>)</literal>
automatically wraps the object you give as its data-model argument. It
uses the object wrapper dictated by the
<literal>Configuration</literal> level <link
linkend="pgui_config_settings">setting</link>,
<literal>object_wrapper</literal> (unless you explicitly specify an
<literal>ObjectWrapper</literal> as its parameter). Thus, in simple
FreeMarker application you need not know about
<literal>TemplateModel</literal>-s at all. Note that the root need not
be a <literal>java.util.Map</literal>. It can be anything that is
wrapped so that it implements the <literal>TemplateHashModel</literal>
interface.</para>
<para>The factory default value of the
<literal>object_wrapper</literal> setting is
<literal>ObjectWrapper.DEFAULT_WRAPPER</literal>. If you want to
change it to, say, <literal>ObjectWrapper.BEANS_WRAPPER</literal>, you
can configure the FreeMarker engine (before starting to use it from
other threads) like this:</para>
<programlisting role="unspecified">cfg.setObjectWrapper(ObjectWrapper.BEANS_WRAPPER);</programlisting>
<para>Note that you can set any object here that implements interface
<literal>ObjectWrapper</literal>, so you can set your custom
implementation as well.</para>
<para>For <literal>TemplateModel</literal> implementations that wrap
basic Java container types, as <literal>java.util.Map</literal>-s and
<literal>java.util.List</literal>-s, the convention is that they use
the same object wrapper to wrap their subvariables as their parent
container does. Technically correctly said, they are instantiated by
their parent container (so it has full control over the creation of
them), and the parent container create them so they will use the same
object wrapper as the parent itself. Thus, if
<literal>BEANS_WRAPPER</literal> is used for the wrapping of the root
hash, it will be used for the wrapping of the subvariables (and the
subvariables of the subvariables, etc.) as well. This is exactly the
same phenomenon as you have seen with
<literal>theMap.anotherString</literal> earlier.</para>
</section>
</chapter>
<chapter xml:id="pgui_config">
<title>The Configuration</title>
<indexterm>
<primary>Configuration</primary>
</indexterm>
<para>This is just an overview. See the <olink
targetdoc="api">FreeMarker Java API documentation</olink> for the
details.</para>
<section xml:id="pgui_config_basics">
<title>Basics</title>
<para>A configuration is an object that stores your common
(application level) settings and defines certain variables that you
want to be available in all templates. Also it deals with the creation
and caching of <literal>Template</literal> instances. A configuration
is a <literal>freemarker.template.Configuration</literal> instances,
that you can create with its constructor. An application typically
uses only a single shared <literal>Configuration</literal>
instance.</para>
<para>Configurations are used by the <literal>Template</literal>
methods, especially by <literal>process</literal> method. Each
<literal>Template</literal> instance has exactly one
<literal>Configuration</literal> instance associated with it, which is
assigned to the <literal>Template</literal> instance by the
<literal>Template</literal> constructor; you can specify a
<literal>Configuration</literal> instance as its parameter. Usually
you obtain <literal>Template</literal> instances with
<literal>Configuration.getTemplate</literal> (not by directly calling
the <literal>Template</literal> constructor), in which case the
associated <literal>Configuration</literal> instance will be the one
whose <literal>getTemplate</literal> method has been called.</para>
</section>
<section xml:id="pgui_config_sharedvariables">
<title>Shared variables</title>
<indexterm>
<primary>shared variable</primary>
</indexterm>
<para><emphasis role="term">Shared variables</emphasis> are variables
that are defined for all templates. You can add shared variables to
the configuration with the <literal>setSharedVariable</literal>
methods:</para>
<programlisting role="unspecified">Configuration cfg = new Configuration();
<replaceable>...</replaceable>
cfg.setSharedVariable("wrap", new WrapDirective());
cfg.setSharedVariable("company", "Foo Inc."); // Using ObjectWrapper.DEFAULT_WRAPPER</programlisting>
<para>In all templates that use this configuration, an user-defined
directive with name <literal>wrap</literal> and a string with name
<literal>company</literal> will be visible in the data-model root, so
you don't have to add them to the root hash again and again. A
variable in the root object that you pass to the
<literal>Template.process</literal> will hide the shared variable with
the same name.</para>
<warning>
<para>Never use <literal>TemplateModel</literal> implementation that
is not <link linkend="gloss.threadSafe">thread-safe</link> for
shared variables, if the configuration is used by multiple threads!
This is the typical situation for Servlet based Web sites.</para>
</warning>
<para>Due to backward compatibility heritage, the set of shared
variables is initially (i.e., for a new
<literal>Configuration</literal> instance) not empty. It contains the
following user-defined directives (they are "user-defined" in the
sense that you use <literal>@</literal> to call them instead of
<literal>#</literal>):</para>
<informaltable border="1">
<thead>
<tr>
<th>name</th>
<th>class</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>capture_output</literal></td>
<td><literal>freemarker.template.utility.CaptureOutput</literal></td>
</tr>
<tr>
<td><literal>compress</literal></td>
<td><literal>freemarker.template.utility.StandardCompress</literal></td>
</tr>
<tr>
<td><literal>html_escape</literal></td>
<td><literal>freemarker.template.utility.HtmlEscape</literal></td>
</tr>
<tr>
<td><literal>normalize_newlines</literal></td>
<td><literal>freemarker.template.utility.NormalizeNewlines</literal></td>
</tr>
<tr>
<td><literal>xml_escape</literal></td>
<td><literal>freemarker.template.utility.XmlEscape</literal></td>
</tr>
</tbody>
</informaltable>
</section>
<section xml:id="pgui_config_settings">
<title>Settings</title>
<indexterm>
<primary>setting</primary>
</indexterm>
<para><emphasis role="term">Settings</emphasis> are named values that
influence the behavior of FreeMarker. Examples of settings are:
<literal>locale</literal>, <literal>number_format</literal></para>
<para>Settings stored in <literal>Configuration</literal> instance can
be overridden in a <literal>Template</literal> instance. For example
you set <literal>"en_US"</literal> for the <literal>locale</literal>
setting in the configuration, then the <literal>locale</literal> in
all templates that use this configuration will be
<literal>"en_US"</literal>, except in templates where the locale was
explicitly specified differently (see <link
linkend="ref_directive_include_localized">localization</link>). Thus,
values in a <literal>Configuration</literal> serve as defaults that
can be overridden in a per template manner. The value comes from
<literal>Configuration</literal> instance or
<literal>Template</literal> instance can be further overridden for a
single <literal>Template.process</literal> call. For each such call a
<literal>freemarker.core.Environment</literal> object is created
internally that holds the runtime environment of the template
processing, including the setting values that were overridden on that
level. The values stored there can even be changed during the template
processing, so a template can set settings itself, like switching
<literal>locale</literal> at the middle of the output.</para>
<para>This can be imagined as 3 layers
(<literal>Configuration</literal>, <literal>Template</literal>,
<literal>Environment</literal>) of settings, where the topmost layer
that contains the value for a certain setting provides the effective
value of that setting. For example (settings A to F are just imaginary
settings for this example):</para>
<informaltable border="1">
<col align="left" />
<col align="center" span="6" />
<thead>
<tr>
<th></th>
<th>Setting A</th>
<th>Setting B</th>
<th>Setting C</th>
<th>Setting D</th>
<th>Setting E</th>
<th>Setting F</th>
</tr>
</thead>
<tbody>
<tr>
<td>Layer 3: <literal>Environment</literal></td>
<td>1</td>
<td>-</td>
<td>-</td>
<td>1</td>
<td>-</td>
<td>-</td>
</tr>
<tr>
<td>Layer 2: <literal>Template</literal></td>
<td>2</td>
<td>2</td>
<td>-</td>
<td>-</td>
<td>2</td>
<td>-</td>
</tr>
<tr>
<td>Layer 1: <literal>Configuration</literal></td>
<td>3</td>
<td>3</td>
<td>3</td>
<td>3</td>
<td>-</td>
<td>-</td>
</tr>
</tbody>
</informaltable>
<para>The effective value of settings will be: A = 1, B = 2, C = 3, D
= 1, E = 2. The F setting is probably <literal>null</literal>, or it
throws exception when you try to get it.</para>
<para>Let's see exactly how to set settings:</para>
<itemizedlist>
<listitem>
<para><literal>Configuration</literal> layer: In principle you set
the settings with the setter methods of the
<literal>Configuration</literal> object, fore example:</para>
<programlisting role="unspecified">Configuration myCfg = new Configuration();
myCfg.setLocale(java.util.Locale.ITALY);
myCfg.setNumberFormat("0.####");</programlisting>
<para>You do it before you start to actually use the
<literal>Configuration</literal> object (typically, when you
initialize the application); you should treat the object as
read-only after that.</para>
<para>In practice, in most Web application frameworks you have to
specify the setting in a framework-specific configuration file
that require specifying setting as <literal>String</literal>
name-value pairs (like in a <literal>.properties</literal> file).
In that case the authors of the frameworks most probably use the
<literal>setSetting(String name, String value)</literal> method of
<literal>Configuration</literal>; see available setting names and
the format of the values in the API doc of
<literal>setSetting</literal>. Example for Spring
Framework:</para>
<programlisting role="unspecified"><bean id="freemarkerConfig"
class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
<property name="freemarkerSettings">
<props>
<prop key="locale">it_IT</prop>
<prop key="number_format">0.####</prop>
</props>
</property>
</bean></programlisting>
<para>Note that this kind of configuring
(<literal>String</literal> key-value pairs) is unfortunately
limited compared to directly using the API of
<literal>Configuration</literal>.</para>
</listitem>
<listitem>
<para><literal>Template</literal> layer: You shouldn't set
settings here, unless you manage the <literal>Template</literal>
objects instead of a
<literal>freemarker.cache.TemplateCache</literal>, in which case
you should set the setting before the <literal>Template</literal>
object is first used, and then treat the
<literal>Template</literal> object as read-only.</para>
</listitem>
<listitem>
<para><literal>Environment </literal>layer: There are two ways
doing it:</para>
<itemizedlist>
<listitem>
<para>With Java API: Use the setter methods of the
<literal>Environment</literal> object. Certainly you want to
do that just before the processing of the template is started,
and then you run into the problem that when you call
<literal>myTemplate.process(...)</literal> it creates the
<literal>Environment</literal> object internally and the
immediately processes the template, so you had no chance. The
solution is that this two steps can be separated like
this:</para>
<programlisting role="unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out);
env.setLocale(java.util.Locale.ITALY);
env.setNumberFormat("0.####");
env.process(); // process the template</programlisting>
</listitem>
<listitem>
<para>Directly in the Template: Use the <link
linkend="ref.directive.setting"><literal>setting</literal>
directive</link>, for example:</para>
<programlisting role="template"><#setting locale="it_IT">
<#setting number_format="0.####"></programlisting>
</listitem>
</itemizedlist>
<para>There are no restriction regarding when can you change the
settings in this layer.</para>
</listitem>
</itemizedlist>
<para>To see the list of supported settings, please read the following
parts of the FreeMarker Java API documentation:</para>
<itemizedlist>
<listitem>
<para>Setter methods of
<literal>freemarker.core.Configurable</literal> for the settings
that are in all three layers</para>
</listitem>
<listitem>
<para>Setter methods of
<literal>freemarker.template.Configuration</literal> for the
settings that are available only in the
<literal>Configuration</literal> layer</para>
</listitem>
<listitem>
<para><literal>freemarker.core.Configurable.setSetting(String,
String)</literal> for settings that are available in all three
layers and are writable with <literal>String</literal> key-value
pairs.</para>
</listitem>
<listitem>
<para><literal>freemarker.template.Configuration.setSetting(String,
String)</literal> for settings that are available only in the
<literal>Configuration</literal> layer and are writable with
<literal>String</literal> key-value pairs.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="pgui_config_templateloading">
<title>Template loading</title>
<indexterm>
<primary>loading templates</primary>
</indexterm>
<indexterm>
<primary>template loading</primary>
</indexterm>
<indexterm>
<primary>storing templates</primary>
</indexterm>
<section>
<title>Template loaders</title>
<indexterm>
<primary>template loaders</primary>
</indexterm>
<para>Template loaders are objects that load raw textual data based
on abstract template paths like <literal>"index.ftl"</literal> or
<literal>"products/catalog.ftl"</literal>. It is up to the concrete
template loader object what source does it use to fetch the
requested data (files in a directory, data base, etc.). When you
call <literal>cfg.getTemplate</literal> (where
<literal>cfg</literal> is a <literal>Configuration</literal>
instance), FreeMarker ask the template loader you have set up for
the <literal>cfg</literal> to return the text for the given template
path, and then FreeMarker parses that text as template.</para>
<section>
<title>Built-in template loaders</title>
<para>You can set up three template loading methods in the
<literal>Configuration</literal> using the following convenience
methods. (Each method will create a template loader object
internally and set up the <literal>Configuration</literal>
instance to use that.)</para>
<programlisting role="unspecified">void setDirectoryForTemplateLoading(File dir);</programlisting>
<para>or</para>
<programlisting role="unspecified">void setClassForTemplateLoading(Class cl, String prefix);</programlisting>
<para>or</para>
<programlisting role="unspecified">void setServletContextForTemplateLoading(Object servletContext, String path);</programlisting>
<para>The first method above sets an explicit directory on the
file system from which to load templates. Needless to say perhaps,
the <literal>File</literal> parameter must be an existing
directory. Otherwise, an exception will be thrown.</para>
<para>The second call takes a <literal>Class</literal> as a
parameter and a prefix. This is for when you want to load
templates via the same mechanism that a java
<literal>ClassLoader</literal> uses to load classes. This means
that the class you pass in will be used to call
<literal>Class.getResource()</literal> to find the templates. The
<literal>prefix</literal> parameter is prepended to the name of
the template. The classloading mechanism will very likely be the
preferred means of loading templates for production code, since
loading from the classpath mechanism is usually more foolproof
than specifying an explicit directory location on the file system.
It is also nicer in a final application to keep everything in a
<literal>.jar</literal> file that the user can simply execute
directly and have all the icons and text and everything else
inside the <literal>.jar</literal> file.</para>
<para>The third call takes the context of your web application,
and a base path, which is interpreted relative to the web
application root directory (that's the parent of the
<literal>WEB-INF</literal> directory). This loader will load the
templates from the web application directory. Note that we refer
to "directory" here although this loading method works even for
unpacked <literal>.war</literal> files since it uses
<literal>ServletContext.getResource()</literal> to access the
templates. If you omit the second parameter (or use
<literal>""</literal>), you can simply store the static files
(<literal>.html</literal>, <literal>.jpg</literal>, etc.) mixed
with the <literal>.ftl</literal> files, just
<literal>.ftl</literal> files will be sent to the client
processed. Of course, you must set up a Servlet for the
<literal>*.ftl</literal> uri-pattern in
<literal>WEB-INF/web.xml</literal> for this, otherwise the client
will get the templates as is, and thus may see confidential
content! You should not use empty path if this is a problem for
your site, rather you should store the templates somewhere inside
the <literal>WEB-INF</literal> directory, so the raw templates are
never served accidentally. This mechanism will very likely be the
preferred means of loading templates for servlet applications,
since the templates can be updated without restarting the web
application, while this often doesn't work with the class-loader
mechanism.</para>
</section>
<section>
<title>Loading templates from multiple locations</title>
<para>If you need to load templates from multiple locations, you
have to instantiate the template loader objects for every
location, wrap them into a special template loader named
<literal>MultiTemplateLoader</literal> and finally pass that
loader to the <literal>setTemplateLoader(TemplateLoader
loader)</literal> method of <literal>Configuration</literal>.
Here's an example for loading templates from two distinct
directories and with the class-loader:</para>
<programlisting role="unspecified">import freemarker.cache.*; // template loaders live in this package
<replaceable>...</replaceable>
FileTemplateLoader ftl1 = new FileTemplateLoader(new File("/tmp/templates"));
FileTemplateLoader ftl2 = new FileTemplateLoader(new File("/usr/data/templates"));
ClassTemplateLoader ctl = new ClassTemplateLoader(getClass(), "");
TemplateLoader[] loaders = new TemplateLoader[] { ftl1, ftl2, ctl };
MultiTemplateLoader mtl = new MultiTemplateLoader(loaders);
cfg.setTemplateLoader(mtl);</programlisting>
<para>Now FreeMarker will try to load templates from
<literal>/tmp/templates</literal> directory, and if it does not
find the requested template there, it will try to load that from
<literal>/usr/data/templates</literal>, and if it still does not
find the requested template, then it tries to load that with the
class-loader.</para>
</section>
<section>
<title>Loading templates from other sources</title>
<para>If none of the built-in class loaders are good for you, you
will have to write your own class that implements the
<literal>freemarker.cache.TemplateLoader</literal> interface and
pass it to the <literal>setTemplateLoader(TemplateLoader
loader)</literal> method of <literal>Configuration</literal>.
Please read the API JavaDoc for more information.</para>
<para>If your template source accesses the templates through an
URL, you needn't implement a <literal>TemplateLoader</literal>
from scratch; you can choose to subclass
<literal>freemarker.cache.URLTemplateLoader</literal> instead and
just implement the <literal>URL getURL(String
templateName)</literal> method.</para>
</section>
<section>
<title>The template path</title>
<indexterm>
<primary>path</primary>
</indexterm>
<indexterm>
<primary>template path</primary>
</indexterm>
<para>It is up to the template loader how it interprets template
paths. But to work together with other components there are
restrictions regarding the format of the path. In general, it is
strongly recommended that template loaders use URL-style paths.
The path must not use <literal>/</literal>, <literal>./</literal>
and <literal>../</literal> and <literal>://</literal> with other
meaning as they have in URL paths (or in UN*X paths). The
characters <literal>*</literal> and <literal>?</literal> are
reserved. Also, the template loader must not want paths starting
with <literal>/</literal>; FreeMarker will never call template
loader with such path. Note that FreeMarker always normalizes the
paths before passing them to the template loader, so the paths do
not contain <literal>/../</literal> and such, and are relative to
the imaginary template root directory.</para>
<para>Note that FreeMarker template loading always uses slash (not
backslash) regardless of the host OS.</para>
</section>
</section>
<section xml:id="pgui_config_templateloading_caching">
<title>Template caching</title>
<indexterm>
<primary>caching</primary>
</indexterm>
<indexterm>
<primary>template caching</primary>
</indexterm>
<para>FreeMarker caches templates (assuming you use the
<literal>Configuration</literal> methods to create
<literal>Template</literal> objects). This means that when you call
<literal>getTemplate</literal>, FreeMarker not only returns the
resulting <literal>Template</literal> object, but stores it in a
cache, so when next time you call <literal>getTemplate</literal>
with the same (or equivalent) path, it just returns the cached
<literal>Template</literal> instance, and will not load and parse
the template file again.</para>
<para>If you change the template file, then FreeMarker will re-load
and re-parse the template automatically when you get the template
next time. However, since checking if the file has been changed can
be time consuming, there is a <literal>Configuration</literal> level
setting called ``update delay''. This is the time that must elapse
since the last checking for a newer version of a certain template
before FreeMarker will check that again. This is set to 5 seconds by
default. If you want to see the changes of templates immediately,
set it to 0. Note that some template loaders may have problems with
template updating. For example, class-loader based template loaders
typically do not notice that you have changed the template
file.</para>
<para>A template will be removed from the cache if you call
<literal>getTemplate</literal> and FreeMarker realizes that the
template file has been removed meanwhile. Also, if the JVM thinks
that it begins to run out of memory, by default it can arbitrarily
drop templates from the cache. Furthermore, you can empty the cache
manually with the <literal>clearTemplateCache</literal> method of
<literal>Configuration</literal>.</para>
<para>The actual strategy of when a cached template should be thrown
away is pluggable with the <literal>cache_storage</literal> setting,
by which you can plug any <literal>CacheStorage</literal>
implementation. For most users
<literal>freemarker.cache.MruCacheStorage</literal> will be
sufficient. This cache storage implements a two-level Most Recently
Used cache. In the first level, items are strongly referenced up to
the specified maximum (strongly referenced items can't be dropped by
the JVM, as opposed to softly referenced items). When the maximum is
exceeded, the least recently used item is moved into the second
level cache, where they are softly referenced, up to another
specified maximum. The size of the strong and soft parts can be
specified with the constructor. For example, set the size of the
strong part to 20, and the size of soft part to 250:</para>
<programlisting role="unspecified">cfg.setCacheStorage(new freemarker.cache.MruCacheStorage(20, 250))</programlisting>
<para>Or, since <literal>MruCacheStorage</literal> is the default
cache storage implementation:</para>
<programlisting role="unspecified">cfg.setSetting(Configuration.CACHE_STORAGE_KEY, "strong:20, soft:250");</programlisting>
<para>When you create a new <literal>Configuration</literal> object,
initially it uses an <literal>MruCacheStorage</literal> where
<literal>maxStrongSize</literal> is 0, and
<literal>maxSoftSize</literal> is
<literal>Integer.MAX_VALUE</literal> (that is, in practice,
infinite). But using non-0 <literal>maxStrongSize</literal> is maybe
a better strategy for high load servers, since it seems that, with
only softly referenced items, JVM tends to cause just higher
resource consumption if the resource consumption was already high,
because it constantly throws frequently used templates from the
cache, which then have to be re-loaded and and re-parsed.</para>
</section>
</section>
<section xml:id="pgui_config_errorhandling">
<title>Error handling</title>
<indexterm>
<primary>error handling</primary>
</indexterm>
<indexterm>
<primary>exception handling</primary>
</indexterm>
<section>
<title>The possible exceptions</title>
<para>The exceptions that can occur regarding FreeMarker could be
classified like this:</para>
<itemizedlist>
<listitem>
<para>Exceptions occurring when you configure FreeMarker:
Typically you configure FreeMarker only once in your
application, when your application initializes itself. Of
course, during this, exceptions can occur, as it is obvious from
the FreeMarker API...</para>
</listitem>
<listitem>
<para>Exceptions occurring when loading and parsing templates:
When you call
<literal>Configuration.getTemplate(<replaceable>...</replaceable>)</literal>,
FreeMarker has to load the template file into the memory and
parse it (unless the template is already <link
linkend="pgui_config_templateloading_caching">cached</link> in
that <literal>Configuration</literal> object). During this, two
kind of exceptions can occur:</para>
<itemizedlist>
<listitem>
<para><literal>IOException</literal> because the template
file was not found, or other I/O problem occurred while
trying to read it, for example you have no right to read the
file, or there are disk errors. The emitter of these errors
is the <link
linkend="pgui_config_templateloading"><literal>TemplateLoader</literal>
object</link>, which is plugged into the
<literal>Configuration</literal> object. (For the sake of
correctness: When I say ``file'' here, that's a
simplification. For example, templates can be stored in a
table of a relational database as well. This is the business
of the <literal>TemplateLoader</literal>.)</para>
</listitem>
<listitem>
<para><literal>freemarker.core.ParseException</literal>
because the template file is syntactically incorrect
according the rules of the FTL language. The point is that
this error occurs when you obtain the
<literal>Template</literal> object
(<literal>Configuration.getTemplate(<replaceable>...</replaceable>)</literal>),
and not when you execute
(<literal>Template.process(<replaceable>...</replaceable>)</literal>)
the template. This exception is an
<literal>IOException</literal> subclass.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Exceptions occurring when executing (processing)
templates, that is, when you call
<literal>Template.process(<replaceable>...</replaceable>)</literal>.
Two kind of exceptions can occur:</para>
<itemizedlist>
<listitem>
<para><literal>IOException</literal> because there was an
error when trying to write into the output writer.</para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplatException</literal>
because other problem occurred while executing the template.
For example, a frequent error is when a template refers to a
variable which is not existing. Be default, when a
<literal>TemplatException</literal> occurs, FreeMarker
prints the FTL error message and the stack trace to the
output writer with plain text format, and then aborts the
template execution by re-throwing the
<literal>TemplatException</literal>, which then you can
catch as
<literal>Template.process(<replaceable>...</replaceable>)</literal>
throws it. But this behavior can be customized. FreeMarker
always <link linkend="pgui_misc_logging">logs</link>
<literal>TemplatException</literal>-s.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section>
<title>Customizing the behavior regarding TemplatException-s</title>
<para><literal>TemplateException</literal>-s thrown during the
template processing are handled by the
<literal>freemarker.template.TemplateExceptionHandler</literal>
object, which is plugged into the <literal>Configuration</literal>
object with its
<literal>setTemplateExceptionHandler(<replaceable>...</replaceable>)</literal>
mehod. The <literal>TemplateExceptionHandler</literal> contains 1
method:</para>
<programlisting role="unspecified">void handleTemplateException(TemplateException te, Environment env, Writer out)
throws TemplateException;</programlisting>
<para>Whenever a <literal>TemplateException</literal> occurs, this
method will be called. The exception to handle is passed with the
<literal>te</literal> argument, the runtime environment of the
template processing is accessible with the <literal>env</literal>
argument, and the handler can print to the output using the
<literal>out</literal> argument. If the method throws exception
(usually it re-throws <literal>te</literal>), then the template
processing will be aborted, and
<literal>Template.process(<replaceable>...</replaceable>)</literal>
will throw the same exception. If
<literal>handleTemplateException</literal> doesn't throw exception,
then template processing continues as if nothing had happen, but the
statement that caused the exception will be skipped (see more
later). Of course, the handler can still print an error indicator to
the output.</para>
<para>In any case, before the
<literal>TemplateExceptionHandler</literal> is invoked, FreeMarker
will <link linkend="pgui_misc_logging">log</link> the
exception.</para>
<para>Let's see how FreeMarker skips ``statements'' when the error
handler doesn't throw exception, through examples. Assume we are
using this template exception handler:</para>
<programlisting role="unspecified">class MyTemplateExceptionHandler implements TemplateExceptionHandler {
public void handleTemplateException(TemplateException te, Environment env, java.io.Writer out)
throws TemplateException {
try {
out.write("[ERROR: " + te.getMessage() + "]");
} catch (IOException e) {
throw new TemplateException("Failed to print error message. Cause: " + e, env);
}
}
}
<replaceable>...</replaceable>
cfg.setTemplateExceptionHandler(new MyTemplateExceptionHandler());</programlisting>
<para>If an error occurs in an interpolation which is not inside an
FTL tag (that is, not enclosed into
<literal><#<replaceable>...</replaceable>></literal> or
<literal><@<replaceable>...</replaceable>></literal>), then
the whole interpolation will be skipped. So this template (assuming
that <literal>badVar</literal> is missing from the
data-model):</para>
<programlisting role="template">a${badVar}b</programlisting>
<para>will print this if we use the
<literal>MyTemplateExceptionHandler</literal>:</para>
<programlisting role="output">a[ERROR: Expression badVar is undefined on line 1, column 4 in test.ftl.]b</programlisting>
<para>This template will print the same (except that the column
number will differ...):</para>
<programlisting role="template">a${"moo" + badVar}b</programlisting>
<para>since, as it was written, the whole interpolation is skipped
if any error occurs inside it.</para>
<para>If an error occurs when evaluating the value of a parameter
for a directive call, or if there are other problems with the
parameter list, or if an error occurs when evaluating
<literal><replaceable>exp</replaceable></literal> in
<literal><@<replaceable>exp</replaceable>
<replaceable>...</replaceable>></literal>, or if the value of
<literal><replaceable>exp</replaceable></literal> is not an
user-defined directive, then the whole directive call is skipped.
For example this:</para>
<programlisting role="template">a<#if badVar>Foo</#if>b</programlisting>
<para>will print this:</para>
<programlisting role="output">a[ERROR: Expression badVar is undefined on line 1, column 7 in test.ftl.]b</programlisting>
<para>Note that the error occurred in the <literal>if</literal>
start-tag (<literal><#if badVar></literal>), but the whole
directive call was skipped. Logically, the nested content
(<literal>Foo</literal>) was skipped with this, since the nested
content is handled (printed) by the enclosing directive
(<literal>if</literal>).</para>
<para>The output will be the same with this (except that the column
number will differ...):</para>
<programlisting role="template">a<#if "foo${badVar}" == "foobar">Foo</#if>b</programlisting>
<para>since, as it was written, the whole directive calling will be
skipped if any error occurs during the parameter evaluation.</para>
<para>The directive call will not be skipped if the error occurs
after the execution of the directive was already started. That is,
if an error occurs in the nested content:</para>
<programlisting role="template">a
<#if true>
Foo
${badVar}
Bar
</#if>
c</programlisting>
<para>or in the macro definition body:</para>
<programlisting role="template">a
<@test />
b
<#macro test>
Foo
${badVar}
Bar
</#macro></programlisting>
<para>the output will be something like:</para>
<programlisting role="output">a
Foo
[ERROR: Expression badVar is undefined on line 4, column 5 in test.ftl.]
Bar
c</programlisting>
<para>FreeMarker comes with these prewritten error handlers:</para>
<itemizedlist>
<listitem>
<para><literal>TemplateExceptionHandler.DEBUG_HANDLER</literal>:
Prints stack trace (includes FTL error message and FTL stack
trace) and re-throws the exception. This is the default handler
(that is, it is initially prugged into all new
<literal>Configuration</literal> objects).</para>
</listitem>
<listitem>
<para><literal>TemplateExceptionHandler.HTML_DEBUG_HANDLER</literal>:
Same as <literal>DEBUG_HANDLER</literal>, but it formats the
stack trace so that it will be readable with Web browsers.
Recommended over <literal>DEBUG_HANDLER</literal> when you
generate HTML pages.</para>
</listitem>
<listitem>
<para><literal>TemplateExceptionHandler.IGNORE_HANDLER</literal>:
Simply suppresses all exceptions (but remember, FreeMarker will
still log them). It does nothing to handle the event. It does
not re-throw the exception.</para>
</listitem>
<listitem>
<para><literal>TemplateExceptionHandler.RETHROW_HANDLER</literal>:
Simply re-throws all exceptions, it doesn't do anything else.
This handler can be good for Web applications (assuming you
don't want to continue template processing after exception),
because it gives the most control to the Web application over
page generation on error conditions (since FreeMarker doesn't
print anything to the output about the error). For more
information about handling errors in Web applications <link
linkend="misc.faq.niceErrorPage">see the FAQ</link>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Explicit error handling in templates</title>
<para>Although it has nothing to do with the FreeMarker
configuration (the topic of this chapter), for the sake of
completeness it is mentioned here that you can handle errors
directly in templates as well. This is usually a bad practice (try
keep templates simple and non-technical), but nonetheless necessary
sometimes:</para>
<itemizedlist>
<listitem>
<para>Handling missing/null variables: <xref
linkend="dgui_template_exp_missing" /></para>
</listitem>
<listitem>
<para>Surviving malfunctioning ``portlets'' and such expendable
page sections: <xref linkend="ref_directive_attempt" /></para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>
<chapter xml:id="pgui_misc">
<title>Miscellaneous</title>
<para>This is just an introductory guide. See the <olink
targetdoc="api">FreeMarker Java API documentation</olink> for the
details.</para>
<section xml:id="pgui_misc_var">
<title>Variables</title>
<indexterm>
<primary>variables</primary>
</indexterm>
<para>This chapter explains what happens when a template tries to
access a variable, and how the variables are stored.</para>
<para>When you call <literal>Template.process</literal> it will
internally create an <literal>Environment</literal> object that will
be in use until <literal>process</literal> returns. This object stores
the runtime state of template processing. Among other things, it
stores the variables created by the template with directives like
<literal>assign</literal>, <literal>macro</literal>,
<literal>local</literal> or <literal>global</literal>. It never tries
to modify the data-model object that you pass to the
<literal>process</literal> call, nor does it create or replace shared
variables stored in the configuration.</para>
<para>When you try to read a variable, FreeMarker will seek the
variable in this order, and stops when it finds a variable with the
right name:</para>
<orderedlist>
<listitem>
<para>In the Environment:</para>
<orderedlist>
<listitem>
<para>If you are in a loop, in the set of loop variables. Loop
variables are the variables created by directives like
<literal>list</literal>.</para>
</listitem>
<listitem>
<para>If you are inside a macro, in the local variable set of
the macro. Local variables can be created with the
<literal>local</literal> directive. Also, the parameters of
macros are local variables.</para>
</listitem>
<listitem>
<para>In the current <link
linkend="dgui_misc_namespace">namespace</link>. You can put
variables into a namespace with the <literal>assign</literal>
directive.</para>
</listitem>
<listitem>
<para>In the set of variables created with
<literal>global</literal> directive. FTL handles these
variables as if they were normal members of the data-model.
That is, they are visible in all namespaces, and you can
access them as if they would be in the data-model.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>In the data-model object you have passed to the
<literal>process</literal> method</para>
</listitem>
<listitem>
<para>In the set of shared variables stored in the
<literal>Configuration</literal></para>
</listitem>
</orderedlist>
<para>In practice, from the viewpoint of template authors these 6
layers are only 4 layers, since from that viewpoint the last 3 layers
(variables created with <literal>global</literal>, the actual
data-model object, shared variables) together constitute the set of
global variables.</para>
<para>Note that it is possible to get variables from a specific layer
in FTL with <link linkend="ref_specvar">special
variables</link>.</para>
</section>
<section xml:id="pgui_misc_charset">
<title>Charset issues</title>
<indexterm>
<primary>charset</primary>
</indexterm>
<indexterm>
<primary>encoding</primary>
</indexterm>
<para>FreeMarker, as most Java applications, works with "<link
linkend="gloss.unicode">UNICODE</link> text" (UTF-16). Nonetheless,
there are situations when it must deal with <link
linkend="gloss.charset">charsets</link>, because it has to exchange
data with the outer world that may uses various charsets.</para>
<section>
<title>The charset of the input</title>
<para>When FreeMarker has to load a template file (or an unparsed
text file), then it must know the charset of the file, since files
are just raw byte arrays. You can use the
<literal>encoding</literal> <link
linkend="pgui_config_settings">setting</link> to specify the
charset. This setting takes effect only when FreeMarker loads a
template (parsed or unparsed) with the
<literal>getTemplate</literal> method of
<literal>Configuration</literal>. Note that the <link
linkend="ref.directive.include"><literal>include</literal>
directive</link> uses this method internally, so the value of the
<literal>encoding</literal> setting is significant for an already
loaded template if the template contains <literal>include</literal>
directive call.</para>
<para>The getter and setter method of the
<literal>encoding</literal> setting is special in the first
(configuration) layer. The getter method guesses the return value
based on a <literal>Locale</literal> passed as parameter; it looks
up the encoding in a table that maps locales to encodings (called
encoding map), and if the locale was not found there, it returns the
default encoding. You can fill the encoding map with the
<literal>setEncoding(Locale locale, String encoding)</literal>
method of the configuration; the encoding map is initially empty.
The default encoding is initially the value of the
<literal>file.encoding</literal> system property, but you can set a
different default with the <literal>setDefaultEncoding</literal>
method.</para>
<para>You can give the charset directly by overriding the
<literal>encoding</literal> setting in the template layer or runtime
environment layer (When you specify an encoding as the parameter of
<literal>getTemplate</literal> method, you override the
<literal>encoding</literal> setting in the template layer.). If you
don't override it, the effective value will be what the
<literal>configuration.getEncoding(Locale)</literal> method returns
for the effective value of the <literal>locale</literal>
setting.</para>
<para>Also, instead of relying on this charset guessing mechanism,
you can specify the charset of the template in the template file
itself, with the <link
linkend="ref.directive.ftl"><literal>ftl</literal></link>
directive.</para>
<para>You may wonder what charset you should choose for the
templates. It primarily depends on the tools (as text editors) that
you want to use to create and modify templates. In principle, using
UTF-8 is the best, but currently (2004) only a few tools supports
it, actually most of them doesn't even know about charsets. So in
that case you should use the widely used charset of your language,
which is probably also the default charset of you working
environment.</para>
<para>Note that the charset of the template is independent from the
charset of the output that the tempalte generates (unless the
enclosing software deliberately sets the output charset to the same
as the template charset).</para>
</section>
<section>
<title>The charset of the output</title>
<note>
<para>The <literal>output_encoding</literal> setting/variable and
the <link linkend="ref_builtin_url"><literal>url</literal>
built-in</link> is available since FreeMarker 2.3.1. It doesn't
exist in 2.3.</para>
</note>
<para><indexterm>
<primary>output encoding</primary>
</indexterm><indexterm>
<primary>output charset</primary>
</indexterm>In principle FreeMarker does not deal with the charset
of the output, since it writes the output to a
<literal>java.io.Writer</literal>. Since the
<literal>Writer</literal> is made by the software that encapsulates
FreeMarker (such as a Web application framework), the output charset
is controlled by the encapsulating software. Still, FreeMarker has a
setting called <literal>output_encoding</literal> (starting from
FreeMarker version 2.3.1). The enclosing software should set this
setting (to the charset that the <literal>Writer</literal> uses), to
inform FreeMarker what charset is used for the output (otherwise
FreeMarker can't find it out). Some features, such as the <link
linkend="ref_builtin_url"><literal>url</literal> built-in</link>,
and the <link
linkend="ref_specvar"><literal>output_encoding</literal> special
variable</link> utilize this information. Thus, if the enclosing
software doesn't set this setting then FreeMarker features that need
to know the output charset can't be used.</para>
<para>If you write software that will use FreeMarker, you may wonder
what output charset should you choose. Of course it depends on the
consumer of the FreeMarker output, but if the consumer is flexible
regarding this question, then the common practice is either using
the charset of the template file for the output, or using UTF-8.
Using UTF-8 is usually a better practice, because arbitrary text may
comes from the data-model, which then possibly contains characters
that couldn't be encoded with the charset of the template.</para>
<para>FreeMarker settings can be set for each individual template
processing if you use
<literal>Template.createProcessingEnvironment(<replaceable>...</replaceable>)</literal>
plus
<literal>Environment.process(<replaceable>...</replaceable>)</literal>
instead of
<literal>Template.process(<replaceable>...</replaceable>)</literal>.
Thus, you can set the <literal>output_encoding</literal> setting for
each template execution independently:</para>
<programlisting role="unspecified">Writer w = new OutputStreamWriter(out, outputCharset);
Environment env = template.createProcessingEnvironment(dataModel, w);
env.setOutputEncoding(outputCharset);
env.process();</programlisting>
</section>
</section>
<section xml:id="pgui_misc_multithreading">
<title>Multithreading</title>
<indexterm>
<primary>multithreading</primary>
</indexterm>
<indexterm>
<primary>thread-safety</primary>
</indexterm>
<para>In a multithreaded environment <literal>Configuration</literal>
instances, <literal>Template</literal> instances and data-models
should be handled as immutable (read-only) objects. That is, you
create and initialize them (for example with
<literal>set<replaceable>...</replaceable></literal> methods), and
then you don't modify them later (e.g. you don't call
<literal>set<replaceable>...</replaceable></literal>). This allows us
to avoid expensive synchronized blocks in a multithreaded environment.
Beware with <literal>Template</literal> instances; when you get a
<literal>Template</literal> instance with
<literal>Configuration.getTemplate</literal>, you may get an instance
from the template cache that is already used by other threads, so do
not call its <literal>set<replaceable>...</replaceable></literal>
methods (calling <literal>process</literal> is of course fine).</para>
<para>The above restrictions do not apply if you access all objects
from the <emphasis>same</emphasis> single thread only.</para>
<para>It is impossible to modify the data-model object or a <link
linkend="pgui_config_sharedvariables">shared variable</link> with FTL,
unless you put methods (or other objects) into the data-model that do
that. We discourage you from writing methods that modify the
data-model object or the shared variables. Try to use variables that
are stored in the environment object instead (this object is created
for a single <literal>Template.process</literal> call to store the
runtime state of processing), so you don't modify data that are
possibly used by multiple threads. For more information read: <xref
linkend="pgui_misc_var" /></para>
</section>
<section xml:id="pgui_misc_beanwrapper">
<title>Bean wrapper</title>
<indexterm>
<primary>wrapping</primary>
<secondary>reflection</secondary>
</indexterm>
<indexterm>
<primary>wrapping</primary>
<secondary>beans</secondary>
</indexterm>
<indexterm>
<primary>beans</primary>
<secondary>wrapping</secondary>
</indexterm>
<para>The <literal>freemarker.ext.beans.BeansWrapper</literal> is an
<link linkend="pgui_datamodel_objectWrapper">object wrapper</link>
that was originally added to FreeMarker so arbitrary POJO-s (Plain Old
Java Objects) can be wrapped into <literal>TemplateModel</literal>
interfaces. Since then it has becomed the normal way of doing things,
and in fact the <literal>DefaultObjectWrapper</literal> itself is a
<literal>BeansWrapper</literal> extension. So everything described
here goes for the <literal>DefaultObjectWrapper</literal> too, except
that the <literal>DefaultObjectWrapper</literal> will wrap
<literal>String</literal>, <literal>Number</literal>,
<literal>Date</literal>, <literal>array</literal>,
<literal>Collection</literal> (like <literal>List</literal>),
<literal>Map</literal>, <literal>Boolean</literal> and
<literal>Iterator</literal> objects with the
<literal>freemarker.template.Simple<replaceable>Xxx</replaceable></literal>
classes, and W3C DOM nodes with
<literal>freemarker.ext.dom.NodeModel</literal> (<link
linkend="xgui">more about wrapped W3C DOM...</link>), so for those the
above described rules doesn't apply.</para>
<para>You will want to use <literal>BeansWrapper</literal> instead of
<literal>DefaultObjectWrapper</literal> when any of these
stands:</para>
<itemizedlist>
<listitem>
<para>The <literal>Collection</literal>-s and
<literal>Map</literal>-s of the model should be allowed to be
modified during template execution.
(<literal>DefaultObjectWrapper</literal> prevents that, since it
creates a copy of the collections when they are wrapped, and the
copies will be read-only.)</para>
</listitem>
<listitem>
<para>If the identity of the <literal>array</literal>,
<literal>Collection</literal> and <literal>Map</literal> objects
must be kept when they are passed to a wrapped object's method in
the template. That is, if those methods must get exactly the same
object that was earlier wrapped.</para>
</listitem>
<listitem>
<para>If the Java API of the earlier listed classes
(<literal>String</literal>, <literal>Map</literal>,
<literal>List</literal> ...etc) should be visible for the
templates. Even with <literal>BeansWrapper</literal>, they are not
visible by default, but it can be achieved by setting the exposure
level (see later). Note that this is usually a bad practice; try
to use <link linkend="ref_builtins">the built-ins</link> (like
<literal>foo?size</literal>, <literal>foo?upper</literal>,
<literal>foo?replace('_', '-')</literal> ...etc) instead of the
Java API.</para>
</listitem>
</itemizedlist>
<para>Below is a summary of the <literal>TemplateModel</literal>-s
that the <literal>BeansWrapper</literal> creates. Let's assume that
the object is called <literal>obj</literal> before wrapping, and
<literal>model</literal> after wrapping for the sake of the following
discussion.</para>
<section xml:id="beanswrapper_hash">
<title>TemplateHashModel functionality</title>
<para>Every object will be wrapped into a
<literal>TemplateHashModel</literal> that will expose JavaBeans
properties and methods of the object. This way, you can use
<literal>model.foo</literal> in the template to invoke
<literal>obj.getFoo()</literal> or <literal>obj.isFoo()</literal>
methods. (Note that public fields are not visible directly; you must
write a getter method for them.) Public methods are also retrievable
through the hash model as template method models, therefore you can
use the <literal>model.doBar()</literal> to invoke
<literal>object.doBar()</literal>. More on this on discussion of
method model functionality.</para>
<para>If the requested key can not be mapped to a bean property or
method, the framework will attempt to locate the so-called "generic
get method", that is a method with signature public
<literal><replaceable>any-return-type</replaceable>
get(String)</literal> or public
<literal><replaceable>any-return-type</replaceable>
get(Object)</literal> and invoke that method with the requested key.
Note that this allows convenient access to mappings in a
<literal>java.util.Map</literal> and similar classes - as long as
the keys of the map are <literal>String</literal>s and some property
or method name does not shadow the mapping. (There is a solution to
avoid shadowing, read on.) Also note that the models for
<literal>java.util.ResourceBundle</literal> objects use the
<literal>getObject(String)</literal> as the generic get
method.</para>
<para>If you call <literal>setExposeFields(true)</literal> on a
<literal>BeansWrapper</literal> instance, it will also expose
public, non-static fields of classes as hash keys and values. I.e.
if <literal>foo</literal> is a public, non-static field of the class
<literal>Bar</literal>, and <literal>bar</literal> is a template
variable wrapping an instance of <literal>Bar</literal>, then
<literal>bar.foo</literal> expression will evaluate as the value of
the field <literal>foo</literal> of the <literal>bar</literal>
object. The public fields in all superclasses of the class are also
exposed.</para>
</section>
<section>
<title>A word on security</title>
<para>By default, you will not be able to access several methods
that are considered not safe for templating. For instance, you can't
use synchronization methods (<literal>wait</literal>,
<literal>notify</literal>, <literal>notifyAll</literal>), thread and
thread group management methods (<literal>stop</literal>,
<literal>suspend</literal>, <literal>resume</literal>,
<literal>setDaemon</literal>, <literal>setPriority</literal>),
reflection (<literal>Field</literal>
<literal>set<replaceable>Xxx</replaceable></literal> methods,
<literal>Method.invoke</literal>,
<literal>Constructor.newInstance</literal>,
<literal>Class.newInstance</literal>,
<literal>Class.getClassLoader</literal> etc.) and various dangerous
methods in <literal>System</literal> and <literal>Runtime</literal>
classes (<literal>exec</literal>, <literal>exit</literal>,
<literal>halt</literal>, <literal>load</literal>, etc.). The
<literal>BeansWrapper</literal> has several security levels (called
"levels of method exposure"), and the default called
<literal>EXPOSE_SAFE</literal> is probably suited for most
applications. There is a no-safeguard level called
<literal>EXPOSE_ALL</literal> that allows you to call even the above
unsafe methods, and a strict level
<literal>EXPOSE_PROPERTIES_ONLY</literal> that will expose only bean
property getters. Finally, there is a level named
<literal>EXPOSE_NOTHING</literal> that will expose no properties and
no methods. The only data you will be able to access through hash
model interface in this case are items in maps and resource bundles,
as well as objects returned from a call to generic
<literal>get(Object)</literal> or <literal>get(String)</literal>
methods - provided the affected objects have such method.</para>
</section>
<section>
<title>TemplateScalarModel functionality</title>
<para>Models for <literal>java.lang.String</literal> objects will
implement <literal>TemplateScalarModel</literal> whose
<literal>getAsString()</literal> method simply delegates to
<literal>toString()</literal>. Note that wrapping
<literal>String</literal> objects into Bean wrappers provides much
more functionality than just them being scalars: because of the hash
interface described above, the models that wrap
<literal>String</literal>s also provide access to all
<literal>String</literal> methods (<literal>indexOf</literal>,
<literal>substring</literal>, etc.).</para>
</section>
<section>
<title>TemplateNumberModel functionality</title>
<para>Model wrappers for objects that are instances of
<literal>java.lang.Number</literal> implement
<literal>TemplateNumberModel</literal> whose
<literal>getAsNumber()</literal> method returns the wrapped number
object. Note that wrapping <literal>Number</literal> objects into
Bean wrappers provides much more functionality than just them being
number models: because of the hash interface described above, the
models that wrap <literal>Number</literal>s also provide access to
all their methods.</para>
</section>
<section>
<title>TemplateCollectionModel functionality</title>
<para>Model wrappers for native Java arrays and all classes that
implement <literal>java.util.Collection</literal> will implement
<literal>TemplateCollectionModel</literal> and thus gain the
additional capability of being usable through
<literal>list</literal> directive.</para>
</section>
<section>
<title>TemplateSequenceModel functionality</title>
<para>Model wrappers for native Java arrays and all classes that
implement <literal>java.util.List</literal> will implement
<literal>TemplateSequenceModel</literal> and thus their elements
will be accessible by index using the <literal>model[i]</literal>
syntax. You can also query the length of the array or the size of
the list using the <literal>model?size</literal> built-in.</para>
<para>Also, every method that takes a single parameter that is
assignable through reflective method invocation from a
<literal>java.lang.Integer</literal> (these are
<literal>int</literal>, <literal>long</literal>,
<literal>float</literal>, <literal>double</literal>,
<literal>java.lang.Object</literal>,
<literal>java.lang.Number</literal>, and
<literal>java.lang.Integer</literal>) also implements this
interface. What this means is that you have a convenient way for
accessing the so-called indexed bean properties:
<literal>model.foo[i]</literal> will translate into
<literal>obj.getFoo(i)</literal>.</para>
</section>
<section xml:id="beanswrapper_method">
<title>TemplateMethodModel functionality</title>
<para>All methods of an object are represented as
<literal>TemplateMethodModelEx</literal> objects accessible using a
hash key with method name on their object's model. When you call a
method using
<literal>model.<replaceable>method</replaceable>(<replaceable>arg1</replaceable>,
<replaceable>arg2</replaceable>,
<replaceable>...</replaceable>)</literal> the arguments are passed
to the method as template models. The method will first try to
unwrap them - see below for details about unwrapping. These
unwrapped arguments are then used for the actual method call. In
case the method is overloaded, the most specific method will be
selected using the same rules that are used by the Java compiler to
select a method from several overloaded methods. In case that no
method signature matches the passed parameters, or that no method
can be chosen without ambiguity, a
<literal>TemplateModelException</literal> is thrown.</para>
<para>Methods of return type <literal>void</literal> return
<literal>TemplateModel.NOTHING</literal>, so they can be safely
called with the <literal>${obj.method(args)}</literal>
syntax.</para>
<para>Models for instances of <literal>java.util.Map</literal> also
implement <literal>TemplateMethodModelEx</literal> as a means for
invoking their <literal>get()</literal> method. As it was discussed
previously, you can use the hash functionality to access the "get"
method as well, but it has several drawbacks: it's slower because
first property and method names are checked for the key; keys that
conflict with property and method names will be shadowed by them;
finally you can use <literal>String</literal> keys only with that
approach. In contrast, invoking <literal>model(key)</literal>
translates to <literal>model.get(key)</literal> directly: it's
faster because there's no property and method name lookup; it is
subject to no shadowing; and finally it works for non-String keys
since the argument is unwrapped just as with ordinary method calls.
In effect, <literal>model(key)</literal> on a <literal>Map</literal>
is equal to <literal>model.get(key)</literal>, only shorter to
write.</para>
<para>Models for <literal>java.util.ResourceBundle</literal> also
implement <literal>TemplateMethodModelEx</literal> as a convenient
way of resource access and message formatting. A single-argument
call to a bundle will retrieve the resource with the name that
corresponds to the <literal>toString()</literal> value of the
unwrapped argument. A multiple-argument call to a bundle will also
retrieve the resource with the name that corresponds to the
<literal>toString()</literal> value of the unwrapped argument, but
it will use it as a format pattern and pass it to
<literal>java.text.MessageFormat</literal> using the unwrapped
values of second and later arguments as formatting parameters.
<literal>MessageFormat</literal> objects will be initialized with
the locale of the bundle that originated them.</para>
</section>
<section>
<title>Unwrapping rules</title>
<para>When invoking a Java method from a template, its arguments
need to be converted from template models back to Java objects.
Assuming that the target type (the declared type of the method's
formal parameter) is denoted as <literal>T</literal>, the following
rules are tried in the following order:</para>
<itemizedlist>
<listitem>
<para>If the model is the null model for this wrapper, Java
<literal>null</literal> is returned.</para>
</listitem>
<listitem>
<para>If the model implements
<literal>AdapterTemplateModel</literal>, the result of
<literal>model.getAdaptedObject(T)</literal> is returned if it
is instance of <literal>T</literal> or it is a number and can be
converted to <literal>T</literal> using numeric coercion as
described three bullets lower. <phrase role="forProgrammers">All
models created by the BeansWrapper are themselves
AdapterTemplateModel implementations, so unwrapping a model that
was created by BeansWrapper for an underlying Java object always
yields the original Java object.</phrase></para>
</listitem>
<listitem>
<para>If the model implements the deprecated
<literal>WrapperTemplateModel</literal>, the result of
<literal>model.getWrappedObject()</literal> is returned if it is
instance of <literal>T</literal> or it is a number and can be
converted to <literal>T</literal> using numeric coercion as
described two bullets lower.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is
<literal>java.lang.String</literal>, then if model implements
<literal>TemplateScalarModel</literal> its string value is
returned. <phrase role="forProgrammers">Note that if the model
doesn't implement TemplateScalarModel we don't attempt to
automatically convert the model to string using
String.valueOf(model). You'll have to use the ?string built-in
explicitly to pass non-scalars as strings.</phrase></para>
</listitem>
<listitem>
<para>If <literal>T</literal> is a primitive numeric type or
<literal>java.lang.Number</literal> is assignable from
<literal>T</literal>, and model implements
<literal>TemplateNumberModel</literal>, then its numeric value
is returned if it is instance of <literal>T</literal> or its
boxing type (if <literal>T</literal> is primitive type).
Otherwise, if <literal>T</literal> is a built-in Java numeric
type (primitive type or a standard subclass of
<literal>java.lang.Number</literal>, including
<literal>BigInteger</literal> and <literal>BigDecimal</literal>)
a new object of class <literal>T</literal> or its boxing type is
created with the number model's appropriately coerced
value.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is <literal>boolean</literal> or
<literal>java.lang.Boolean</literal>, and model implements
<literal>TemplateBooleanModel</literal>, then its boolean value
is returned.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is
<literal>java.util.Map</literal> and the model implements
<literal>TemplateHashModel</literal>, then a special Map
representation of the hash model is returned.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is
<literal>java.util.List</literal> and the model implements
<literal>TemplateSequenceModel</literal>, then a special List
representation of the sequence model is returned.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is
<literal>java.util.Set</literal> and the model implements
<literal>TemplateCollectionModel</literal>, then a special Set
representation of the collection model is returned.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is
<literal>java.util.Collection</literal> or
<literal>java.lang.Iterable</literal> and the model implements
either <literal>TemplateCollectionModel</literal> or
<literal>TemplateSequenceModel</literal>, then a special Set or
List representation of the collection or sequence model
(respectively) is returned.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is a Java array type and the model
implements <literal>TemplateSequenceModel</literal>, then a new
array of the specified type is created and its elements
unwrapped into the array recursively using the array's component
type as <literal>T</literal>.</para>
</listitem>
<listitem>
<para>If <literal>T</literal> is <literal>char</literal> or
<literal>java.lang.Character</literal>, and model implements
<literal>TemplateScalarModel</literal>, and its string
representation contains exactly one character, then a
<literal>java.lang.Character</literal> with that value is
retured.</para>
</listitem>
<listitem>
<para>If <literal>java.util.Date</literal> is assignable from
<literal>T</literal>, and model implements
<literal>TemplateDateModel</literal>, and its date value is
instance of <literal>T</literal>, then its date value is
returned.</para>
</listitem>
<listitem>
<para>If model is a number model, and its numeric value is
instance of <literal>T</literal>, the numeric value is returned.
<phrase role="forProgrammers">You can have a custom subclass of
java.lang.Number that implements a custom interface, and T might
be that interface. (*)</phrase></para>
</listitem>
<listitem>
<para>If model is a date model, and its date value is instance
of <literal>T</literal>, the date value is returned. <phrase
role="forProgrammers">Similar consideration as for
(*)</phrase></para>
</listitem>
<listitem>
<para>If model is a scalar model, and <literal>T</literal> is
assignable from <literal>java.lang.String</literal>, the string
value is returned. <phrase role="forProgrammers">This covers
cases when T is java.lang.Object, java.lang.Comparable, and
java.io.Serializable (**)</phrase></para>
</listitem>
<listitem>
<para>If model is a boolean model, and <literal>T</literal> is
assignable from <literal>java.lang.Boolean</literal>, the
boolean value is returned. <phrase role="forProgrammers">Same as
(**)</phrase></para>
</listitem>
<listitem>
<para>If model is a hash model, and <literal>T</literal> is
assignable from
<literal>freemarker.ext.beans.HashAdapter</literal>, a hash
adapter is returned. <phrase role="forProgrammers">Same as
(**)</phrase></para>
</listitem>
<listitem>
<para>If model is a sequence model, and <literal>T</literal> is
assignable from
<literal>freemarker.ext.beans.SequenceAdapter</literal>, a
sequence adapter is returned. <phrase role="forProgrammers">Same
as (**)</phrase></para>
</listitem>
<listitem>
<para>If model is a collection model, and <literal>T</literal>
is assignable from
<literal>freemarker.ext.beans.SetAdapter</literal>, a set
adapter for the collection is returned. <phrase
role="forProgrammers">Same as (**)</phrase></para>
</listitem>
<listitem>
<para>If the model is instance of <literal>T</literal>, the
model itself is returned. <phrase role="forProgrammers">This
covers the case where the method explicitly declared a
FreeMarker-specific model interface, as well as allows returning
directive, method and transform models when java.lang.Object is
requested.</phrase></para>
</listitem>
<listitem>
<para>An exception signifying no conversion is possible is
thrown.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Accessing static methods</title>
<indexterm>
<primary>static method</primary>
<secondary>accessing from templates</secondary>
</indexterm>
<para>The <literal>TemplateHashModel</literal> returned from
<literal>BeansWrapper.getStaticModels()</literal> can be used to
create hash models for accessing static methods and fields of an
arbitrary class.</para>
<programlisting role="unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance();
TemplateHashModel staticModels = wrapper.getStaticModels();
TemplateHashModel fileStatics =
(TemplateHashModel) staticModels.get("java.io.File");</programlisting>
<para>And you will get a template hash model that exposes all static
methods and static fields (both final and non-final) of the
<literal>java.lang.System</literal> class as hash keys. Suppose that
you put the previous model in your root model:</para>
<programlisting role="unspecified">root.put("File", fileStatics);</programlisting>
<para>From now on, you can use <literal>${File.SEPARATOR}</literal>
to insert the file separator character into your template, or you
can even list all roots of your file system by:</para>
<programlisting role="template"><#list File.listRoots() as fileSystemRoot>...</#list></programlisting>
<para>Of course, you must be aware of the potential security issues
this model brings.</para>
<para>You can even give the template authors complete freedom over
which classes' static methods they use by placing the static models
hash into your template root model with</para>
<programlisting role="unspecified">root.put("statics", BeansWrapper.getDefaultInstance().getStaticModels());</programlisting>
<para>This object exposes just about any class' static methods if
it's used as a hash with class name as the key. You can then use
expression like
<literal>${statics["java.lang.System"].currentTimeMillis()}</literal>
in your template. Note, however that this has even more security
implications, as someone could even invoke
<literal>System.exit()</literal> using this model if the method
exposure level is weakened to <literal>EXPOSE_ALL</literal>.</para>
<para>Note that in above examples, we always use the default
<literal>BeansWrapper</literal> instance. This is a convenient
static wrapper instance that you can use in most cases. You are also
free to create your own <literal>BeansWrapper</literal> instances
and use them instead especially when you want to modify some of its
characteristics (like model caching, security level, or the null
model representation).</para>
</section>
<section xml:id="jdk_15_enums">
<title>Accessing enums</title>
<indexterm>
<primary>enum</primary>
</indexterm>
<para>The <literal>TemplateHashModel</literal> returned from
<literal>BeansWrapper.getEnumModels()</literal> can be used to
create hash models for accessing values of enums on JRE 1.5 or
later. (An attempt to invoke this method on an earlier JRE will
result in an
<literal>UnsupportedOperationException</literal>.)</para>
<programlisting role="unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance();
TemplateHashModel enumModels = wrapper.getEnumModels();
TemplateHashModel roundingModeEnums =
(TemplateHashModel) enumModels.get("java.math.RoundingMode");</programlisting>
<para>And you will get a template hash model that exposes all enum
values of the <literal>java.math.RoundingMode</literal> class as
hash keys. Suppose that you put the previous model in your root
model:</para>
<programlisting role="unspecified">root.put("RoundingMode", roundingModeEnums);</programlisting>
<para>From now on, you can use <literal>RoundingMode.UP</literal> as
an expression to reference the <literal>UP</literal> enum value in
your template.</para>
<para>You can even give the template authors complete freedom over
which enum classes they use by placing the enum models hash into
your template root model with</para>
<programlisting role="unspecified">root.put("enums", BeansWrapper.getDefaultInstance().getEnumModels());</programlisting>
<para>This object exposes any enum class if it's used as a hash with
class name as the key. You can then use expression like
<literal>${enums["java.math.RoundingMode"].UP}</literal> in your
template.</para>
<para>The exposed enum values can be used as scalars (they'll
delegate to their <literal>toString()</literal> method), and can be
used in equality and inequality comparisons as well.</para>
<para>Note that in above examples, we always use the default
<literal>BeansWrapper</literal> instance. This is a convenient
static wrapper instance that you can use in most cases. You are also
free to create your own <literal>BeansWrapper</literal> instances
and use them instead especially when you want to modify some of its
characteristics (like model caching, security level, or the null
model representation).</para>
</section>
</section>
<section xml:id="pgui_misc_logging">
<title>Logging</title>
<indexterm>
<primary>logging</primary>
</indexterm>
<para>FreeMarker integrates with the following logging packages: <link
xlink:href="http://www.slf4j.org/">SLF4J</link>, <link
xlink:href="http://commons.apache.org/logging/">Apache Commons
Logging</link>, <link
xlink:href="http://jakarta.apache.org/log4j">Log4J</link>, <link
xlink:href="http://jakarta.apache.org/avalon/logkit">Avalon
LogKit</link>, and <link
xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html"><literal>java.util.logging</literal></link>
(Java 1.4 and above). By default, FreeMarker will look for the
following logging packages in this order, and will automatically use
the first package it finds: <remark>[2.4 - un-remark this] SLF4J,
Apache Commons Logging, </remark>Log4J, Avalon,
<literal>java.util.logging</literal>. However, if you call the static
<literal>selectLoggerLibrary</literal> method on the
<literal>freemarker.log.Logger</literal> class with appropriate
parameter and <emphasis>before using any FreeMarker classes that log
messages</emphasis>, you can explicitly select a logger package, or
even disable the logging. See the API documentation for more
details.</para>
<note>
<para>Prior to FreeMarker 2.4, SLF4J and Apache Commons Logging
aren't searched automatically due to backward compatibility
constraints, so to use one of them you must do this:</para>
<programlisting role="unspecified">import freemarker.log.Logger;
...
// IMPORTANT: This should be executed before using other FreeMarker classes!
Logger.selectLoggerLibrary(Logger.LIBRARY_SLF4J); // or Logger.LIBRARY_COMMONS
...</programlisting>
<para>Doing this is recommended, because starting from 2.4 SLF4J
will be used by default if present, otherwise Apache Commons Logging
if present, otherwise Log4J if present, etc.</para>
</note>
<para>All log messages produced by FreeMarker are logged into the
logger hierarchy whose top-level logger is named
<literal>freemarker</literal>. Currently used loggers are:</para>
<informaltable border="1">
<thead>
<tr>
<th>Logger name</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>freemarker.beans</literal></td>
<td>Logs messages of the Beans wrapper module.</td>
</tr>
<tr>
<td><literal>freemarker.cache</literal></td>
<td>Logs messages related to template loading and caching.</td>
</tr>
<tr>
<td><literal>freemarker.runtime</literal></td>
<td>Logs template exceptions thrown during template
processing.</td>
</tr>
<tr>
<td><literal>freemarker.runtime.attempt</literal></td>
<td>Logs template exceptions thrown during template processing,
but caught by
<literal>attempt</literal>/<literal>recover</literal>
directives. Enable DEBUG severity to see the exceptions.</td>
</tr>
<tr>
<td><literal>freemarker.servlet</literal></td>
<td>Logs messages of the <literal>FreemarkerServlet</literal>
class.</td>
</tr>
<tr>
<td><literal>freemarker.jsp</literal></td>
<td>Logs messages of the FreeMarker JSP support.</td>
</tr>
</tbody>
</informaltable>
<para>You can call the static <literal>selectLoggerLibrary</literal>
method on the <literal>freemarker.log.Logger</literal> class and pass
it a string that will be used to prefix the above mentioned logger
names. This is useful if you want to have separate loggers on a
per-web-application basis (assuming the application uses its own local
<literal>freemarker.jar</literal>). Also, you can disable logging with
<literal>Logger.selectLoggerLibrary(Logger.LIBRARY_NONE)</literal>. In
any case, <literal>selectLoggerLibrary</literal> must be called early,
before FreeMarker could log anything, or else it will not have
(consistent) effect.</para>
</section>
<section xml:id="pgui_misc_servlet">
<title>Using FreeMarker with servlets</title>
<anchor xml:id="topic.servlet" />
<indexterm>
<primary>Servlet</primary>
</indexterm>
<indexterm>
<primary>HTTP</primary>
</indexterm>
<indexterm>
<primary>JSP</primary>
</indexterm>
<indexterm>
<primary>Model 2</primary>
</indexterm>
<indexterm>
<primary>Struts</primary>
</indexterm>
<indexterm>
<primary>Web application framework</primary>
</indexterm>
<para>In a fundamental sense, using FreeMarker in the web application
space is no different from anywhere else; FreeMarker writes its output
to a <literal>Writer</literal> that you pass to the
<literal>Template.process</literal> method, and it does not care if
that <literal>Writer</literal> prints to the console or to a file or
to the output stream of <literal>HttpServletResponse</literal>.
FreeMarker knows nothing about servlets and Web; it just merges Java
object with template files and generates text output from them. From
here, it is up to you how to build a Web application around
this.</para>
<para>But, probably you want to use FreeMarker with some already
existing Web application framework. Many frameworks rely on the
``Model 2'' architecture, where JSP pages handle presentation. If you
use such a framework (for example, <link
xlink:href="http://jakarta.apache.org/struts">Apache Struts</link>),
then read on. For other frameworks please refer to the documentation
of the framework.</para>
<section xml:id="pgui_misc_servlet_model2">
<title>Using FreeMarker for ``Model 2''</title>
<para>Many frameworks follow the strategy that the HTTP request is
dispatched to user-defined ``action'' classes that put data into
<literal>ServletContext</literal>, <literal>HttpSession</literal>
and <literal>HttpServletRequest</literal> objects as attributes, and
then the request is forwarded by the framework to a JSP page (the
view) that will generate the HTML page using the data sent with the
attributes. This is often referred as Model 2.</para>
<mediaobject>
<imageobject>
<imagedata fileref="figures/model2sketch.png"></imagedata>
</imageobject>
</mediaobject>
<para>With these frameworks you can simply use FTL files instead of
JSP files. But, since your servlet container (Web application
server), unlike with JSP files, does not know out-of-the-box what to
do with FTL files, a little extra configuring is needed for your Web
application:</para>
<orderedlist>
<listitem>
<para>Copy <literal>freemarker.jar</literal> (from the
<literal>lib</literal> directory of the FreeMarker distribution)
into the <literal>WEB-INF/lib</literal> directory of your Web
application.</para>
</listitem>
<listitem>
<para>Insert the following section to the
<literal>WEB-INF/web.xml</literal> file of your Web application
(and adjust it if required):</para>
</listitem>
</orderedlist>
<programlisting role="unspecified"><servlet>
<servlet-name>freemarker</servlet-name>
<servlet-class><emphasis>freemarker.ext.servlet.FreemarkerServlet</emphasis></servlet-class>
<!-- FreemarkerServlet settings: -->
<init-param>
<param-name>TemplatePath</param-name>
<param-value>/</param-value>
</init-param>
<init-param>
<param-name>NoCache</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>ContentType</param-name>
<param-value>text/html; charset=UTF-8</param-value> <!-- Forces UTF-8 output encoding! -->
</init-param>
<!-- FreeMarker settings: -->
<init-param>
<param-name>template_update_delay</param-name>
<param-value>0</param-value> <!-- 0 is for development only! Use higher value otherwise. -->
</init-param>
<init-param>
<param-name>default_encoding</param-name>
<param-value>ISO-8859-1</param-value> <!-- The encoding of the template files. -->
</init-param>
<init-param>
<param-name>number_format</param-name>
<param-value>0.##########</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>freemarker</servlet-name>
<url-pattern><emphasis>*.ftl</emphasis></url-pattern>
</servlet-mapping></programlisting>
<para>That's all. After this, you can use FTL files
(<literal>*.ftl</literal>) in the same manner as JSP
(<literal>*.jsp</literal>) files. (Of course you can choose another
extension besides <literal>ftl</literal>; it is just the
convention)</para>
<note>
<para>How does it work? Let's examine how JSP-s work. Many servlet
container handles JSP-s with a servlet that is mapped to the
<literal>*.jsp</literal> request URL pattern. That servlet will
receive all requests where the request URL ends with
<literal>.jsp</literal>, find the JSP file based on the request
URL, and internally compiles it to a <literal>Servlet</literal>,
and then call the generated servlet to generate the page. The
<literal>FreemarkerServlet</literal> mapped here to the
<literal>*.ftl</literal> URL pattern does the same, except that
FTL files are not compiled to <literal>Servlet</literal>-s, but to
<literal>Template</literal> objects, and then the
<literal>process</literal> method of <literal>Template</literal>
will be called to generate the page.</para>
</note>
<para><anchor xml:id="topic.servlet.scopeAttr" />For example,
instead of this JSP file (note that it heavily uses Struts tag-libs
to save designers from embedded Java monsters):</para>
<programlisting role="template"><%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>
<html>
<head><title>Acmee Products International</title>
<body>
<h1>Hello <bean:write name="user"/>!</h1>
<p>These are our latest offers:
<ul>
<logic:iterate name="latestProducts" id="prod">
<li><bean:write name="prod" property="name"/>
for <bean:write name="prod" property="price"/> Credits.
</logic:iterate>
</ul>
</body>
</html></programlisting>
<para>you can use this FTL file (use <literal>ftl</literal> file
extension instead of <literal>jsp</literal>):</para>
<programlisting role="template"><html>
<head><title>Acmee Products International</title>
<body>
<h1>Hello ${user}!</h1>
<p>These are our latest offers:
<ul>
<#list latestProducts as prod>
<li>${prod.name} for ${prod.price} Credits.
</#list>
</ul>
</body>
</html></programlisting>
<warning>
<para>In FreeMarker <literal><html:form
action="/query"><replaceable>...</replaceable></html:form></literal>
is just static text, so it is printed to the output as is, like
any other XML or HTML markup. JSP tags are just FreeMarker
directives, nothing special, so you <emphasis>use FreeMarker
syntax</emphasis> for calling them, not JSP syntax:
<literal><@html.form
action="/query"><replaceable>...</replaceable></@html.form></literal>.
Note that in the FreeMarker syntax you <emphasis>don't use
<literal>${<replaceable>...</replaceable>}</literal> in
parameters</emphasis> as in JSP, and you <emphasis>don't quote the
parameter values</emphasis>. So this is
<emphasis>WRONG</emphasis>:</para>
<programlisting role="template"><#-- WRONG: -->
<@my.jspTag color="${aVariable}" name="aStringLiteral"
width="100" height=${a+b} /></programlisting>
<para>and this is good:</para>
<programlisting role="template"><#-- Good: -->
<@my.jspTag color=aVariable name="aStringLiteral"
width=100 height=a+b /></programlisting>
</warning>
<para>In both templates, when you refer to <literal>user</literal>
and <literal>latestProduct</literal>, it will first try to find a
variable with that name that was created in the template (like
<literal>prod</literal>; if you master JSP: a page scope attribute).
If that fails, it will try to look up an attribute with that name in
the <literal>HttpServletRequest</literal>, and if it is not there
then in the <literal>HttpSession</literal>, and if it still doesn't
find it then in the <literal>ServletContext</literal>. In the case
of FTL this works because <literal>FreemarkerServlet</literal>
builds the data-model from the attributes of the mentioned 3
objects. That is, in this case the root hash is not a
<literal>java.util.Map</literal> (as it was in some example codes in
this manual), but
<literal>ServletContext</literal>+<literal>HttpSession</literal>+<literal>HttpServletRequest</literal>;
FreeMarker is pretty flexible about what the data-model is. So if
you want to put variable <literal>"name"</literal> into the
data-model, then you call
<literal>servletRequest.setAttribute("name", "Fred")</literal>; this
is the logic of Model 2, and FreeMarker adapts itself to it.</para>
<para><literal>FreemarkerServlet</literal> also puts 3 hashes into
the data-model, by which you can access the attributes of the 3
objects directly. The hash variables are:
<literal>Request</literal>, <literal>Session</literal>,
<literal>Application</literal> (corresponds to
<literal>ServletContext</literal>). It also exposes another hash
named <literal>RequestParameters</literal> that provides access to
the parameters of the HTTP request.</para>
<para><literal>FreemarkerServlet</literal> has various init-params.
It can be set up to load templates from an arbitrary directory, from
the classpath, or relative to the Web application directory. You can
set the charset used for templates. You can set up what object
wrapper do you want to use. Etc.</para>
<para><literal>FreemarkerServlet</literal> is easily tailored to
special needs through subclassing. Say, if you need to have
additional variables available in your data-model for all templates,
subclass the servlet and override the
<literal>preTemplateProcess()</literal> method to shove any
additional data you need into the model before the template gets
processed. Or subclass the servlet, and set these globally available
variables as <link linkend="pgui_config_sharedvariables">shared
variables</link> in the <literal>Configuration</literal>.</para>
<para>For more information please read the Java API documentation of
the class.</para>
</section>
<section xml:id="pgui_misc_servlet_include">
<title>Including content from other web application
resources</title>
<indexterm>
<primary>include</primary>
<secondary>servlet</secondary>
</indexterm>
<indexterm>
<primary>include</primary>
<secondary>JSP</secondary>
</indexterm>
<indexterm>
<primary>servlet</primary>
<secondary>include</secondary>
</indexterm>
<indexterm>
<primary>JSP</primary>
<secondary>include</secondary>
</indexterm>
<para>You can use the <literal><@include_page
path="..."/></literal> custom directive provided by the
<literal>FreemarkerServlet</literal> (since 2.3.15) to include the
contents of another web application resource into the output; this
is often useful to integrate output of JSP pages (living alongside
the FreeMarker templates in the same web server) into the FreeMarker
template output. Using:</para>
<programlisting role="template"><@include_page path="path/to/some.jsp"/></programlisting>
<para>is identical to using this tag in JSP:</para>
<programlisting role="template"><jsp:include page="path/to/some.jsp"></programlisting>
<note>
<para><literal><@include_page ...></literal> is not to be
confused with <literal><#include ...></literal>, as the last
is for including FreeMarker templates without involving the
Servlet container. An <literal><#include ...></literal>-ed
template shares the template processing state with the including
template, such as the data-model and the template-language
variables, while <literal><@include_page ...></literal>
starts an independent HTTP request processing.</para>
</note>
<note>
<para>Some Web Application Frameworks provide their own solution
for this, in which case you possibly should use that instead. Also
some Web Application Frameworks don't use
<literal>FreemarkerServlet</literal>, so
<literal>include_page</literal> is not available.</para>
</note>
<para>The path can be relative or absolute. Relative paths are
interpreted relative to the URL of the current HTTP request (one
that triggered the template processing), while absolute paths are
absolute in the current servlet context (current web application).
You can not include pages from outside the current web application.
Note that you can include any page, not just a JSP page; we just
used page with path ending in <literal>.jsp</literal> as an
illustration.</para>
<para>In addition to the <literal>path</literal> parameter, you can
also specify an optional parameter named
<literal>inherit_params</literal> with a boolean value (defaults to
true when not specified) that specifies whether the included page
will see the HTTP request parameters of the current request or
not.</para>
<para>Finally, you can specify an optional parameter named
<literal>params</literal> that specifies new request parameters that
the included page will see. In case inherited parameters are passed
too, the values of specified parameters will get prepended to the
values of inherited parameters of the same name. The value of
<literal>params</literal> must be a hash, with each value in it
being either a string, or a sequence of strings (if you need
multivalued parameters). Here's a full example:</para>
<programlisting role="template"><@include_page path="path/to/some.jsp" inherit_params=true params={"foo": "99", "bar": ["a", "b"]}/></programlisting>
<para>This will include the page
<literal>path/to/some.jsp</literal>, pass it all request parameters
of the current request, except for "foo" and "bar", which will be
set to "99" and multi-value of "a", "b", respectively. In case the
original request already had values for these parameters, the new
values will be prepended to the existing values. I.e. if "foo" had
values "111" and "123", then it will now have values "99", "111",
"123".</para>
<para><phrase role="forProgrammers">It is in fact possible to pass
non-string values for parameter values within
<literal>params</literal>. Such a value will be converted to a
suitable Java object first (i.e. a Number, a Boolean, a Date, etc.),
and then its Java <literal>toString()</literal> method will be used
to obtain the string value. It is better to not rely on this
mechanism, though, and instead explicitly ensure that parameter
values that aren't strings are converted to strings on the template
level where you have control over formatting using the
<literal>?string</literal> and <literal>?c</literal> built-ins.
</phrase></para>
</section>
<section>
<title>Using JSP custom tags in FTL</title>
<indexterm>
<primary>JSP</primary>
<secondary>taglib</secondary>
</indexterm>
<indexterm>
<primary>custom tags</primary>
</indexterm>
<indexterm>
<primary>taglib</primary>
</indexterm>
<para><literal>FreemarkerServlet</literal> puts a hash
<literal>JspTaglibs</literal> into the data-model, what you can use
to access JSP taglibs. The JSP custom tags will be accessible as
plain user-defined directives. For example, this is a JSP file that
uses some Struts tags:</para>
<programlisting role="template"><%@page contentType="text/html;charset=ISO-8859-2" language="java"%>
<%@taglib uri="/WEB-INF/struts-html.tld" prefix="html"%>
<%@taglib uri="/WEB-INF/struts-bean.tld" prefix="bean"%>
<html>
<body>
<h1><bean:message key="welcome.title"/></h1>
<html:errors/>
<html:form action="/query">
Keyword: <html:text property="keyword"/><br>
Exclude: <html:text property="exclude"/><br>
<html:submit value="Send"/>
</html:form>
</body>
</html></programlisting>
<para>And this is the (near) equivalent FTL:</para>
<programlisting role="template"><#assign html=JspTaglibs["/WEB-INF/struts-html.tld"]>
<#assign bean=JspTaglibs["/WEB-INF/struts-bean.tld"]>
<html>
<body>
<h1><@bean.message key="welcome.title"/></h1>
<@html.errors/>
<@html.form action="/query">
Keyword: <@html.text property="keyword"/><br>
Exclude: <@html.text property="exclude"/><br>
<@html.submit value="Send"/>
</@html.form>
</body>
</html></programlisting>
<para>Since JSP custom tags are written to operate in JSP
environment, they assume that variables (often referred as ``beans''
in JSP world) are stored in 4 scopes: page scope, request scope,
session scope and application scope. FTL has no such notation (the 4
scopes), but <literal>FreemarkerServlet</literal> provides emulated
JSP environment for the custom JSP tags, which maintains
correspondence between the ``beans'' of JSP scopes and FTL
variables. For the custom JSP tags, the request, session and
application scopes are exactly the same as with real JSP: the
attributes of the <literal>javax.servlet.ServletContext</literal>,
<literal>HttpSession</literal> and <literal>ServletRequest</literal>
objects. From the FTL side you see these 3 scopes together as the
data-model, as it was explained earlier. The page scope corresponds
to the FTL global variables (see the <link
linkend="ref.directive.global"><literal>global</literal>
directive</link>). That is, if you create a variable with the
<literal>global</literal> directive, it will be visible for the
custom tags as page scope variable through the emulated JSP
environment. Also, if a JSP-tag creates a new page scope variable,
the result will be the same as if you create a variable with the
<literal>global</literal> directive. Note that the variables in the
data-model are not visible as page-scope attributes for the JSP
tags, despite that they are globally visible, since the data-model
corresponds to the request, session and application scopes, not the
page-scope.</para>
<para>On JSP pages you quote all attribute values, it does not mater
if the type of the parameter is string or boolean or number. But
since custom tags are accessible in FTL templates as user-defined
FTL directives, you have to use the FTL syntax rules inside the
custom tags, not the JSP rules. So when you specify the value of an
``attribute'', then on the right side of the <literal>=</literal>
there is an <link linkend="dgui_template_exp">FTL expression</link>.
Thus, <emphasis>you must not quote boolean and numerical parameter
values</emphasis> (e.g. <literal><@tiles.insert
page="/layout.ftl" flush=true/></literal>), or they are
interpreted as string values, and this will cause a type mismatch
error when FreeMarker tries to pass the value to the custom tag that
expects non-string value. Also note, that naturally, you can use any
FTL expression as attribute value, such as variables, calculated
values, etc. (e.g. <literal><@tiles.insert page=layoutName
flush=foo && bar/></literal>).</para>
<para>FreeMarker does not rely on the JSP support of the servlet
container in which it is run when it uses JSP taglibs since it
implements its own lightweight JSP runtime environment. There is
only one small detail to pay attention to: to enable the FreeMarker
JSP runtime environment to dispatch events to JSP taglibs that
register event listeners in their TLD files, you should add this to
the <literal>WEB-INF/web.xml</literal> of your Web
application:</para>
<programlisting role="unspecified"><listener>
<listener-class>freemarker.ext.jsp.EventForwarding</listener-class>
</listener></programlisting>
<para>Note that you can use JSP taglibs with FreeMarker even if the
servlet container has no native JSP support, just make sure that the
<literal>javax.servlet.jsp.*</literal> packages for JSP 1.2 (or
later) are available to your Web application. If your servlet
container comes with JSP 1.1, then you have to obtain the following
six classes (for example you can extract them from the jar-s of
Tomcat 5.x or Tomcat 4.x), and copy them into your webapp's
<literal>WEB-INF/classes/<replaceable>...</replaceable></literal>
directory: <literal>javax.servlet.jsp.tagext.IterationTag</literal>,
<literal>javax.servlet.jsp.tagext.TryCatchFinally</literal>,
<literal>javax.servlet.ServletContextListener</literal>,
<literal>javax.servlet.ServletContextAttributeListener</literal>,
<literal>javax.servlet.http.HttpSessionAttributeListener</literal>,
<literal>javax.servlet.http.HttpSessionListener</literal>. But
beware, since containers that come with JSP 1.1 usually use earlier
Serlvet versions than 2.3, event listeners will not be supported,
and thus JSP 1.2 taglibs that register event listeners will not work
properly.</para>
<para>As of this writing, JSP features up to JSP 2.1 are
implemented, except the "tag files" feature of JSP 2 (i.e., custom
JSP tags <emphasis>implemented</emphasis> in JSP language). The tag
files had to be compiled to Java classes to be usable under
FreeMarker.</para>
</section>
<section>
<title>Embed FTL into JSP pages</title>
<indexterm>
<primary>JSP</primary>
<secondary>taglib</secondary>
</indexterm>
<para>There is a taglib that allows you to put FTL fragments into
JSP pages. The embedded FTL fragment can access the attributes
(Beans) of the 4 JSP scopes. You can find a working example and the
taglib in the FreeMarker distribution.</para>
</section>
</section>
<section xml:id="pgui_misc_secureenv">
<title>Configuring security policy for FreeMarker</title>
<indexterm>
<primary>security</primary>
</indexterm>
<para>When FreeMarker is used in a Java virtual machine with a
security manager installed, you have to grant it few permissions to
ensure it operates properly. Most notably, you need these entries to
your security policy file for
<literal>freemarker.jar</literal>:</para>
<programlisting role="unspecified">grant codeBase "file:/path/to/freemarker.jar"
{
permission java.util.PropertyPermission "file.encoding", "read";
permission java.util.PropertyPermission "freemarker.*", "read";
}</programlisting>
<para>Additionally, if you are loading templates from a directory, you
need to give FreeMarker permissions to read files from that directory
using the following permission:</para>
<programlisting role="unspecified">grant codeBase "file:/path/to/freemarker.jar"
{
...
permission java.io.FilePermission "/path/to/templates/-", "read";
}</programlisting>
<para>Finally, if you're just using the default template loading
mechanism which loads templates from the current directory, then
specify these permissions additionally: (note that the expression
<literal>${user.dir}</literal> will be evaluated at run time by the
policy interpreter, pretty much as if it were a FreeMarker
template)</para>
<programlisting role="unspecified">
grant codeBase "file:/path/to/freemarker.jar"
{
...
permission java.util.PropertyPermission "user.dir", "read";
permission java.io.FilePermission "${user.dir}/-", "read";
}</programlisting>
<para>Naturally, if you're running under Windows, use double backslash
instead of a single slash for separating directory components in
paths.</para>
</section>
<section xml:id="pgui_misc_xml_legacy">
<title>Legacy XML wrapper implementation</title>
<note>
<para><emphasis>The legacy XML wrapper is deprecated.</emphasis>
FreeMarker 2.3 has introduced support for a new XML processing
model. To support this, a new XML wrapper package was introduced,
<literal>freemarker.ext.dom</literal>. For new usage, we encourage
you to use that. It is documented in the part <xref
linkend="xgui" />.</para>
</note>
<para>The class <literal>freemarker.ext.xml.NodeListModel</literal>
provides a template model for wrapping XML documents represented as
node trees. Every node list can contain zero or more XML nodes
(documents, elements, texts, processing instructions, comments, entity
references, CDATA sections, etc.). The node list implements the
following template model interfaces with the following
semantics:</para>
<section>
<title>TemplateScalarModel</title>
<para>When used as a scalar, the node list will render the XML
fragment that represents its contained nodes. This makes it handy
for use in XML-to-XML transforming templates.</para>
</section>
<section>
<title>TemplateCollectionModel</title>
<para>When used as a collection with <literal>list</literal>
directive, it will simply enumerate its nodes. Every node will be
returned as a new node list consisting of a single node.</para>
</section>
<section>
<title>TemplateSequenceModel</title>
<para>When used as a sequence, it will return the i-th node as a new
node list consisting of the single requested node. I.e. to return
the 3rd <literal><chapter></literal> element of the
<literal><book></literal> element, you'd use the following
(note indexes are zero-based):</para>
<programlisting role="template"><#assign 3rdChapter = xmldoc.book.chapter[2]></programlisting>
</section>
<section>
<title>TemplateHashModel</title>
<para>When used as a hash, it is basically used to traverse
children. That is, if you have a node list named
<literal>book</literal> that wraps an element node with several
chapters, then the <literal>book.chapter</literal> will yield a node
list with all chapter elements of that book element. The at sign is
used to refer to attributes: <literal>book.@title</literal> yields a
node list with a single attribute node, that is the title attribute
of the book element.</para>
<para>It is important to realize the consequence that, for example,
if <literal>book</literal> has no <literal>chapter</literal>-s then
<literal>book.chapter</literal> is an empty sequence, so
<literal>xmldoc.book.chapter??</literal> will
<emphasis>not</emphasis> be <literal>false</literal>, it will be
always <literal>true</literal>! Similarly,
<literal>xmldoc.book.somethingTotallyNonsense??</literal> will not
be <literal>false</literal> either. To check if there was no
children found, use <literal>xmldoc.book.chapter?size ==
0</literal>.</para>
<para>The hash defines several "magic keys" as well. All these keys
start with an underscore. The most notable is the
<literal>_text</literal> key which retrieves the text of the node:
<literal>${book.@title._text}</literal> will render the value of the
attribute into the template. Similarly, <literal>_name</literal>
will retrieve the name of the element or attribute.
<literal>*</literal> or <literal>_allChildren</literal> returns all
direct children elements of all elements in the node list, while
<literal>@*</literal> or <literal>_allAttributes</literal> returns
all attributes of the elements in the node list. There are many more
such keys; here's a detailed summary of all the hash keys:</para>
<informaltable border="1">
<thead>
<tr>
<th>Key name</th>
<th>Evaluates to</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>*</literal> or <literal>_children</literal></td>
<td>all direct element children of current nodes
(non-recursive). Applicable to element and document
nodes.</td>
</tr>
<tr>
<td><literal>@*</literal> or
<literal>_attributes</literal></td>
<td>all attributes of current nodes. Applicable to elements
only.</td>
</tr>
<tr>
<td><literal>@<replaceable>attributeName</replaceable></literal></td>
<td>named attributes of current nodes. Applicable to elements,
doctypes and processing instructions. On doctypes it supports
attributes <literal>publicId</literal>,
<literal>systemId</literal> and
<literal>elementName</literal>. On processing instructions, it
supports attributes <literal>target</literal> and
<literal>data</literal>, as well as any other attribute name
specified in data as <literal>name="value"</literal> pair. The
attribute nodes for doctype and processing instruction are
synthetic, and as such have no parent. Note, however that
<literal>@*</literal> does NOT operate on doctypes or
processing instructions.</td>
</tr>
<tr>
<td><literal>_ancestor</literal></td>
<td>all ancestors up to root element (recursive) of current
nodes. Applicable to same node types as
<literal>_parent</literal>.</td>
</tr>
<tr>
<td><literal>_ancestorOrSelf</literal></td>
<td>all ancestors of current nodes plus current nodes.
Applicable to same node types as
<literal>_parent</literal>.</td>
</tr>
<tr>
<td><literal>_cname</literal></td>
<td>the canonical names of current nodes (namespace URI +
local name), one string per node (non-recursive). Applicable
to elements and attributes</td>
</tr>
<tr>
<td><literal>_content</literal></td>
<td>the complete content of current nodes, including children
elements, text, entity references, and processing instructions
(non-recursive). Applicable to elements and documents.</td>
</tr>
<tr>
<td><literal>_descendant</literal></td>
<td>all recursive descendant element children of current
nodes. Applicable to document and element nodes.</td>
</tr>
<tr>
<td><literal>_descendantOrSelf</literal></td>
<td>all recursive descendant element children of current nodes
plus current nodes. Applicable to document and element
nodes.</td>
</tr>
<tr>
<td><literal>_document</literal></td>
<td>all documents the current nodes belong to. Applicable to
all nodes except text.</td>
</tr>
<tr>
<td><literal>_doctype</literal></td>
<td>doctypes of the current nodes. Applicable to document
nodes only.</td>
</tr>
<tr>
<td><literal>_filterType</literal></td>
<td>is a filter-by-type template method model. When called, it
will yield a node list that contains only those current nodes
whose type matches one of types passed as argument. You should
pass arbitrary number of strings to this method containing the
names of types to keep. Valid type names are: "attribute",
"cdata", "comment", "document", "documentType", "element",
"entity", "entityReference", "processingInstruction",
"text".</td>
</tr>
<tr>
<td><literal>_name</literal></td>
<td>the names of current nodes, one string per node
(non-recursive). Applicable to elements and attributes
(returns their local names), entities, processing instructions
(returns its target), doctypes (returns its public ID)</td>
</tr>
<tr>
<td><literal>_nsprefix</literal></td>
<td>the namespace prefixes of current nodes, one string per
node (non-recursive). Applicable to elements and
attributes</td>
</tr>
<tr>
<td><literal>_nsuri</literal></td>
<td>the namespace URIs of current nodes, one string per node
(non-recursive). Applicable to elements and attributes</td>
</tr>
<tr>
<td><literal>_parent</literal></td>
<td>parent elements of current nodes. Applicable to element,
attribute, comment, entity, processing instruction.</td>
</tr>
<tr>
<td><literal>_qname</literal></td>
<td>the qualified names of current nodes in
<literal>[namespacePrefix:]localName</literal> form, one
string per node (non-recursive). Applicable to elements and
attributes</td>
</tr>
<tr>
<td><literal>_registerNamespace(prefix, uri)</literal></td>
<td>register a XML namespace with the specified prefix and URI
for the current node list and all node lists that are derived
from the current node list. After registering, you can use the
<literal>nodelist["prefix:localname"]</literal> or
<literal>nodelist["@prefix:localname"]</literal> syntaxes to
reach elements and attributes whose names are
namespace-scoped. Note that the namespace prefix need not
match the actual prefix used by the XML document itself since
namespaces are compared solely by their URI.</td>
</tr>
<tr>
<td><literal>_text</literal></td>
<td>the text of current nodes, one string per node
(non-recursive). Applicable to elements, attributes, comments,
processing instructions (returns its data) and CDATA sections.
The reserved XML characters ('<' and '&') are not
escaped.</td>
</tr>
<tr>
<td><literal>_type</literal></td>
<td>Returns a node list containing one string per node
describing the type of the node. Possible node type names are:
"attribute", "cdata", "comment", "document", "documentType",
"element", "entity", "entityReference",
"processingInstruction", "text". If the type of the node is
unknown, returns "unknown".</td>
</tr>
<tr>
<td><literal>_unique</literal></td>
<td>a copy of the current nodes that keeps only the first
occurrence of every node, eliminating duplicates. Duplicates
can occur in the node list by applying uptree-traversals
<literal>_parent</literal>, <literal>_ancestor</literal>,
<literal>_ancestorOrSelf</literal>, and
<literal>_document</literal>. I.e.
<literal>foo._children._parent</literal> will return a node
list that has duplicates of nodes in foo - each node will have
the number of occurrences equal to the number of its children.
In these cases, use
<literal>foo._children._parent._unique</literal> to eliminate
duplicates. Applicable to all node types.</td>
</tr>
<tr>
<td>any other key</td>
<td>element children of current nodes with name matching the
key. This allows for convenience child traversal in
<literal>book.chapter.title</literal> style syntax. Note that
<literal>nodeset.childname</literal> is technically equivalent
to <literal>nodeset("childname")</literal>, but is both
shorter to write and evaluates faster. Applicable to document
and element nodes.</td>
</tr>
</tbody>
</informaltable>
</section>
<section>
<title>TemplateMethodModel</title>
<para>When used as a method model, it returns a node list that is
the result of evaluating an XPath expression on the current contents
of the node list. For this feature to work, you must have the
<literal>Jaxen</literal> library in your classpath. For
example:</para>
<programlisting role="template"><#assign firstChapter=xmldoc("//chapter[first()]")></programlisting>
</section>
<section>
<title>Namespace handling</title>
<para>For purposes of traversal of children elements that have
namespace-scoped names, you can register namespace prefixes with the
node list. You can do it either in Java, calling the</para>
<programlisting role="unspecified">public void registerNamespace(String prefix, String uri);</programlisting>
<para>method, or inside a template using the</para>
<programlisting role="template">${<replaceable>nodelist</replaceable>._registerNamespace(<replaceable>prefix</replaceable>, <replaceable>uri</replaceable>)}</programlisting>
<para>syntax. From there on, you can refer to children elements in
the namespace denoted by the particular URI through the
syntax</para>
<programlisting role="metaTemplate"><literal><replaceable>nodelist</replaceable>["<replaceable>prefix</replaceable>:<replaceable>localName</replaceable>"]</literal></programlisting>
<para>and</para>
<programlisting role="metaTemplate"><literal><replaceable>nodelist</replaceable>["@<replaceable>prefix</replaceable>:<replaceable>localName</replaceable>"]</literal></programlisting>
<para>as well as use these namespace prefixes in XPath expressions.
Namespaces registered with a node list are propagated to all node
lists that are derived from the original node list. Note also that
namespaces are matched by their URI only, so you can safely use a
prefix for a namespace inside your template that differs from the
prefix in the actual XML document - a prefix is just a local alias
for the URI both in the template and in the XML document.</para>
</section>
</section>
<section xml:id="pgui_misc_ant">
<title>Using FreeMarker with Ant</title>
<indexterm>
<primary>ant task</primary>
</indexterm>
<para>There are two ``FreeMarker Ant tasks'' that we know
about:</para>
<itemizedlist>
<listitem>
<para><literal>FreemarkerXmlTask</literal>: It comes with the
FreeMarker distribution, packed into the
<literal>freemarker.jar</literal>. This is a lightweight,
easy-to-use Ant task for transforming XML documents with
FreeMarker templates. Its approach is that the source files (input
files) are XML files, which are rendered to corresponding output
files, by a single template. That is, for each XML file, the
template will be executed (with the XML document in the
data-model), and the template output will be written into a file
of similar name than the name of the XML file. Thus, the template
file plays a similar role as an XSLT style sheet, but it is FTL,
not XSLT.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>command-line</primary>
</indexterm> FMPP: It's a more heavyweight, less XML centric,
third party Ant task (and standalone command-line tool). Its
primary approach is that the source files (input files) are
template files that generate the corresponding output files
themselves, but it also supports the approach of
<literal>FreemarkerXmlTask</literal> for the source files that are
XML-s. Also, it has extra features over the
<literal>FreemarkerXmlTask</literal>. What's its drawback then? As
it is more complex and more generalized, it's harder to learn and
use it.</para>
</listitem>
</itemizedlist>
<para>This section introduces the
<literal>FreemarkerXmlTask</literal>. For more information about FMPP
visit its homepage: <link
xlink:href="http://fmpp.sourceforge.net/">http://fmpp.sourceforge.net/</link>.</para>
<para>In order to use the <literal>FreemarkerXmlTask</literal>, you
must first define the
<literal>freemarker.ext.ant.FreemarkerXmlTask</literal> inside your
Ant buildfile, then call the task. Suppose you want to transform
several XML documents to HTML using the hypothetical "xml2html.ftl"
template, with XML documents being located in the directory "xml" and
HTML documents generated into directory "html". You would write
something like:</para>
<programlisting role="unspecified"><taskdef name="freemarker" classname="freemarker.ext.ant.FreemarkerXmlTask">
<classpath>
<pathelement location="freemarker.jar" />
</classpath>
</taskdef>
<mkdir dir="html" />
<freemarker basedir="xml" destdir="html" includes="**/*.xml" template="xml2html.ftl" /></programlisting>
<para>The task would invoke the template for every XML document. Every
document would be parsed into a DOM tree, then wrapped as a FreeMarker
node variable. When template processing begins, the special variable,
<literal>.node</literal>, is set to the root node of the XML
document.</para>
<para>Note that if you are using the legacy (FreeMarker 2.2.x and
earlier) XML adapter implementation, that still works, and the root of
the XML tree is placed in the data-model as the variable
<literal>document</literal>. That contains an instance of the legacy
<literal>freemarker.ext.xml.NodeListModel</literal> class.</para>
<para>Note that all properties defined by the build file would be made
available as a hash model named "properties". Several other models are
made available; for detailed description of what variables are made
available to templates as well as what other attributes can the task
accept, see the JavaDoc for
<literal>freemarker.ext.ant.FreemarkerXmlTask</literal>.</para>
</section>
<section xml:id="pgui_misc_jythonwrapper">
<title>Jython wrapper</title>
<indexterm>
<primary>wrapping</primary>
<secondary>jython</secondary>
</indexterm>
<indexterm>
<primary>jython</primary>
<secondary>wrapping</secondary>
</indexterm>
<para>The <literal>freemarker.ext.jython</literal> package consists of
models that enable any Jython object to be used as a
<literal>TemplateModel</literal>. In the very basic case, you only
need to call the</para>
<programlisting role="unspecified">public TemplateModel wrap(Object obj);</programlisting>
<para>method of the
<literal>freemarker.ext.jython.JythonWrapper</literal> class. This
method will wrap the passed object into an appropriate
<literal>TemplateModel</literal>. Below is a summary of the properties
of returned model wrappers. Let's assume that the model that resulted
from the <literal>JythonWrapper</literal> call on object
<literal>obj</literal> is named <literal>model</literal> in the
template model root for the sake of the following discussion.</para>
<section>
<title>TemplateHashModel functionality</title>
<para><literal>PyDictionary</literal> and
<literal>PyStringMap</literal> will be wrapped into a hash model.
Key lookups are mapped to the <literal>__finditem__</literal>
method; if an item is not found, a model for <literal>None</literal>
is returned.</para>
</section>
<section>
<title>TemplateScalarModel functionality</title>
<para>Every python object will implement
<literal>TemplateScalarModel</literal> whose
<literal>getAsString()</literal> method simply delegates to
<literal>toString()</literal>.</para>
</section>
<section>
<title>TemplateBooleanModel functionality</title>
<para>Every python object will implement
<literal>TemplateBooleanModel</literal> whose
<literal>getAsBoolean()</literal> method simply delegates to
<literal>__nonzero__()</literal> in accordance with Python semantics
of true/false.</para>
</section>
<section>
<title>TemplateNumberModel functionality</title>
<para>Model wrappers for <literal>PyInteger</literal>,
<literal>PyLong</literal>, and <literal>PyFloat</literal> objects
implement <literal>TemplateNumberModel</literal> whose
<literal>getAsNumber()</literal> method returns
<literal>__tojava__(java.lang.Number.class)</literal>.</para>
</section>
<section>
<title>TemplateSequenceModel functionality</title>
<para>Model wrappers for all classes that extend
<literal>PySequence</literal> will implement
<literal>TemplateSequenceModel</literal> and thus their elements
will be accessible by index using the <literal>model[i]</literal>
syntax, which will delegate to <literal>__finditem__(i)</literal>.
You can also query the length of the array or the size of the list
using the <literal>model?size</literal> built-in, which will
delegate to <literal>__len__()</literal>.</para>
</section>
</section>
</chapter>
</part>
<part xml:id="xgui">
<title>XML Processing Guide</title>
<preface xml:id="xgui_preface">
<title>Preface</title>
<para>Although FreeMarker was originally designed as a web page template
engine, as of version 2.3 it also targets another application domain:
transforming XML into arbitrary textual output (e.g. HTML files). Thus,
in many cases, FreeMarker is an XSLT alternative.</para>
<para>Technically, there is nothing special in transforming XML
documents. It's just like when you do anything else with FreeMarker: you
drop the XML document into the data-model (and possibly other
variables), and then you merge the data-model with the FTL template(s)
that generate the output text. The extra features introduced for better
XML processing are the node FTL variable type (symbolizes a node in
generic tree structures, usable not only for XML) and the built-ins and
directives dealing with them, and the XML wrapper you get out-of-the-box
that exposes XML documents as FTL variables for the templates.</para>
<para>What's the difference between using FreeMarker or XSLT? The FTL
language has the usual imperative/procedural logic. On the other hand,
XSLT is a language with declarative style, designed by "too clever"
people, so it's not easy to adopt its logic, nor to use it in many
cases. Also its syntax is terribly verbose. However, XSLT's
"apply-templates" method can be very handy when you process XML
documents, thus FreeMarker supports something similar called the
``visitor pattern''. So in many applications, it is much easier to write
FTL stylesheets than XSLT style-sheets. Another fundamental difference
is that FTL "transforms" the node tree to text, while XSLT transforms
the tree to another tree. So you cannot always use FreeMarker where you
can use XSLT.</para>
</preface>
<chapter xml:id="xgui_expose">
<title>Exposing XML documents</title>
<indexterm>
<primary>XML</primary>
<secondary>exposing</secondary>
</indexterm>
<section xml:id="xgui_expose_dom">
<title>The DOM tree</title>
<para>We will use this XML document for the examples:</para>
<anchor xml:id="misc.example.bookXml" />
<programlisting role="unspecified"><book>
<title>Test Book</title>
<chapter>
<title>Ch1</title>
<para>p1.1</para>
<para>p1.2</para>
<para>p1.3</para>
</chapter>
<chapter>
<title>Ch2</title>
<para>p2.1</para>
<para>p2.2</para>
</chapter>
</book></programlisting>
<para>W3C DOM models an XML document as a tree of nodes. The node tree
of the above XML can be visualized as:</para>
<programlisting role="unspecified">document
|
+- element book
|
+- text "\n "
|
+- element title
| |
| +- text "Test Book"
|
+- text "\n "
|
+- element chapter
| |
| +- text "\n "
| |
| +- element title
| | |
| | +- text "Ch1"
| |
| +- text "\n "
| |
| +- element para
| | |
| | +- text "p1.1"
| |
| +- text "\n "
| |
| +- element para
| | |
| | +- text "p1.2"
| |
| +- text "\n "
| |
| +- element para
| |
| +- text "p1.3"
|
+- element
|
+- text "\n "
|
+- element title
| |
| +- text "Ch2"
|
+- text "\n "
|
+- element para
| |
| +- text "p2.1"
|
+- text "\n "
|
+- element para
|
+- text "p2.2"</programlisting>
<para>Note that the disturbing <literal>"\n "</literal>-s are the
line-breaks (indicated here with <literal>\n</literal>, an escape
sequence used in FTL string literals) and the indentation spaces
between the tags.</para>
<para>Notes on the DOM related terminology:</para>
<itemizedlist>
<listitem>
<para>The topmost node of a tree is called the <emphasis
role="term">root</emphasis>. In the case of XML documents, it is
always the ``document'' node, and not the top-most element
(<literal>book</literal> in this example).</para>
</listitem>
<listitem>
<para>We say that node B is the <emphasis
role="term">child</emphasis> of node A, if B is the
<emphasis>immediate</emphasis> descendant of A. For example, the
two <literal>chapter</literal> element nodes are the children of
the <literal>book</literal> element node, but the
<literal>para</literal> element nodes are not.</para>
</listitem>
<listitem>
<para>We say that node A is the <emphasis
role="term">parent</emphasis> of node B, if A is the
<emphasis>immediate</emphasis> ascendant of node B, that is, if B
is the children of A. For example, the <literal>book</literal>
element node is the parent of the two <literal>chapter</literal>
element nodes, but it is not the parent of the
<literal>para</literal> element nodes.</para>
</listitem>
<listitem>
<para>There are several kind of components that can occur in XML
documents, such as elements, text, comments, processing
instructions, etc. All such components are nodes in the DOM tree,
so there are element nodes, text nodes, comment nodes, etc. In
principle, the attributes of elements are also nodes in the tree
-- they are the children of the element --, but still, usually we
(and other XML related technologies) exclude them of element
children. So basically they don't count as children nodes.</para>
</listitem>
</itemizedlist>
<para>The programmer drops the document node of the DOM tree into the
FreeMarker data-model, and then the template author can walk the DOM
tree using that variable as the starting-point.</para>
<para>The DOM nodes in FTL correspond to <emphasis role="term">node
variables</emphasis>. This is a variable type, similarly to type
string, number, hash, etc. Node variable type makes it possible for
FreeMarker to get the parent node and the child nodes of a node. This
is technically required to allow the template author to navigate
between the nodes, say, to use the <link
linkend="ref_builtins_node">node built-ins</link> or the <link
linkend="ref.directive.visit"><literal>visit</literal></link> and
<link
linkend="ref.directive.recurse"><literal>recurse</literal></link>
directives; we will show the usage of these in the further
chapters.</para>
</section>
<section xml:id="xgui_expose_put">
<title>Putting the XML into the data-model</title>
<note>
<para>This section is for programmers.</para>
</note>
<para>It's easy to create a simple program to try the examples. Just
replace the ``Create a data-model'' part of <link
linkend="pgui_quickstart_all">the example of Programmer's Guide
Quickstart</link> with this:</para>
<programlisting role="unspecified">/* Create a data-model */
Map root = new HashMap();
root.put(
"doc",
freemarker.ext.dom.NodeModel.parse(new File("<replaceable>the/path/of/the.xml</replaceable>")));</programlisting>
<para>and then you have a program that outputs the result of the XML
transformation to the standard output (usually the terminal
screen).</para>
<para>Notes:</para>
<itemizedlist>
<listitem>
<para>The <literal>parse</literal> method removes comment and
processing instruction nodes by default. See the API for more
details.</para>
</listitem>
<listitem>
<para><literal>NodeModel</literal> also allows you to wrap
<literal>org.w3c.dom.Node</literal>-s directly. You may want to
clean up the DOM tree first with the static utility methods, such
as <literal>NodeModel.simplify</literal> or your own custom
cleanup routines.</para>
</listitem>
</itemizedlist>
<para>Note that there are tools available that you can use to generate
files from XML documents, so you don't have to write your own for this
common task. <link linkend="pgui_misc_ant">See here...</link></para>
</section>
</chapter>
<chapter xml:id="xgui_imperative">
<title>Imperative XML processing</title>
<indexterm>
<primary>XML</primary>
<secondary>imperative processing</secondary>
</indexterm>
<section xml:id="xgui_imperative_learn">
<title>Learning by example</title>
<note>
<para>This section uses the DOM tree and the variable made in the
<link linkend="xgui_expose">previous chapter</link>.</para>
</note>
<para>Assume that the programmer has put the XML document into the
data-model as variable <literal>doc</literal>. This variable
corresponds to the root of the <link linkend="xgui_expose_dom">DOM
tree</link>, the ``document''. The actual variable structure behind
<literal>doc</literal> is wily enough, and only roughly resembles the
DOM tree. So instead of getting lost in the details, let's see how to
use it by example.</para>
<section>
<title>Accessing elements by name</title>
<para>This FTL prints the title of the book:</para>
<programlisting role="template"><h1>${doc.book.title}</h1></programlisting>
<para>The output will be:</para>
<programlisting role="output"><h1>Test Book</h1></programlisting>
<para>As you see, both <literal>doc</literal> and
<literal>book</literal> can be used as hashes; you get their child
nodes as subvariables. Basically, you describe the path by which you
reach the target (element <literal>title</literal>) in the DOM tree.
You may notice that there was some swindle above: with
<literal>${doc.book.title}</literal>, it seems that we instruct
FreeMarker to print the <literal>title</literal> element itself, but
we should print its child text node (check the <link
linkend="xgui_expose_dom">DOM tree</link>). It still works, because
elements are not only hash variables, but string variables as well.
The scalar value of an element node is the string resulting from the
concatenation of all its text child nodes. However, trying to use an
element as scalar will cause error if the element has child
elements. For example <literal>${doc.book}</literal> would stop with
error.</para>
<para>This FTL prints the titles of the two chapters:</para>
<programlisting role="template"><h2>${doc.book.chapter[0].title}</h2>
<h2>${doc.book.chapter[1].title}</h2></programlisting>
<para>Here, as <literal>book</literal> has 2
<literal>chapter</literal> element children,
<literal>doc.book.chapter</literal> is a sequence that stores the
two element nodes. Thus, we can generalize the above FTL, so it
works with any number of chapters:</para>
<programlisting role="template"><#list doc.book.chapter as ch>
<h2>${ch.title}</h2>
</#list></programlisting>
<para>But what's if there is only one chapter? Actually, when you
access an element as hash subvariable, it is
<emphasis>always</emphasis> a sequence as well (not only hash and
string), but if the sequence contains exactly 1 item, then the
variable also acts as that item itself. So, returning to the first
example, this would print the book title as well:</para>
<programlisting role="template"><h1>${doc.book[0].title[0]}</h1></programlisting>
<para>But you know that there is exactly 1 <literal>book</literal>
element, and that a book has exactly 1 title, so you can omit the
<literal>[0]</literal>-s.
<literal>${doc.book.chapter.title}</literal> would work too, if the
book happen to have only 1 <literal>chapter</literal>-s (otherwise
it is ambiguous: how is it to know if the <literal>title</literal>
of which <literal>chapter</literal> you want? So it stops with an
error.). But since a book can have multiple chapters, you don't use
this form. If the element <literal>book</literal> has no
<literal>chapter</literal> child, then
<literal>doc.book.chapter</literal> will be a 0 length sequence, so
the FTL with <literal><#list ...></literal> will still
work.</para>
<para>It is important to realize the consequence that, for example,
if <literal>book</literal> has no <literal>chapter</literal>-s then
<literal>book.chapter</literal> is an empty sequence, so
<literal>doc.book.chapter??</literal> will <emphasis>not</emphasis>
be <literal>false</literal>, it will be always
<literal>true</literal>! Similarly,
<literal>doc.book.somethingTotallyNonsense??</literal> will not be
<literal>false</literal> either. To check if there was no children
found, use <literal>doc.book.chapter[0]??</literal> (or
<literal>doc.book.chapter?size == 0</literal>). Of course you can
use similarly all the <link
linkend="dgui_template_exp_missing">missing value handler
operators</link> (e.g.
<literal>doc.book.author[0]!"Anonymous"</literal>), just don't
forget that <literal>[0]</literal>.</para>
<note>
<para>The rule with sequences of size 1 is a convenience feature
of the XML wrapper (implemented via multi-type FTL variables). It
will not work with other sequences in general.</para>
</note>
<para>Now we finish the example by printing all the
<literal>para</literal>-s of each chapter:</para>
<programlisting role="template"><h1>${doc.book.title}</h1>
<#list doc.book.chapter as ch>
<h2>${ch.title}</h2>
<#list ch.para as p>
<p>${p}
</#list>
</#list></programlisting>
<para>this will print:</para>
<programlisting role="output"><h1>Test</h1>
<h2>Ch1</h2>
<p>p1.1
<p>p1.2
<p>p1.3
<h2>Ch2</h2>
<p>p2.1
<p>p2.2</programlisting>
<para>The above FTL could be written more nicely as:</para>
<programlisting role="template"><#assign book = doc.book>
<h1>${book.title}</h1>
<#list book.chapter as ch>
<h2>${ch.title}</h2>
<#list ch.para as p>
<p>${p}
</#list>
</#list></programlisting>
<para>Finally, a ``generalized`` usage of the child selector
mechanism: this template lists all <literal>para</literal>-s of the
example XML document:</para>
<programlisting role="template"><#list doc.book.chapter.para as p>
<p>${p}
</#list></programlisting>
<para>The output will be:</para>
<programlisting role="output"> <p>p1.1
<p>p1.2
<p>p1.3
<p>p2.1
<p>p2.2
</programlisting>
<para>This example shows that hash subvariables select the children
of a sequence of notes (just in the earlier examples that sequence
happened to be of size 1). In this concrete case, subvariable
<literal>chapter</literal> returns a sequence of size 2 (since there
are two <literal>chapter</literal>-s), and then subvariable
<literal>para</literal> selects the <literal>para</literal> child
nodes of all nodes in that sequence.</para>
<para>A negative consequence of this mechanism is that things like
<literal>doc.somethingNonsense.otherNonsesne.totalNonsense</literal>
will just evaluate to an empty sequence, and you don't get any error
messages.</para>
</section>
<section>
<title>Accessing attributes</title>
<para>This XML is the same as the original, except that it uses
attributes for the titles, instead of elements:</para>
<programlisting role="unspecified"><!-- THIS XML IS USED FOR THE "Accessing attributes" CHAPTER ONLY! -->
<!-- Outside this chapter examples use the XML from earlier. -->
<book title="Test">
<chapter title="Ch1">
<para>p1.1</para>
<para>p1.2</para>
<para>p1.3</para>
</chapter>
<chapter title="Ch2">
<para>p2.1</para>
<para>p2.2</para>
</chapter>
</book></programlisting>
<para>The attributes of an element can be accessed in the same way
as the child elements of the element, except that you put an at-sign
(@) before the name of the attribute:</para>
<programlisting role="template"><#assign book = doc.book>
<h1>${book.@title}</h1>
<#list book.chapter as ch>
<h2>${ch.@title}</h2>
<#list ch.para as p>
<p>${p}
</#list>
</#list></programlisting>
<para>This will print exactly the same as the previous
example.</para>
<para>Getting attributes follows the same logic as getting child
elements, so the result of <literal>ch.@title</literal> above is a
sequence of size 1. If there were no <literal>title</literal>
attribute, then the result would be a sequence of size 0. So be
ware, using existence built-ins is tricky here too: if you are
curious if <literal>foo</literal> has attribute
<literal>bar</literal> then you have to write
<literal>foo.@bar[0]??</literal>. (<literal>foo.@bar??</literal> is
wrong, because it always returns <literal>true</literal>.)
Similarly, if you want a default value for the
<literal>bar</literal> attribute, then you have to write
<literal>foo.@bar[0]!"theDefaultValue"</literal>.</para>
<para>As with child elements, you can select the attributes of
multiple nodes. For example, this template prints the titles of all
chapters:</para>
<programlisting role="template"><#list doc.book.chapter.@title as t>
${t}
</#list></programlisting>
</section>
<section>
<title>Exploring the tree</title>
<para>This FTL will enumerate all child nodes of the book
element:</para>
<programlisting role="template"><#list doc.book?children as c>
- ${c?node_type} <#if c?node_type = 'element'>${c?node_name}</#if>
</#list></programlisting>
<para>this will print:</para>
<programlisting role="output">- text
- element title
- text
- element chapter
- text
- element chapter
- text</programlisting>
<para>The meaning of <literal>?node_type</literal> is probably clear
without explanation. There are several node types that can occur in
a DOM tree, such as <literal>"element"</literal>,
<literal>"text"</literal>, <literal>"comment"</literal>,
<literal>"pi"</literal>, ...etc.</para>
<para>The <literal>?node_name</literal> returns the name of element
for element nodes. For other node types, it also returns something,
but that's mainly useful for declarative XML processing, which will
be discussed in a <link linkend="xgui_declarative">later
chapter</link>.</para>
<para>If the book element had attributes, they would
<emphasis>not</emphasis> appear in the above list, for practical
reasons. But you can get a list that contains all attributes of the
element, with subvariable <literal>@@</literal> of the element
variable. If you modify the first line of the XML to this:</para>
<programlisting role="unspecified"><book foo="Foo" bar="Bar" baaz="Baaz"></programlisting>
<para>and run this FTL:</para>
<programlisting role="template"><#list doc.book.@@ as attr>
- ${attr?node_name} = ${attr}
</#list></programlisting>
<para>then you get this output (or something similar):</para>
<programlisting role="output">- baaz = Baaz
- bar = Bar
- foo = Foo</programlisting>
<para>Returning to the listing of children, there is a convenience
subvariable to list only the element children of an element:</para>
<programlisting role="template"><#list doc.book.* as c>
- ${c?node_name}
</#list></programlisting>
<para>This will print:</para>
<programlisting role="output">- title
- chapter
- chapter</programlisting>
<para>You get the parent of an element with the
<literal>parent</literal> built-in:</para>
<programlisting role="template"><#assign e = doc.book.chapter[0].para[0]>
<#-- Now e is the first para of the first chapter -->
${e?node_name}
${e?parent?node_name}
${e?parent?parent?node_name}
${e?parent?parent?parent?node_name}</programlisting>
<para>This will print:</para>
<programlisting role="output">para
chapter
book
@document</programlisting>
<para>In the last line you have reached the root of the DOM tree,
the document node. It's not an element, and this is why it has that
strange name; don't deal with it now. Obviously, the document node
has no parent.</para>
<para>You can quickly go back to the document node using the
<literal>root</literal> built-in:</para>
<programlisting role="template"><#assign e = doc.book.chapter[0].para[0]>
${e?root?node_name}
${e?root.book.title}</programlisting>
<para>This will print:</para>
<programlisting role="output">@document
Test Book</programlisting>
<para>For the complete list of built-ins you can use to navigate in
the DOM tree, read the <link linkend="ref_builtins_node">reference
of node built-ins</link>.</para>
</section>
<section>
<title>Using XPath expressions</title>
<note>
<para>XPath expressions work only if <link
xlink:href="http://jaxen.org/">Jaxen</link> (recommended, but use
at least Jaxen 1.1-beta-8, not older) or <link
xlink:href="http://xml.apache.org/xalan/">Apache Xalan</link>
classes are available. (Apache Xalan classes are included in Sun
J2SE 1.4, 1.5 and 1.6 (and maybe later too); no separate Xalan jar
is needed.)</para>
</note>
<para>If a hash key used with a node variable can't be interpreted
otherwise (see the <link linkend="xgui_imperative_formal">next
section</link> for the precise definition), then it will by
interpreted as an XPath expression. For more information on XPath,
please visit <link
xlink:href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</link>.</para>
<para>For example, here we list the <literal>para</literal> elements
of the chapter with title ``Ch1'':</para>
<programlisting role="template"><#list doc["book/chapter[title='Ch1']/para"] as p>
<p>${p}
</#list></programlisting>
<para>It will print:</para>
<programlisting role="output"> <p>p1.1
<p>p1.2
<p>p1.3</programlisting>
<para>The rule with sequences of length 1 (explained in earlier
sections) stands for XPath results as well. That is, if the
resulting sequence contains exactly 1 node, it also acts as the node
itself. For example, print the first paragraph of chapter
``Ch1'':</para>
<programlisting role="template">${doc["book/chapter[title='Ch1']/para[1]"]}</programlisting>
<para>which prints the same as:</para>
<programlisting role="template">${doc["book/chapter[title='Ch1']/para[1]"][0]}</programlisting>
<para>The context node of the XPath expression is the node (or
sequence of nodes) whose hash subvariable is used to issue the XPath
expression. Thus, this prints the same as the previous
example:</para>
<programlisting role="template">${doc.book["chapter[title='Ch1']/para[1]"]}</programlisting>
<para>Note that currently you can use a sequence of 0 or multiple
(more than 1) nodes as context only if the programmer has set up
FreeMarker to use Jaxen instead of Xalan.</para>
<para>Also note that XPath indexes sequence items from 1, while FTL
indexes sequence items from 0. Thus, to select the first chapter,
the XPath expression is <literal>"/book/chapter[1]"</literal>, while
the FTL expression is <literal>book.chapter[0]</literal>.</para>
<para>If the programmer has set up FreeMarker to use Jaxen instead
of Xalan, then FreeMarker variables are visible with XPath variable
references:</para>
<programlisting role="template"><#assign <emphasis>currentTitle</emphasis> = "Ch1">
<#list doc["book/chapter[title=<emphasis>$currentTitle</emphasis>]/para"] as p>
<replaceable>...</replaceable></programlisting>
<para>Note that <literal>$currentTitle</literal> is not a FreeMarker
interpolation, as there are no <literal>{</literal> and
<literal>}</literal> there. That's an XPath expression.</para>
<para>The result of some XPath expressions is not a node-set, but a
string, a number, or a boolean. For those XPath expressions, the
result is an FTL string, number, or boolean variable respectively.
For example, the following will count the total number of
<literal>para</literal> elements in the XML document, so the result
is a number:</para>
<programlisting role="template">${x["count(//para)"]}</programlisting>
<para>The output will be:</para>
<programlisting role="output">5</programlisting>
</section>
<section>
<title>XML namespaces</title>
<indexterm>
<primary>XML namespace</primary>
<secondary>in imperative processing</secondary>
</indexterm>
<para>Be default, when you write something like
<literal>doc.book</literal>, then it will select the element with
name <literal>book</literal> that does not belongs to any XML
namespace (similarly to XPath). If you want to select an element
that is inside an XML namespace, you must register a prefix and use
that. For example, if element <literal>book</literal> is in XML
namespace <literal>http://example.com/ebook</literal>, then you have
to associate a prefix with it at the top of the template with the
<literal>ns_prefixes</literal> parameter of the <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link>:</para>
<programlisting role="template"><#ftl ns_prefixes={"e":"http://example.com/ebook"}>
</programlisting>
<para>And now you can write expressions as
<literal>doc["e:book"]</literal>. (The usage of square bracket
syntax was required because the colon would confuse FreeMarker
otherwise.)</para>
<para>As the value of <literal>ns_prefixes</literal> is a hash, you
can register multiple prefixes:</para>
<programlisting role="template"><#ftl ns_prefixes={
"e":"http://example.com/ebook",
"f":"http://example.com/form",
"vg":"http://example.com/vectorGraphics"}
></programlisting>
<para>The <literal>ns_prefixes</literal> parameter affects the whole
<link linkend="dgui_misc_namespace">FTL namespace</link>. This means
in practice that the prefixes you have registered in the main page
template will be visible in all <literal><#include
...></literal>-d templates, but not in <literal><#imported
...></literal>-d templates (often referred as FTL libraries). Or
from another point of view, an FTL library can register XML
namespace prefixes for it's own use, without interfering with the
prefix registrations of the main template and other
libraries.</para>
<para>Note that, if an input document is dominated by a given XML
namespace, you can set that as the default namespace for
convenience. This means that if you don't use prefix, as in
<literal>doc.book</literal>, then it selects element that belongs to
the default namespace. The setting of the default namespace happens
with reserved prefix <literal>D</literal>, for example:</para>
<programlisting role="template"><#ftl ns_prefixes={"D":"http://example.com/ebook"}>
</programlisting>
<para>Now expression <literal>doc.book</literal> select the
<literal>book</literal> element that belongs to XML namespace
<literal>http://example.com/ebook</literal>. Unfortunately, XPath
does not support this idea of a default namespace. Thus, in XPath
expressions, element names without prefixes always select the
elements that does not belong to any XML namespace. However, to
access elements in the default namespace you can directly use prefix
<literal>D</literal>, for example:
<literal>doc["D:book/D:chapter[title='Ch1']"]</literal>.</para>
<para>Note that when you use a default namespace, then you can
select elements that does not belong to any node namespace with
reserved prefix <literal>N</literal>, for example
<literal>doc.book["N:foo"]</literal>. It doesn't go for XPath
expressions, where the above can be witten as
<literal>doc["D:book/foo"]</literal>.</para>
</section>
<section>
<title>Don't forget escaping!</title>
<para>We have made a big mistake in all examples. We generate output
of HTML format, and HTML format reserves characters as
<literal><</literal>, <literal>&</literal>, etc. So when we
print plain text (as the titles and paragraphs), we have to escape
it. Thus, the correct version of the example is:</para>
<programlisting role="template"><emphasis><#escape x as x?html></emphasis>
<#assign book = doc.book>
<h1>${book.title}</h1>
<#list book.chapter as ch>
<h2>${ch.title}</h2>
<#list ch.para as p>
<p>${p}
</#list>
</#list>
<emphasis></#escape></emphasis></programlisting>
<para>So if the book title is "Romeo & Julia", the resulting
HTML output will be correctly:</para>
<programlisting role="output"><replaceable>...</replaceable>
<h1>Romeo &amp; Julia</h1>
<replaceable>...</replaceable></programlisting>
</section>
</section>
<section xml:id="xgui_imperative_formal">
<title>Formal description</title>
<para>Every variable that corresponds to a single node in the DOM tree
is a multi-type variable of type node and type hash (for programmers:
implements both <literal>TemplateNodeModel</literal> and
<literal>TemplateHashModel</literal>). Thus, you can use the <link
linkend="ref_builtins_node">node built-ins</link> with them. Hash keys
are interpreted as XPath expressions, except the special keys shown in
the table below. Some of the node variables also have string type, so
you can use them as string variables (for programmers: they implement
<literal>TemplateScalarModel</literal>).</para>
<anchor xml:id="misc.xguiTable" />
<informaltable border="1">
<thead>
<tr>
<th>Node type (<literal>?node_type</literal>)</th>
<th>Node name (<literal>?node_name</literal>)</th>
<th>String value (e.g. <literal><p>${node}</literal>)</th>
<th>Special hash keys</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>"document"</literal></td>
<td><literal>"@document"</literal></td>
<td>No string value. (Error when you try to use it as
string.)</td>
<td><literal>"<replaceable>elementName</replaceable>"</literal>,
<literal>"<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>"</literal>,
<literal>"*"</literal>, <literal>"**"</literal>,
<literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal></td>
</tr>
<tr>
<td><literal>"element"</literal></td>
<td><literal>"<replaceable>name</replaceable>"</literal>: the
name of the element. This is the local name (i.e. name without
namespace prefix).</td>
<td>If it has no element children, the text of all text node
children concatenated together. Error otherwise, when you try to
use it as string.</td>
<td><literal>"<replaceable>elementName</replaceable>"</literal>,
<literal>"<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>"</literal>,
<literal>"*"</literal>, <literal>"**"</literal>,
<literal>"@<replaceable>attrName</replaceable>"</literal>,
<literal>"@<replaceable>prefix</replaceable>:<replaceable>attrName</replaceable>"</literal>,
<literal>"@@"</literal>, <literal>"@*"</literal>,
<literal>"@@start_tag"</literal>,
<literal>"@@end_tag"</literal>,
<literal>"@@attributes_markup"</literal>,
<literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal>, <literal>"@@qname"</literal></td>
</tr>
<tr>
<td><literal>"text"</literal></td>
<td><literal>"@text"</literal></td>
<td>The text itself.</td>
<td><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal></td>
</tr>
<tr>
<td><literal>"pi"</literal></td>
<td><literal>"@pi$<replaceable>target</replaceable>"</literal></td>
<td>The part between the target name and the
<literal>?></literal>.</td>
<td><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal></td>
</tr>
<tr>
<td><literal>"comment"</literal></td>
<td><literal>"@comment"</literal></td>
<td>The text of the comment, without the delimiters
<literal><!--</literal> and <literal>--></literal>.</td>
<td><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal></td>
</tr>
<tr>
<td><literal>"attribute"</literal></td>
<td><literal>"<replaceable>name</replaceable>"</literal>: the
name of the attribute. This is the local name (i.e. name without
namespace prefix).</td>
<td>The value of the attribute.</td>
<td><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal>, <literal>"@@qname"</literal></td>
</tr>
<tr>
<td><literal>"document_type"</literal></td>
<td><literal>"@document_type$<replaceable>name</replaceable>"</literal>:
<literal><replaceable>name</replaceable></literal> is the name
of the document element.</td>
<td>No string value. (Error when you try to use it as
string.)</td>
<td><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal>,
<literal>"@@text"</literal></td>
</tr>
</tbody>
</informaltable>
<para>Notes:</para>
<itemizedlist>
<listitem>
<para>There is no CDATA type. CDATA nodes are transparently
considered as text nodes.</para>
</listitem>
<listitem>
<para>Variables do <emphasis>not</emphasis> support
<literal>?keys</literal> and <literal>?values</literal>.</para>
</listitem>
<listitem>
<para>Element and attribute node names are local names, that is,
they do not contain the namespace prefix. The URI of the namespace
the node belongs to can be queried with the
<literal>?node_namespace</literal> built-in.</para>
</listitem>
<listitem>
<para>XPath expression needs Jaxen (recommended, but please use
1.1-beta-8 or later; <link xlink:href="http://jaxen.org/">download
it here</link>) or Apache Xalan classes available, or an error
will stop template execution. Note, however, that as some special
hash keys hide the XPath expressions of the same meaning, those
XPath expressions will work even if there is no XPath
implementation available. <phrase role="forProgrammers">If both
Xalan and Jaxen is available, FreeMarker will use Xalan, unless
you choose Jaxen by calling
<literal>freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</literal>
from Java.</phrase></para>
</listitem>
<listitem>
<para>If Jaxen is used for the XPath support (not Xalan), then
FreeMarker variables are visible with XPath variable references
(e.g.
<literal>doc["book/chapter[title=$currentTitle]"]</literal>).</para>
</listitem>
</itemizedlist>
<para>Meaning of special hash keys:</para>
<itemizedlist>
<listitem>
<para><literal>"<replaceable>elementName</replaceable>"</literal>,
<literal>"<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>"</literal>:
Returns the sequence of child nodes that are elements of name
<literal><replaceable>elementName</replaceable></literal>. (Note
that the term ``child'' means <emphasis>immediate</emphasis>
descendant.) The selection is XML name-space aware, unless the XML
document was persed with an XML parser that was not in namespace
aware mode. In XML name-space aware mode, names without prefix
(<replaceable>elementName</replaceable>) selects only elements
that doesn't belong to any XML name-space (unless you have
registered a default XML namespace), and names with prefix
(<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>)
selects only elements that are belonging to the XML namespace
denoted by the prefix. The registration of prefixes and the
setting of the default XML namespace is done with the
<literal>ns_prefixes</literal> parameter of the <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link>.</para>
</listitem>
<listitem>
<para><literal>"*"</literal>: Returns the sequence of all child
(direct descedant) <emphasis>element</emphasis> nodes. The
sequence will contain the elements in the ``document order'', that
is, in the order in which the first character of the XML
representation of each node occurs (after expansion of general
entities).</para>
</listitem>
<listitem>
<para><literal>"**"</literal>: Returns the sequence of all
descendant <emphasis>element</emphasis> nodes. The sequence will
contain the elements in the document order.</para>
</listitem>
<listitem>
<para><literal>"@<replaceable>attName</replaceable>"</literal>,
<literal>"@<replaceable>prefix</replaceable>:<replaceable>attrName</replaceable>"</literal>:
Returns the attribute
<literal><replaceable>attName</replaceable></literal> of the
element as a sequence of size 1 that contains the attribute node,
or as an empty sequence if the attribute does not exist (so to
check if an attribute exists use
<literal>foo.@<replaceable>attName</replaceable>[0]??</literal>,
<emphasis>not</emphasis>
<literal>foo.@<replaceable>attName</replaceable>??</literal>). As
with special key
<literal>"<replaceable>elementName</replaceable>"</literal>, if
the length of the sequence is 1, then it also acts as its first
subvariable. If no
<literal><replaceable>prefix</replaceable></literal> is used, then
it returns only attribute that does not use XML namespace (even if
you have set a default XML namespace). If a
<literal><replaceable>prefix</replaceable></literal> is used, it
returns only the attribute that belongs to the XML namespace
associated with the
<literal><replaceable>prefix</replaceable></literal>. The
registration of prefixes is done with the
<literal>ns_prefixes</literal> parameter of the <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link>.</para>
</listitem>
<listitem>
<para><literal>"@@"</literal> or <literal>"@*"</literal>: Returns
the sequence of attribute nodes belonging to the parent element.
This is the same as XPath <literal>@*</literal>.</para>
</listitem>
<listitem>
<para><literal>"@@qname"</literal>: Returns the full-qualified
name of the element (such as <literal>e:book</literal>, in
contrast to the local name returned by
<literal>?node_name</literal> that is <literal>book</literal>) .
The prefix used (as <literal>e</literal>) is chosen based on the
prefix registered in the current namespace with the
<literal>ns_prefixes</literal> parameter of the
<literal>ftl</literal> directive, and not influenced by the prefix
used in the source XML document. If you have set a default XML
namespace, then for nodes that use that, prefix
<literal>D</literal> will be used. For nodes that does not belong
to an XML namespace, no prefix is used (even if you have set a
default namespace). If there is no prefix registered for the
namespace of the node, the result is a non-existent variable
(<literal>node.@@qname??</literal> is
<literal>false</literal>).</para>
</listitem>
<listitem>
<para><literal>"@@markup"</literal>: This returns the full XML
markup of a node, as a string. (Full XML markup means that it also
contains the markup of the child nodes, and the markup of the
children of the child nodes, and so on.) The markup you get is not
necessary the same as the markup in the source XML file, it's just
semantically identical. Especially, note that CDATA sections will
become to plain text. Also note that depending on how did you
wrapped the original XML document with FreeMarker, comment or
processing instruction nodes may were removed, and then they will
be missing from the output of course. The first outputted start
tag will contain
<literal>xmlns:<replaceable>prefix</replaceable></literal>
attributes for each XML name-spaces used in the outputted XML
fragment, and those prefixes will be used in the outputted element
and attribute names. These prefixes will be the same as the
prefixes registered with the <literal>ns_prefixes</literal>
parameter of the <literal>ftl</literal> directive (no prefix will
be used for <literal>D</literal>, as it will be registered as the
default name-space with an <literal>xmlns</literal> attribute), or
if no prefix was assigned for a XML name-space with that, then an
arbitrary chosen unused prefix is used.</para>
</listitem>
<listitem>
<para><literal>"@@nested_markup"</literal>: This is similar to
<literal>"@@markup"</literal>, but it returns the XML markup of an
element without its opening and closing tags. For the document
node, it returns the same as <literal>"@@markup"</literal>. For
other node types (text, processing instruction, etc.), it returns
an empty string. Unlike with <literal>"@@markup"</literal>, no
<literal>xmlns:<replaceable>prefix</replaceable></literal>
attributes will be placed into the ouput, but regarding the
prefixes used in element and attribute names the rules are the
same.</para>
</listitem>
<listitem>
<para><literal>"@@text"</literal>: This returns the value of all
text nodes that occur within the node (all descendant text nodes,
not just direct children), concatenated together into a single
string. If the node has no text node children, then the result is
an empty string.</para>
</listitem>
<listitem>
<para><literal>"@@start_tag"</literal>: Returns the markup of the
<link linkend="gloss.startTag">start-tag</link> of the element
node. As with <literal>@@markup</literal>, the output is not
necessary the same as in the original XML document, but it is
semantically equivalent with that. Regarding the XML name-spaces
(<literal>xmlns:<replaceable>prefix</replaceable></literal>
attributes in the output, etc.) the rules are the same as with
<literal>"@@markup"</literal></para>
</listitem>
<listitem>
<para><literal>"@@end_tag"</literal>: Returns the markup of the
<link linkend="gloss.endTag">end-tag</link> of the element node.
As with <literal>@@markup</literal>, the output is not necessary
the same as in the original XML document, but it is semantically
equivalent with that.</para>
</listitem>
<listitem>
<para><literal>@@attributes_markup</literal>: Returns the markup
of the <link linkend="gloss.attribute">attributes</link> of the
element node. As with <literal>@@markup</literal>, the output is
not necessary the same as in the original XML document, but it is
semantically equivalent with that.</para>
</listitem>
</itemizedlist>
<section>
<title>Node sequences</title>
<para>Many of the special hash keys (indicated in the above list),
and XPath expressions that result in node-sets (see the <link
xlink:href="http://www.w3.org/TR/xpath">XPath recommendation</link>)
return a sequence of nodes.</para>
<para>These node sequences, if they store exactly 1 subvariable,
will also act as the subvariable itself. For example,
<literal>${book.title[0]}</literal> will do the same as
<literal>${book.title}</literal>, if there is only one
<literal>title</literal> element child of element
<literal>book</literal>.</para>
<para>Returning an empty node sequence is a normal situation. For
example, if in a concrete XML document, element
<literal>book</literal> has no child element
<literal>chapter</literal>, then <literal>book.chapter</literal>
results in an empty node sequence. Beware! This also means, that
<literal>book.chaptre</literal> (note the typo) will also return
empty node sequence, and will not stop with error. Also,
<literal>book.chaptre??</literal> (note the typo) will return
<literal>true</literal> because the empty sequence exists, so you
have to use <literal>book.chaptre[0]??</literal> for the
check.</para>
<para>Node sequences that store not 1 nodes (but 0 or more than 1
nodes) also support some of the hash keys described above. Namely,
the following special keys are supported:</para>
<itemizedlist>
<listitem>
<para><literal>"<replaceable>elementName</replaceable>"</literal>,
<literal>"<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>"</literal></para>
</listitem>
<listitem>
<para><literal>"@<replaceable>attrName</replaceable>"</literal>,
<literal>"@<replaceable>prefix</replaceable>:<replaceable>attrName</replaceable>"</literal></para>
</listitem>
<listitem>
<para><literal>"@@markup"</literal>,
<literal>"@@nested_markup"</literal></para>
</listitem>
<listitem>
<para><literal>"@@text"</literal></para>
</listitem>
<listitem>
<para><literal>"*"</literal>, <literal>"**"</literal></para>
</listitem>
<listitem>
<para><literal>"@@"</literal>, <literal>"@*"</literal></para>
</listitem>
</itemizedlist>
<para>When you apply one of the above special keys on a node
sequence that contains more than 1 or 0 nodes, then for each node in
the sequence (where the special key does make sense, e.g. text nodes
will be skipped for key <literal>*</literal> or
<literal>@foo</literal>), the special key will be applied as it was
explained for single nodes, and the results will be concatenated to
form the final result. The results will be concatenated in the order
as the corresponding nodes occur in the node sequence. The
concatenation means string or sequence concatenation depending on
the type of the results. If the special key would result in a string
for a single node, then for multiple nodes the result is a single
string too (the results for the single nodes concatenated), and if
the special key would return a sequence for a single node, then for
multiple nodes the result is a single sequence too. If there are 0
nodes in the sequence you apply the special key on, the string
result is an empty string or an empty sequence respectively.</para>
<para>XPath expressions can be used with node sequences. However,
for 0 or more than 1 nodes it will work only if you use Jaxen
instead of Xalan, because of the limitations of the Xalan XPath
implementation.</para>
</section>
</section>
</chapter>
<chapter xml:id="xgui_declarative">
<title>Declarative XML Processing</title>
<indexterm>
<primary>XML</primary>
<secondary>declarative processing</secondary>
</indexterm>
<indexterm>
<primary>XSLT</primary>
</indexterm>
<section xml:id="xgui_declarative_basics">
<title>Basics</title>
<note>
<para>This section uses the DOM tree and the variable made in <link
linkend="xgui_expose">a previous chapter</link>.</para>
</note>
<para>With the imperative approach of XML processing -- this was shown
in the previous chapter -- you write an FTL program that walks the
tree to find the different kind of nodes. With the declarative
approach, you rather define how to handle the different kind of nodes,
and then let FreeMarker walk the tree an call the handlers you have
defined. This approach is useful for complex XML schemas, where the
same element can occur as the child of many other elements. Examples
of such schemas are XHTML and XDocBook.</para>
<para>The directive you most often use with the declarative approach
is the <link
linkend="ref.directive.recurse"><literal>recurse</literal>
directive</link>. This directive gets a node variable as parameter,
and ``visits'' all its children nodes, one after the other, starting
with the first child. ``Visiting'' a node means that it calls a
user-defined directive (like a macro) that has the same name as the
name of the child node (<literal>?node_name</literal>). We say on
this, that the user-defined directive <emphasis>handles</emphasis> the
node. The node that the user-defined directive just handles is
available as special variable <literal>.node</literal>. For example,
this FTL:</para>
<programlisting role="template"><#recurse doc>
<#macro book>
I'm the book element handler, and the title is: ${.node.title}
</#macro></programlisting>
<para>will print (I have removed some disturbing white-space form the
output):</para>
<programlisting role="output">I'm the book element handler, and the title is: Test Book
</programlisting>
<para>If you call <literal>recurse</literal> without parameter, then
it uses <literal>.node</literal>, that is, it visits all children
nodes of the node being handled currently. So this FTL:</para>
<programlisting role="template"><#recurse doc>
<#macro book>
Book element with title ${.node.title}
<#recurse>
End book
</#macro>
<#macro title>
Title element
</#macro>
<#macro chapter>
Chapter element with title: ${.node.title}
</#macro></programlisting>
<para>will print (I have removed disturbing white-space form the
output):</para>
<programlisting role="output">Book element with title Test Book
Title element
Chapter element with title: Ch1
Chapter element with title: Ch2
End book</programlisting>
<para>You have seen how to define handlers for element nodes, but not
how to define handler for the text nodes. Since the name of the
handler is the same as the node-name of nodes it handles, and as the
node-name of all text nodes is <literal>@text</literal> (see <link
linkend="misc.xguiTable">the table</link>), you define handler for the
text nodes like this:</para>
<programlisting role="template">
<#macro @text>${.node?html}</#macro>
</programlisting>
<para>Note the <literal>?html</literal>. You have to HTML-escape the
text, since you generate output of HTML format.</para>
<para>Here it is the template that transforms the XML to complete
HTML:</para>
<anchor xml:id="misc.example.declarativeBookProcessor" />
<programlisting role="template"><#recurse doc>
<#macro book>
<html>
<head>
<title><#recurse .node.title></title>
</head>
<body>
<h1><#recurse .node.title></h1>
<#recurse>
</body>
</html>
</#macro>
<#macro chapter>
<h2><#recurse .node.title></h2>
<#recurse>
</#macro>
<#macro para>
<p><#recurse>
</#macro>
<#macro title>
<#--
We have handled this element imperatively,
so we do nothing here.
-->
</#macro>
<#macro @text>${.node?html}</#macro></programlisting>
<para>and the output will be (now I will honestly include the annoying
white-space...):</para>
<programlisting role="output"> <html>
<head>
<title>Test Book</title>
</head>
<body>
<h1>Test Book</h1>
<h2>Ch1</h2>
<p>p1.1
<p>p1.2
<p>p1.3
<h2>Ch2</h2>
<p>p2.1
<p>p2.2
</body>
</html>
</programlisting>
<para>Note that you can reduce substantially the amount of superfluous
whitespace in the output by using the <link
linkend="ref_directive_t">trim directives</link>, as
<literal><#t></literal>. See also: <xref
linkend="dgui_misc_whitespace" /></para>
<para>You may say that the FTL that did it with imperative approach
was much shorter. That's true, but the example XML uses a very simple
schema, and as I said, the declarative approach brings its form with
XML schemas that are not that firm about what element can occur where.
Say, introduce element <literal>mark</literal>, that should color text
to red, does not mater where do you use it; in a
<literal>title</literal>, or in a <literal>para</literal>. For this,
with the declarative approach, you just add a macro:</para>
<programlisting role="template"><#macro mark><font color=red><#recurse></font></#macro></programlisting>
<para>And then <literal><mark>...</mark></literal> will
automatically work everywhere. So for certain XML schemas, declarative
XML processing will actually result in shorter, and what is even more
important, much clearer FTL-s, than imperative XML processing. It's up
to you to decide which approach to use when; don't forget that you can
mix the two approaches freely. Say, in an element handler, you can use
imperative approach to process the contents of that element.</para>
</section>
<section xml:id="xgui_declarative_details">
<title>Details</title>
<section>
<title>Default handlers</title>
<para>For some XML node types, there is a default handler, which
will handle the node if you haven't defined a handler for the node
(i.e. if there is no user-defined directive available with name
identical to the node name). Here are these node types, and what the
default handler does:</para>
<itemizedlist>
<listitem>
<para>Text node: prints the text as it. Note, that in most
applications, this will not be good for you, because you should
escape the text before you send it to the output (with
<literal>?html</literal> or <literal>?xml</literal> or
<literal>?rtf</literal>, ...etc. depends on the output
format).</para>
</listitem>
<listitem>
<para>Processing instruction node: call handler called
<literal>@pi</literal> if you have created such user-defined
directive, otherwise do nothing (ignore the node).</para>
</listitem>
<listitem>
<para>Comment node, document type node: Do nothing (ignore the
node).</para>
</listitem>
<listitem>
<para>Document node: Call <literal>recurse</literal>, that is,
visit all children of the document node.</para>
</listitem>
</itemizedlist>
<para>Element and attribute nodes will be handled according to the
usual, XML independent mechanism. That is,
<literal>@<replaceable>node_type</replaceable></literal> will be
called as handler, and if that's not defined, then an error stops
template processing.</para>
<para>In the case of element nodes, this means that if you define a
macro (or other kind of user-defined directive) called
<literal>@element</literal>, that will catch all element nodes,
which has no more specific handler. If you have no
<literal>@element</literal> handler, then you
<emphasis>must</emphasis> define a handler for all possible
elements.</para>
<para>Attribute nodes are not visited by the
<literal>recurse</literal> directive, so you don't need to write
handlers for them.</para>
</section>
<section>
<title>Visiting a single node</title>
<para>With the <link
linkend="ref.directive.visit"><literal>visit</literal>
directive</link> you can visit a single node, instead of the
children of the node:
<literal><#visit <replaceable>nodeToVisist</replaceable>></literal>.
This can be useful sometimes.</para>
</section>
<section>
<title>XML namespaces</title>
<indexterm>
<primary>XML namespaces</primary>
<secondary>in declarative processing</secondary>
</indexterm>
<para>We said that the name of the handler user-defined directive
(like a macro) for an element is the name of the element. In fact,
it is the full-qualified name of the element:
<literal><replaceable>prefix</replaceable>:<replaceable>elementName</replaceable></literal>.
The rules regarding the usage of
<literal><replaceable>prefix</replaceable></literal>-es is the same
as with imperative processing. Thus, the user-defined
<literal>book</literal> directive handles only element
<literal>book</literal> that does not belong to any XML namespace
(unless you have specified a default XML namespace). So if the
example XML would use XML namespace
<literal>http://example.com/ebook</literal>:</para>
<programlisting role="unspecified"><book xmlns="http://example.com/ebook">
<replaceable>...</replaceable></programlisting>
<para>Then the FTL should look as this:</para>
<programlisting role="template"><emphasis><#ftl ns_prefixes={"e":"http://example.com/ebook"}></emphasis>
<#recurse doc>
<#macro "<emphasis>e:</emphasis>book">
<html>
<head>
<title><#recurse .node["<emphasis>e:</emphasis>title"]></title>
</head>
<body>
<h1><#recurse .node["<emphasis>e:</emphasis>title"]></h1>
<#recurse>
</body>
</html>
</#macro>
<#macro "<emphasis>e:</emphasis>chapter">
<h2><#recurse .node["<emphasis>e:</emphasis>title"]></h2>
<#recurse>
</#macro>
<#macro "<emphasis>e:</emphasis>para">
<p><#recurse>
</#macro>
<#macro "<emphasis>e:</emphasis>title">
<#--
We have handled this element imperatively,
so we do nothing here.
-->
</#macro>
<#macro @text>${.node?html}</#macro></programlisting>
<para>Or, you can define a default XML namespace, and then the
further part of the template remains the same as in the original XML
namespace free example:</para>
<programlisting role="template"><#ftl ns_prefixes={"<emphasis>D</emphasis>":"http://example.com/ebook"}>
<#recurse doc>
<#macro book>
<replaceable>...</replaceable></programlisting>
<para>But in this case don't forge that in XPath expressions (we
didn't used any in the example) the default XML namespace must be
accessed with an explicit <literal>D:</literal> since names without
prefix always refer to nodes with no XML namespace in XPath. Also
note that with the same logic as with imperative XML processing, the
name of handlers for elements that has no XML namespace is
<literal>N:<replaceable>elementName</replaceable></literal> if (and
only if) there is a default XML namespace. However, for nodes that
are not of type element (such as text nodes), you never use the
<literal>N</literal> prefix in the handler name, because those nodes
are free of the idea of XML namespaces. So for example, the handler
for text nodes is always just <literal>@text</literal>.</para>
<para>For more detailed information, please read <link
linkend="ref_directive_visit">the reference of
<literal>recurse</literal> and <literal>visit</literal></link>
directives.</para>
</section>
</section>
</chapter>
</part>
<part xml:id="ref">
<title>Reference</title>
<chapter xml:id="ref_builtins">
<title>Built-in Reference</title>
<indexterm>
<primary>built-in</primary>
</indexterm>
<section xml:id="ref_builtins_alphaidx">
<title>Alphabetical index</title>
<indexterm>
<primary>built-in</primary>
</indexterm>
<itemizedlist spacing="compact">
<listitem>
<para><link
linkend="ref_builtin_ancestors">ancestors</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">byte</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_c">c</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_cap_first">cap_first</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_capitalize">capitalize</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_rounding">ceiling</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_children">children</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_chop_linebreak">chop_linebreak</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_chunk">chunk</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_contains">contains</link></para>
</listitem>
<listitem>
<para>date <link linkend="ref_builtin_date_datetype">for
dates</link>, <link linkend="ref_builtin_string_date">for
strings</link></para>
</listitem>
<listitem>
<para>datetime <link linkend="ref_builtin_date_datetype">for
dates</link>, <link linkend="ref_builtin_string_date">for
strings</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">double</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_ends_with">ends_with</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_eval">eval</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_first">first</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_rounding">floor</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_groups">groups</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">float</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_has_content">has_content</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_html">html</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_index_of">index_of</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">int</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_interpret">interpret</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_isType">is_...</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_date_iso">iso,
iso_...</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_j_string">j_string</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_js_string">js_string</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_keys">keys</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_last">last</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_last_index_of">last_index_of</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_left_pad">left_pad</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_length">length</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">long</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_lower_case">lower_case</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_matches">matches</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_namespace">namespace</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_new">new</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_node_namespace">node_namespace</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_node_name">node_name</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_node_type">node_type</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_number">number</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numToDate">number_to_date,
number_to_datetime, number_to_time</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_parent">parent</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_replace">replace</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_reverse">reverse</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_right_pad">right_pad</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_rounding">round</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_root">root</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_rtf">rtf</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_numType">short</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_size">size</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_sort">sort</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_seq_contains">seq_contains</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_seq_index_of">seq_index_of</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_seq_last_index_of">seq_last_index_of</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_sort_by">sort_by</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_split">split</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_starts_with">starts_with</link></para>
</listitem>
<listitem>
<para>string: <link linkend="ref_builtin_string_for_string">for
strings</link>, <link linkend="ref_builtin_string_for_number">for
numbers</link>, <link linkend="ref_builtin_string_for_boolean">for
booleans</link>, <link linkend="ref_builtin_string_for_date">for
date/times</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_substring">substring</link></para>
</listitem>
<listitem>
<para>time <link linkend="ref_builtin_date_datetype">for
dates</link>, <link linkend="ref_builtin_string_date">for
strings</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_trim">trim</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_uncap_first">uncap_first</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_upper_case">upper_case</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_url">url</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_values">values</link></para>
</listitem>
<listitem>
<para><link
linkend="ref_builtin_word_list">word_list</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_xhtml">xhtml</link></para>
</listitem>
<listitem>
<para><link linkend="ref_builtin_xml">xml</link></para>
</listitem>
</itemizedlist>
<para>If you don't find a built-in here that you have seen in a
working template, probably you will find it here: <xref
linkend="ref_deprecated" /></para>
</section>
<section xml:id="ref_builtins_string">
<title>Built-ins for strings</title>
<indexterm>
<primary>string</primary>
<secondary>built-ins</secondary>
</indexterm>
<section xml:id="ref_builtin_substring">
<title>substring</title>
<indexterm>
<primary>substring built-in</primary>
</indexterm>
<note>
<para>This built-in exists since FreeMarker 2.3.7.</para>
</note>
<para>Synopsis:
<literal><replaceable>exp</replaceable>?substring(<replaceable>from</replaceable>,
<replaceable>toExclusive</replaceable>)</literal>, also callable as
<literal><replaceable>exp</replaceable>?substring(<replaceable>from</replaceable>)</literal></para>
<para>A substring of the string.
<literal><replaceable>from</replaceable></literal> is the index of
the first character. It must be a number that is at least 0 and less
than or equal with
<literal><replaceable>toExclusive</replaceable></literal>, or else
an error will abort the template processing. The
<literal><replaceable>toExclusive</replaceable></literal> is the
index of the character position after the last character of the
substring, or with other words, it is one greater than the index of
the last character. It must be a number that is at least 0 and less
than or equal to the length of the string, or else an error will
abort the template processing. If the
<literal><replaceable>toExclusive</replaceable></literal> is
omitted, then it defaults to the length of the string. If a
parameter is a number that is not an integer, only the integer part
of the number will be used.</para>
<para>Example:</para>
<programlisting role="template">- ${'abc'?substring(0)}
- ${'abc'?substring(1)}
- ${'abc'?substring(2)}
- ${'abc'?substring(3)}
- ${'abc'?substring(0, 0)}
- ${'abc'?substring(0, 1)}
- ${'abc'?substring(0, 2)}
- ${'abc'?substring(0, 3)}
- ${'abc'?substring(0, 1)}
- ${'abc'?substring(1, 2)}
- ${'abc'?substring(2, 3)}</programlisting>
<para>The output:</para>
<programlisting role="output">- abc
- bc
- c
-
-
- a
- ab
- abc
- a
- b
- c</programlisting>
</section>
<section xml:id="ref_builtin_cap_first">
<title>cap_first</title>
<indexterm>
<primary>cap_first built-in</primary>
</indexterm>
<para>The string with the very first word of the string capitalized.
For the precise meaning of ``word'' see the <link
linkend="ref_builtin_word_list">word_list built-in</link>.
Example:</para>
<programlisting role="template">${" green mouse"?cap_first}
${"GreEN mouse"?cap_first}
${"- green mouse"?cap_first}</programlisting>
<para>The output:</para>
<programlisting role="output"> Green mouse
GreEN mouse
- green mouse</programlisting>
<para>In the case of <literal>"- green mouse"</literal>, the first
word is the <literal>-</literal>.</para>
</section>
<section xml:id="ref_builtin_uncap_first">
<title>uncap_first</title>
<indexterm>
<primary>uncap_first built-in</primary>
</indexterm>
<para>The opposite of <link
linkend="ref_builtin_cap_first"><literal>cap_first</literal></link>.
The string with the very first word of the string
un-capitalized.</para>
</section>
<section xml:id="ref_builtin_capitalize">
<title>capitalize</title>
<indexterm>
<primary>capitalize built-in</primary>
</indexterm>
<para>The string with all words capitalized. For the precise meaning
of ``word'' see the <link linkend="ref_builtin_word_list">word_list
built-in</link>. Example:</para>
<programlisting role="template">${" green mouse"?capitalize}
${"GreEN mouse"?capitalize}</programlisting>
<para>The output:</para>
<programlisting role="output"> Green Mouse
Green Mouse</programlisting>
</section>
<section xml:id="ref_builtin_chop_linebreak">
<title>chop_linebreak</title>
<indexterm>
<primary>chop_linebreak built-in</primary>
</indexterm>
<para>The string without the <link
linkend="gloss.lineBreak">line-break</link> at its very end if there
was a line-break, otherwise the unchanged string.</para>
</section>
<section xml:id="ref_builtin_string_date">
<title>date, time, datetime</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>date built-in</primary>
</indexterm>
<indexterm>
<primary>time built-in</primary>
</indexterm>
<indexterm>
<primary>datetime built-in</primary>
</indexterm>
<indexterm>
<primary>string to date</primary>
</indexterm>
<indexterm>
<primary>string to time</primary>
</indexterm>
<indexterm>
<primary>converting string to date</primary>
</indexterm>
<indexterm>
<primary>converting string to time</primary>
</indexterm>
<indexterm>
<primary>parsing string as date</primary>
</indexterm>
<indexterm>
<primary>parsing string as time</primary>
</indexterm>
<para>The string converted to a date value. It is recommended to
specify a parameter that specifies the format. For example:</para>
<programlisting role="template"><#assign test1 = "10/25/1995"?date("MM/dd/yyyy")>
<#assign test2 = "15:05:30"?time("HH:mm:ss")>
<#assign test3 = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>
${test1}
${test2}
${test3}</programlisting>
<para>will print something like (depends on the output locale
(language) and on other settings):</para>
<programlisting role="output">Oct 25, 1995
3:05:30 PM
Oct 25, 1995 3:05:00 PM
</programlisting>
<para>Note that the dates was converted back to string according to
the <literal>date_format</literal>, <literal>time_format</literal>
and <literal>datetime_format</literal> <link
linkend="ref.directive.setting">settings</link> (for more
information about converting dates to strings read: <link
linkend="ref_builtin_string_for_date">string built-in for
dates</link>, <link
linkend="dgui_template_valueinserion_universal_date">date
interpolations</link>). It does not mater what format did you use
when you have converted the strings to dates.</para>
<para>You don't have to use the format parameter, if you know what
the default date/time/datetime format will be when the template is
processed:</para>
<programlisting role="template"><#assign test1 = "Oct 25, 1995"?date>
<#assign test2 = "3:05:30 PM"?time>
<#assign test3 = "Oct 25, 1995 03:05:00 PM"?datetime>
${test1}
${test2}
${test3}</programlisting>
<para>If the string is not in the appropriate format, an error will
abort template processing when you try to access this
built-in.</para>
</section>
<section xml:id="ref_builtin_ends_with">
<title>ends_with</title>
<indexterm>
<primary>ends_with built-in</primary>
</indexterm>
<para>Returns if this string ends with the specified substring. For
example <literal>"redhead"?ends_with("head")</literal> returns
boolean true. Also, <literal>"head"?ends_with("head")</literal> will
return true.</para>
</section>
<section xml:id="ref_builtin_html">
<title>html</title>
<indexterm>
<primary>escaping</primary>
<secondary>output</secondary>
</indexterm>
<indexterm>
<primary>html built-in</primary>
</indexterm>
<para>The string as HTML markup. That is, the string with
all:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><</literal> replaced with
<literal>&lt;</literal></para>
</listitem>
<listitem>
<para><literal>></literal> replaced with
<literal>&gt;</literal></para>
</listitem>
<listitem>
<para><literal>&</literal> replaced with
<literal>&amp;</literal></para>
</listitem>
<listitem>
<para><literal>"</literal> replaced with
<literal>&quot;</literal></para>
</listitem>
</itemizedlist>
<para>Note that if you want to insert an attribute value securely,
you must quote the attribute value in the HTML template with
quotation mark (with <literal>"</literal>, not with
<literal>'</literal>):</para>
<programlisting role="template"><input type=text name=user value=<emphasis>"</emphasis>${user?html}<emphasis>"</emphasis>></programlisting>
<para>Note that in HTML pages usually you want to use this built-in
for all interpolations. So you can spare a lot of typing and lessen
the chances of accidental mistakes by using the <link
linkend="ref_directive_escape"><literal>escape</literal>
directive</link>.</para>
</section>
<section xml:id="ref_builtin_groups">
<title>groups</title>
<indexterm>
<primary>groups built-in</primary>
</indexterm>
<para>This is used only with the result of the
<literal>matches</literal> built-in. See <link
linkend="ref_builtin_matches">there...</link></para>
</section>
<section xml:id="ref_builtin_index_of">
<title>index_of</title>
<indexterm>
<primary>index_of built-in</primary>
</indexterm>
<para>Returns the index within this string of the first occurrence
of the specified substring. For example,
<literal>"abcabc"?index_of("bc")</literal> will return 1 (don't
forget that the index of the first character is 0). Also, you can
specify the index to start the search from:
<literal>"abcabc"?index_of("bc", 2)</literal> will return 4. There
is no restriction on the numerical value of the second parameter: if
it is negative, it has the same effect as if it were zero, and if it
is greater than the length of this string, it has the same effect as
if it were equal to the length of this string. Decimal values will
be truncated to integers.</para>
<para>If the 1st parameter does not occur as a substring in this
string (starting from the given index, if you use the second
parameter), then it returns -1.</para>
</section>
<section xml:id="ref_builtin_j_string">
<title>j_string</title>
<indexterm>
<primary>j_string built-in</primary>
</indexterm>
<para>Escapes the string with the escaping rules of Java language
string literals, so it is safe to insert the value into a string
literal. In additional, all characters under <link
linkend="gloss.UCS">UCS</link> code point 0x20, that has no
dedicated escape sequence in Java language, will be replaced with
UNICODE escape
(<literal>\u<replaceable>XXXX</replaceable></literal>).</para>
<para>Example:</para>
<programlisting role="template"><#assign beanName = 'The "foo" bean.'>
String BEAN_NAME = "${beanName?j_string}";</programlisting>
<para>will output:</para>
<programlisting role="output">String BEAN_NAME = "The \"foo\" bean.";</programlisting>
</section>
<section xml:id="ref_builtin_js_string">
<title>js_string</title>
<indexterm>
<primary>js_string built-in</primary>
</indexterm>
<para>Escapes the string with the escaping rules of JavaScript
language string literals, so it is safe to insert the value into a
string literal. Both quotation mark (<literal>"</literal>) and
apostrophe-quoate (<literal>'</literal>) are escaped. Starting from
FreeMarker 2.3.1, it also escapes <literal>></literal> as
<literal>\></literal> (to avoid
<literal></script></literal>). Furthermore, all characters
under <link linkend="gloss.UCS">UCS</link> code point 0x20, that has
no dedicated escape sequence in JavaScript language, will be
replaced with hexadecimal escape
(<literal>\x<replaceable>XX</replaceable></literal>). (Of course,
according the JavaScript language string literal syntax, backslash
(<literal>\</literal>) will be escaped too, line-feed will be
escaped as <literal>\n</literal>, ...etc.)</para>
<para>Example:</para>
<programlisting role="template"><#assign user = "Big Joe's \"right hand\"">
<script>
alert("Welcome ${user?js_string}!");
</script></programlisting>
<para>will output:</para>
<programlisting role="output"><script>
alert("Welcome Big Joe\'s \"right hand\"!");
</script></programlisting>
</section>
<section xml:id="ref_builtin_last_index_of">
<title>last_index_of</title>
<indexterm>
<primary>last_index_of built-in</primary>
</indexterm>
<para>Returns the index within this string of the last (rightmost)
occurrence of the specified substring. It returns the index of the
first (leftmost) character of the substring. For example:
<literal>"abcabc"?last_index_of("ab")</literal> will return 3. Also,
you can specify the index to start the search from. For example,
<literal>"abcabc"?last_index_of("ab", 2)</literal> will return 0.
Note that the second parameter indicates the maximum index of the
start of the substring. There is no restriction on the numerical
value of the second parameter: if it is negative, it has the same
effect as if it were zero, and if it is greater than the length of
this string, it has the same effect as if it were equal to the
length of this string. Decimal values will be truncated to
inegers.</para>
<para>If the 1st parameter does not occur as a substring in this
string (before the given index, if you use the second parameter),
then it returns -1.</para>
</section>
<section xml:id="ref_builtin_length">
<title>length</title>
<indexterm>
<primary>length built-in</primary>
</indexterm>
<para>The number of characters in the string.</para>
</section>
<section xml:id="ref_builtin_lower_case">
<title>lower_case</title>
<indexterm>
<primary>lower_case built-in</primary>
</indexterm>
<para>The lower case version of the string. For example
<literal>"GrEeN MoUsE"?lower_case</literal> will be <literal>"green
mouse"</literal>.</para>
</section>
<section xml:id="ref_builtin_left_pad">
<title>left_pad</title>
<indexterm>
<primary>left_pad built-in</primary>
</indexterm>
<indexterm>
<primary>padding</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<para>If it's used with 1 parameter, then it inserts spaces on the
beginning of the string until it reaches the length that is
specified as the parameter. If the string is already as long or
longer than the specified length, then it does nothing. For example,
this:</para>
<programlisting role="template">[${""?left_pad(5)}]
[${"a"?left_pad(5)}]
[${"ab"?left_pad(5)}]
[${"abc"?left_pad(5)}]
[${"abcd"?left_pad(5)}]
[${"abcde"?left_pad(5)}]
[${"abcdef"?left_pad(5)}]
[${"abcdefg"?left_pad(5)}]
[${"abcdefgh"?left_pad(5)}]</programlisting>
<para>will output this:</para>
<programlisting role="output">[ ]
[ a]
[ ab]
[ abc]
[ abcd]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]</programlisting>
<para>If it's used with 2 parameters, then the 1st parameter means
the same as if you were using the built-in with only 1 parameter,
and the second parameter specifies what to insert instead of space
characters. For example:</para>
<programlisting role="template">[${""?left_pad(5, "-")}]
[${"a"?left_pad(5, "-")}]
[${"ab"?left_pad(5, "-")}]
[${"abc"?left_pad(5, "-")}]
[${"abcd"?left_pad(5, "-")}]
[${"abcde"?left_pad(5, "-")}]</programlisting>
<para>will output this:</para>
<programlisting role="output">[-----]
[----a]
[---ab]
[--abc]
[-abcd]
[abcde]</programlisting>
<para>The 2nd parameter can be a string whose length is greater than
1. Then the string will be inserted periodically, for
example:</para>
<programlisting role="template">[${""?left_pad(8, ".oO")}]
[${"a"?left_pad(8, ".oO")}]
[${"ab"?left_pad(8, ".oO")}]
[${"abc"?left_pad(8, ".oO")}]
[${"abcd"?left_pad(8, ".oO")}]</programlisting>
<para>will output this:</para>
<programlisting role="output">[.oO.oO.o]
[.oO.oO.a]
[.oO.oOab]
[.oO.oabc]
[.oO.abcd]</programlisting>
<para>The 2nd parameter must be a string value, and it must be at
least 1 character long.</para>
</section>
<section xml:id="ref_builtin_right_pad">
<title>right_pad</title>
<indexterm>
<primary>right_pad built-in</primary>
</indexterm>
<indexterm>
<primary>padding</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<para>This is the same as <link
linkend="ref_builtin_left_pad"><literal>left_pad</literal></link>,
but it inserts the characters at the end of the string instead of
the beginning of the string.</para>
<para>Example:</para>
<programlisting role="template">[${""?right_pad(5)}]
[${"a"?right_pad(5)}]
[${"ab"?right_pad(5)}]
[${"abc"?right_pad(5)}]
[${"abcd"?right_pad(5)}]
[${"abcde"?right_pad(5)}]
[${"abcdef"?right_pad(5)}]
[${"abcdefg"?right_pad(5)}]
[${"abcdefgh"?right_pad(5)}]
[${""?right_pad(8, ".oO")}]
[${"a"?right_pad(8, ".oO")}]
[${"ab"?right_pad(8, ".oO")}]
[${"abc"?right_pad(8, ".oO")}]
[${"abcd"?right_pad(8, ".oO")}]</programlisting>
<para>This will output this:</para>
<programlisting role="output">[ ]
[a ]
[ab ]
[abc ]
[abcd ]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]
[.oO.oO.o]
[aoO.oO.o]
[abO.oO.o]
[abc.oO.o]
[abcdoO.o]</programlisting>
</section>
<section xml:id="ref_builtin_contains">
<title>contains</title>
<indexterm>
<primary>contains built-in</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<para>Returns if the substring specified as the parameter to this
built-in occurrs in the string. For example:</para>
<programlisting role="template"><#if "piceous"?contains("ice")>It contains "ice"</#if>
</programlisting>
<para>This will output:</para>
<programlisting role="output">It contains "ice"</programlisting>
</section>
<section xml:id="ref_builtin_matches">
<title>matches</title>
<indexterm>
<primary>matches built-in</primary>
</indexterm>
<para>This is a ``power user'' built-in. Ignore it if you don't know
<link linkend="gloss.regularExpression">regular
expressions</link>.</para>
<note>
<para>This built-in will work only if you use Java2 platform 1.4
or later. Otherwise it will stop template processing with
error.</para>
</note>
<para>This built-in determines if the string exactly matches the
pattern. Also, it returns the list of matching sub-strings. The
return value is a multi-type value:</para>
<itemizedlist>
<listitem>
<para>Boolean: <literal>true</literal>, if it the string exactly
matches the pattern, otherwise <literal>false</literal>. For
example, <literal>"fooo"?matches('fo*')</literal> is
<literal>true</literal>, but
<literal>"fooo bar"?matches('fo*')</literal> is
<literal>false</literal>.</para>
</listitem>
<listitem>
<para>Sequence: the list of matched substrings of the string.
Possibly a 0 length sequence.</para>
</listitem>
</itemizedlist>
<para>For example:</para>
<programlisting role="template"><#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if>
<#assign res = "foo bar fyo"?matches("f.?o")>
<#if res>Matches.<#else>Does not match.</#if>
Matching sub-strings:
<#list res as m>
- ${m}
</#list></programlisting>
<para>will print:</para>
<programlisting role="output">Matches.
Does not match.
Matching sub-strings:
- foo
- fyo</programlisting>
<para>If the regular expression contains groups (parentheses), then
you can access them with the <literal>groups</literal>
built-in:</para>
<programlisting role="template"><#assign res = "aa/rx; ab/r;"?matches("(\\w[^/]+)/([^;]+);")>
<#list res as m>
- ${m} is ${m?groups[1]} per ${m?groups[2]}
</#list></programlisting>
<para>This will print:</para>
<programlisting role="output">- aa/rx; is aa per rx
- ab/r; is ab per r</programlisting>
<para><literal>matches</literal> accepts an optional 2nd parameter,
the <link linkend="ref_builtin_string_flags">flags</link>. Note that
it does not support flag <literal>f</literal>, and ignores the
<literal>r</literal> flag.</para>
</section>
<section xml:id="ref_builtin_number">
<title>number</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>number built-in</primary>
</indexterm>
<indexterm>
<primary>string to number</primary>
</indexterm>
<indexterm>
<primary>converting string to number</primary>
</indexterm>
<indexterm>
<primary>parse string as number</primary>
</indexterm>
<para>The string converted to numerical value. The number must be in
the same format as you specify numerical values directly in FTL.
That is, it must be in the locale independent form, where the
decimal separator is dot. In additional the built-in recognizes
scientific notation (e.g. <literal>"1.23E6"</literal>,
<literal>"1.5e-8"</literal>).</para>
<para>If the string is not in the appropriate format, an error will
abort template processing when you try to access this
built-in.</para>
<para>Known problem: If you use earlier Java2 platform than v1.3,
the built-ins will not recognize + prefix and scientific
notation.</para>
</section>
<section xml:id="ref_builtin_replace">
<title>replace</title>
<indexterm>
<primary>replace built-in</primary>
</indexterm>
<para>It is used to replace all occurrences of a string in the
original string with another string. It does not deal with word
boundaries. For example:</para>
<programlisting role="template">${"this is a car acarus"?replace("car", "bulldozer")}</programlisting>
<para>will print:</para>
<programlisting role="output">this is a bulldozer abulldozerus</programlisting>
<para>The replacing occurs in left-to-right order. This means that
this:</para>
<programlisting role="template">${"aaaaa"?replace("aaa", "X")}</programlisting>
<para>will print:</para>
<programlisting role="output">Xaa</programlisting>
<para>If the 1st parameter is an empty string, then all occurrences
of the empty string will be replaced, like
<literal>"foo"?replace("","|")</literal> will evaluate to
<literal>"|f|o|o|"</literal>.</para>
<para><literal>replace</literal> accepts an optional <link
linkend="ref_builtin_string_flags">flags parameter</link>, as its
3rd parameter.</para>
</section>
<section xml:id="ref_builtin_rtf">
<title>rtf</title>
<indexterm>
<primary>rtf built-in</primary>
</indexterm>
<indexterm>
<primary>escaping</primary>
<secondary>output</secondary>
</indexterm>
<para>The string as Rich text (RTF text). That is, the string with
all:</para>
<itemizedlist>
<listitem>
<para><literal>\</literal> replaced with
<literal>\\</literal></para>
</listitem>
<listitem>
<para><literal>{</literal> replaced with
<literal>\{</literal></para>
</listitem>
<listitem>
<para><literal>}</literal> replaced with
<literal>\}</literal></para>
</listitem>
</itemizedlist>
</section>
<section xml:id="ref_builtin_url">
<title>url</title>
<indexterm>
<primary>url built-in</primary>
</indexterm>
<indexterm>
<primary>escaping</primary>
<secondary>URL</secondary>
</indexterm>
<indexterm>
<primary>encoding</primary>
<secondary>URL</secondary>
</indexterm>
<indexterm>
<primary>URL escaping</primary>
</indexterm>
<indexterm>
<primary>URL encoding</primary>
</indexterm>
<indexterm>
<primary>url_escaping_charset</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<para>The string after URL escaping. This means that all
non-US-ASCII and reserved URL characters will be escaped with
<literal>%<replaceable>XX</replaceable></literal>. For
example:</para>
<programlisting role="template"><#assign x = 'a/b c'>
${x?url}</programlisting>
<para>The output will be (assuming that the charset used for the
escaping is an US-ASCII compatible charset):</para>
<programlisting role="output">a%2Fb%20c</programlisting>
<para>Note that it escapes <emphasis>all</emphasis> reserved URL
characters (<literal>/</literal>, <literal>=</literal>,
<literal>&</literal>, ...etc), so this encoding can be used for
encoding query parameter values, for example:</para>
<programlisting role="template"><a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a></programlisting>
<note>
<para>Above no HTML encoding (<literal>?htm</literal>) was needed,
because URL escaping escapes all reserved HTML characters anyway.
But watch: always quote the attribute value, and always with
normal quotation mark (<literal>"</literal>), never with
apostrophe quotation mark (<literal>'</literal>), because
apostrophe quotation mark is not escaped by the URL
escaping.</para>
</note>
<para>To do URL escaping a <link
linkend="gloss.charset">charset</link> must be chosen that will be
used for calculating the escaped parts
(<literal>%<replaceable>XX</replaceable></literal>). If you are HTML
page author and you don't really understand this, don't worry: the
programmers should configure FreeMarker so that it uses the proper
charset by default (<phrase role="forProgrammers">programmers: see
more below...</phrase>). If you are a more technical minded user,
then you may want to know that the charset used is specified by the
<literal>url_escaping_charset</literal> setting, that can be set in
template execution time (or, preferably, earlier by the
programmers). For example:</para>
<programlisting role="template"><#--
This will use the charset specified by the programmers
before the template execution has started.
-->
<a href="foo.cgi?x=${x?url}">foo</a>
<#-- Use UTF-8 charset for URL escaping from now: -->
<emphasis><#setting url_escaping_charset="UTF-8"></emphasis>
<#-- This will surely use UTF-8 charset -->
<a href="bar.cgi?x=${x?url}">bar</a></programlisting>
<para>Furthermore, you can explicitly specify a charset for a single
URL escaping as the parameter to the built-in:</para>
<programlisting role="template"><a href="foo.cgi?x=${x?url<emphasis>('ISO-8895-2')</emphasis>}">foo</a></programlisting>
<para><phrase role="forProgrammers"><indexterm>
<primary>output encoding</primary>
</indexterm><indexterm>
<primary>output charset</primary>
</indexterm>If the <literal>url</literal> built-in has no
parameter, then it will use the charset specified as the value of
the <literal>url_escaping_charset</literal> setting. This setting
should be set by the software that encloses FreeMarker (e.g. a Web
application framework), because it is not set
(<literal>null</literal>) by default. If it is not set, then
FreeMarker falls back using the value of the
<literal>output_encoding</literal> setting, which is also not set by
default, so it is again the task of the enclosing software. If the
<literal>output_encoding</literal> setting is not set either, then
the parameterless <literal>url</literal> built-in can't be executed,
and it will cause execution time error. Of course, the
<literal>url</literal> built-in with parameter always
works.</phrase></para>
<para><phrase role="forProgrammers">It's possible to set
<literal>url_escaping_charset</literal> in the template with the
<literal>setting</literal> directive, but it is bad practice, at
least in true MVC applications. The
<literal>output_encoding</literal> setting can't be set with the
<literal>setting</literal> directive, so that's surely the task of
the enclosing software. You may find more information regarding this
<link linkend="pgui_misc_charset">here...</link></phrase></para>
</section>
<section xml:id="ref_builtin_split">
<title>split</title>
<indexterm>
<primary>split built-in</primary>
</indexterm>
<para>It is used to split a string into a sequence of strings along
the occurrences of another string. For example:</para>
<programlisting role="template"><#list "someMOOtestMOOtext"?split("MOO") as x>
- ${x}
</#list></programlisting>
<para>will print:</para>
<programlisting role="output">- some
- test
- text</programlisting>
<para>Note that it is assumed that all occurrences of the separator
is before a new item, thus:</para>
<programlisting role="template"><#list "some,,test,text,"?split(",") as x>
- "${x}"
</#list></programlisting>
<para>will print:</para>
<programlisting role="output">- "some"
- ""
- "test"
- "text"
- ""</programlisting>
<para><literal>split</literal> accepts an optional <link
linkend="ref_builtin_string_flags">flags parameter</link>, as its
2nd parameter.</para>
</section>
<section xml:id="ref_builtin_starts_with">
<title>starts_with</title>
<indexterm>
<primary>starts_with built-in</primary>
</indexterm>
<para>Returns if this string starts with the specified substring.
For example <literal>"redhead"?starts_with("red")</literal> returns
boolean true. Also, <literal>"red"?starts_with("red")</literal> will
return true.</para>
</section>
<section xml:id="ref_builtin_string_for_string">
<title>string (when used with a string value)</title>
<para>Does nothing, just returns the string as-is. The exception is
that if the value is a multi-type value (e.g. it is both string and
sequence at the same time), then the resulting value will be only a
simple string, not a multi-type value. This can be utilized to
prevent the artifacts of multi-typing.</para>
</section>
<section xml:id="ref_builtin_trim">
<title>trim</title>
<indexterm>
<primary>trim built-in</primary>
</indexterm>
<para>The string without leading and trailing white-space.
Example:</para>
<programlisting role="template">(${" green mouse "?trim})</programlisting>
<para>The output:</para>
<programlisting role="output">(green mouse)</programlisting>
</section>
<section xml:id="ref_builtin_upper_case">
<title>upper_case</title>
<indexterm>
<primary>upper_case built-in</primary>
</indexterm>
<para>The upper case version of the string. For example
<literal>"GrEeN MoUsE"</literal> will be <literal>"GREEN
MOUSE"</literal>.</para>
</section>
<section xml:id="ref_builtin_word_list">
<title>word_list</title>
<indexterm>
<primary>word_list built-in</primary>
</indexterm>
<para>A sequence that contains all words of the string in the order
as they appear in the string. Words are continual character
sequences that contain any character but <link
linkend="gloss.whiteSpace">white-space</link>. Example:</para>
<programlisting role="template"><#assign words = " a bcd, . 1-2-3"?word_list>
<#list words as word>[${word}]</#list>
</programlisting>
<para>will output:</para>
<programlisting role="output">[a][bcd,][.][1-2-3]</programlisting>
</section>
<section xml:id="ref_builtin_xhtml">
<title>xhtml</title>
<indexterm>
<primary>xhtml built-in</primary>
</indexterm>
<indexterm>
<primary>escaping</primary>
<secondary>output</secondary>
</indexterm>
<para>The string as XHTML text. That is, the string with all:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><</literal> replaced with
<literal>&lt;</literal></para>
</listitem>
<listitem>
<para><literal>></literal> replaced with
<literal>&gt;</literal></para>
</listitem>
<listitem>
<para><literal>&</literal> replaced with
<literal>&amp;</literal></para>
</listitem>
<listitem>
<para><literal>"</literal> replaced with
<literal>&quot;</literal></para>
</listitem>
<listitem>
<para><literal>'</literal> replaced with
<literal>&#39;</literal></para>
</listitem>
</itemizedlist>
<para>The only difference between this built-in and the
<literal>xml</literal> built-in is that the <literal>xhtml</literal>
built-in escapes <literal>'</literal> as
<literal>&#39;</literal> instead of as
<literal>&apos;</literal>, because some older browsers don't
interpret <literal>&apos;</literal> correctly.</para>
</section>
<section xml:id="ref_builtin_xml">
<title>xml</title>
<indexterm>
<primary>xml built-in</primary>
</indexterm>
<indexterm>
<primary>escaping</primary>
<secondary>output</secondary>
</indexterm>
<para>The string as XML text. That is, the string with all:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><</literal> replaced with
<literal>&lt;</literal></para>
</listitem>
<listitem>
<para><literal>></literal> replaced with
<literal>&gt;</literal></para>
</listitem>
<listitem>
<para><literal>&</literal> replaced with
<literal>&amp;</literal></para>
</listitem>
<listitem>
<para><literal>"</literal> replaced with
<literal>&quot;</literal></para>
</listitem>
<listitem>
<para><literal>'</literal> replaced with
<literal>&apos;</literal></para>
</listitem>
</itemizedlist>
</section>
<section xml:id="ref_builtin_string_flags">
<title>Common flags</title>
<para>Many string built-ins accept an optional string parameter, the
so called ``flags''. In this string, each letter influences a
certain aspect of the behavior of the built-in. For example, letter
<literal>i</literal> means that the built-in should not
differentiate the lower and upper-case variation of the same letter.
The order of the letters in the flags string is not
significant.</para>
<para>This is the complete list of letters (flags):</para>
<itemizedlist>
<listitem>
<para><literal>i</literal>: Case insensitive: do not
differentiate the lower and upper-case variation of the same
letter.</para>
</listitem>
<listitem>
<para><literal>f</literal>: First only. That is,
replace/find/etc. only the first occurrence of something.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>regular expression</primary>
<secondary>built-ins</secondary>
</indexterm> <literal>r</literal>: The substring to find is a
<link linkend="gloss.regularExpression">regular
expression</link>. FreeMarker uses the variation of regular
expressions described at <link
xlink:href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html</link>.
<emphasis>This flag will work only if you use Java2 platform 1.4
or later. Otherwise it will cause template processing to stop
with error.</emphasis></para>
</listitem>
<listitem>
<para><literal>m</literal>: Multi-line mode for regular
expressions. In multi-line mode the expressions
<literal>^</literal> and <literal>$</literal> match just after
or just before, respectively, a line terminator or the end of
the string. By default these expressions only match at the
beginning and the end of the entire string. Note that
<literal>^</literal> and <literal>$</literal> doesn't match the
line-break character itself. </para>
</listitem>
<listitem>
<para><literal>s</literal>: Enables dot-all mode for regular
expressions (same as Perl singe-line mode). In dot-all mode, the
expression <literal>.</literal> matches any character, including
a line terminator. By default this expression does not match
line terminators.</para>
</listitem>
<listitem>
<para><literal>c</literal>: Permits whitespace and comments in
regular expressions.</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting role="template"><#assign s = 'foo bAr baar'>
${s?replace('ba', 'XY')}
i: ${s?replace('ba', 'XY', 'i')}
if: ${s?replace('ba', 'XY', 'if')}
r: ${s?replace('ba*', 'XY', 'r')}
ri: ${s?replace('ba*', 'XY', 'ri')}
rif: ${s?replace('ba*', 'XY', 'rif')}</programlisting>
<para>This outputs this:</para>
<programlisting role="output">foo bAr XYar
i: foo XYr XYar
if: foo XYr baar
r: foo XYAr XYr
ri: foo XYr XYr
rif: foo XYr baar</programlisting>
<para>This is the table of built-ins that use these common flags,
and which supports which flags:</para>
<informaltable border="1">
<thead>
<tr>
<th>Built-in</th>
<th><literal>i</literal> (ignore case)</th>
<th><literal>r</literal> (reg. exp.)</th>
<th><literal>m</literal> (multi-line mode)</th>
<th><literal>s</literal> (dot-all mode)</th>
<th><literal>c</literal> (whitesp. and comments)</th>
<th><literal>f</literal> (first only)</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>replace</literal></td>
<td>Yes</td>
<td>Yes</td>
<td>Only with <literal>r</literal></td>
<td>Only with <literal>r</literal></td>
<td>Only with <literal>r</literal></td>
<td>Yes</td>
</tr>
<tr>
<td><literal>split</literal></td>
<td>Yes</td>
<td>Yes</td>
<td>Only with <literal>r</literal></td>
<td>Only with <literal>r</literal></td>
<td>Only with <literal>r</literal></td>
<td>No</td>
</tr>
<tr>
<td><literal>match</literal></td>
<td>Yes</td>
<td>Ignored</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
</tbody>
</informaltable>
</section>
</section>
<section xml:id="ref_builtins_number">
<title>Built-ins for numbers</title>
<indexterm>
<primary>number</primary>
<secondary>built-ins</secondary>
</indexterm>
<para>Related FAQs: Do you have things like 1,000,000 or 1 000 000
instead of 1000000, or something like 3.14 instead of 3,14 or vice
versa? See <link linkend="faq_number_grouping">this</link> and <link
linkend="faq_number_decimal_point">this</link> FAQ entry, also note
the <literal>c</literal> built-in above.</para>
<section xml:id="ref_builtin_c">
<title>c</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>format</primary>
<secondary>number</secondary>
</indexterm>
<note>
<para>This built-in exists since FreeMarker 2.3.3.</para>
</note>
<para>This built-in converts a number to string for ``computer
audience'' as opposed to human audience. That is, it formats with
the rules that programming languages used to use, which is
independent of all the locale and number format settings of
FreeMarker. It always uses dot as decimal separator, and it never
uses grouping separators (like 3,000,000), nor exponential form
(like 5E20), nor superfluous leading or trailing 0-s (like 03 or
1.0), nor + sign (like +1). It will print at most 16 digits after
the decimal dot, and thus numbers whose absolute value is less than
1E-16 will be shown as 0. This built-in is crucial because be
default (like with <literal>${x}</literal>) numbers are converted to
strings with the locale (language, country) specific number
formatting, which is for human readers (like 3000000 is possibly
printed as 3,000,000). When the number is printed not for human
audience (e.g., for a database record ID used as the part of an URL,
or as invisible field value in a HTML form, or for printing
CSS/JavaScript numerical literals) this built-in must be used to
print the number (i.e., use <literal>${x?c}</literal> instead of
<literal>${x}</literal>), or else the output will be possibly broken
depending on the current number formatting settings and locale (like
the decimal point is not dot, but comma in many countries) and the
value of the number (like big numbers are possibly ``damaged'' by
grouping separators).</para>
</section>
<section xml:id="ref_builtin_string_for_number">
<title>string (when used with a numerical value)</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>string built-in</primary>
</indexterm>
<indexterm>
<primary>format</primary>
<secondary>number</secondary>
</indexterm>
<para>Converts a number to a string. It uses the default format that
the programmer has specified. You can also specify a number format
explicitly with this built-in, as it will be shown later.</para>
<para>There are four predefined number formats:
<literal>computer</literal>, <literal>currency</literal>,
<literal>number</literal>, and <literal>percent</literal>. The exact
meaning of these is locale (nationality) specific, and is controlled
by the Java platform installation, rather than by FreeMarker, except
for <literal>computer</literal>, which uses the same formatting as
<link linkend="ref_builtin_c">the <literal>c</literal>
built-in</link>. You can use these predefined formats like
this:</para>
<programlisting role="template"><#assign x=42>
${x}
${x?string} <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}
${x?string.computer}</programlisting>
<para>If your locale is US English, this will certainly
produce:</para>
<programlisting role="output">42
42
42
$42.00
4,200%
42</programlisting>
<para>The output of first three expressions is identical because the
first two expressions use the default format, which is "number"
here. You can change this default using a setting:</para>
<programlisting role="template"><#setting number_format="currency">
<#assign x=42>
${x}
${x?string} <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}</programlisting>
<para>Will now output:</para>
<programlisting role="output">$42.00
$42.00
42
$42.00
4,200%</programlisting>
<para>since the default number format was set to "currency".</para>
<para>Beside the three predefined formats, you can use arbitrary
number format patterns written in <link
xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java
decimal number format syntax</link>:</para>
<programlisting role="template"><#assign x = 1.234>
${x?string("0")}
${x?string("0.#")}
${x?string("0.##")}
${x?string("0.###")}
${x?string("0.####")}
${1?string("000.00")}
${12.1?string("000.00")}
${123.456?string("000.00")}
${1.2?string("0")}
${1.8?string("0")}
${1.5?string("0")} <-- 1.5, rounded towards even neighbor
${2.5?string("0")} <-- 2.5, rounded towards even neighbor
${12345?string("0.##E0")}</programlisting>
<para>outputs this:</para>
<programlisting role="output">1
1.2
1.23
1.234
1.234
001.00
012.10
123.46
1
2
2 <-- 1.5, rounded towards even neighbor
2 <-- 2.5, rounded towards even neighbor
1.23E4</programlisting>
<para>Following the financial and statistics practice, the rounding
goes according the so called half-even rule, which means rounding
towards the nearest ``neighbor'', unless both neighbors are
equidistant, in which case, it rounds towards the even neighbor.
This was visible in the above example if you look at the rounding of
1.5 and of 2.5, as both were rounded to 2, since 2 is even, but 1
and 3 are odds.</para>
<para>Apart from the Java decimal syntax patterns, you can also
write <literal>${aNumber?string("currency")}</literal> and like,
that will do the same as
<literal>${aNumber?string.currency}</literal> and like.</para>
<para>As it was shown for the predefined formats earlier, the
default formatting of the numbers can be set in the template:</para>
<programlisting role="template"><#setting number_format="0.##">
${1.234}
</programlisting>
<para>outputs this:</para>
<programlisting role="output">1.23</programlisting>
<para>Note that the number formatting is locale sensitive:</para>
<programlisting role="template"><#setting locale="en_US">
US people write: ${12345678?string(",##0.00")}
<#setting locale="hu">
Hungarian people write: ${12345678?string(",##0.00")}</programlisting>
<para>outputs this:</para>
<programlisting role="output">US people write: 12,345,678.00
Hungarian people write: 12 345 678,00</programlisting>
</section>
<section xml:id="ref_builtin_rounding">
<title>round, floor, ceiling</title>
<indexterm>
<primary>rounding</primary>
</indexterm>
<indexterm>
<primary>floor built-in</primary>
</indexterm>
<indexterm>
<primary>ceiling built-in</primary>
</indexterm>
<indexterm>
<primary>round built-in</primary>
</indexterm>
<note>
<para>The rounding built-ins exist since FreeMarker 2.3.13.</para>
</note>
<para>Converts a number to a whole number using the specified
rounding rule:</para>
<itemizedlist>
<listitem>
<para><literal>round</literal>: Rounds to the nearest whole
number. If the number ends with .5, then it rounds upwards
(i.e., towards positive infinity)</para>
</listitem>
<listitem>
<para><literal>floor</literal>: Rounds the number downwards
(i.e., towards neagative infinity)</para>
</listitem>
<listitem>
<para><literal>ceiling</literal>: Rounds the number upwards
(i.e., towards positive infinity)</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting role="template"><#assign testlist=[
0, 1, -1, 0.5, 1.5, -0.5,
-1.5, 0.25, -0.25, 1.75, -1.75]>
<#list testlist as result>
${result} ?floor=${result?floor} ?ceiling=${result?ceiling} ?round=${result?round}
</#list></programlisting>
<para>Prints:</para>
<programlisting role="output"> 0 ?floor=0 ?ceiling=0 ?round=0
1 ?floor=1 ?ceiling=1 ?round=1
-1 ?floor=-1 ?ceiling=-1 ?round=-1
0.5 ?floor=0 ?ceiling=1 ?round=1
1.5 ?floor=1 ?ceiling=2 ?round=2
-0.5 ?floor=-1 ?ceiling=0 ?round=0
-1.5 ?floor=-2 ?ceiling=-1 ?round=-1
0.25 ?floor=0 ?ceiling=1 ?round=0
-0.25 ?floor=-1 ?ceiling=0 ?round=0
1.75 ?floor=1 ?ceiling=2 ?round=2
-1.75 ?floor=-2 ?ceiling=-1 ?round=-2</programlisting>
<para>These built-ins may be useful in pagination operations and
like. If you just want to <emphasis>display</emphasis> numbers in
rounded form, then you should rather use the <link
linkend="ref_builtin_string_for_number"><literal>string</literal>
built-in</link> or the <link
linkend="ref.setting.number_format"><literal>number_format</literal>
setting</link>.</para>
</section>
</section>
<section xml:id="ref_builtins_date">
<title>Built-ins for dates</title>
<indexterm>
<primary>date</primary>
<secondary>built-ins</secondary>
</indexterm>
<indexterm>
<primary>time</primary>
<secondary>built-ins</secondary>
</indexterm>
<section xml:id="ref_builtin_string_for_date">
<title>string (when used with a date value)</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>string built-in</primary>
</indexterm>
<indexterm>
<primary>format</primary>
<secondary>date</secondary>
</indexterm>
<indexterm>
<primary>converting date to string</primary>
</indexterm>
<indexterm>
<primary>converting time to string</primary>
</indexterm>
<indexterm>
<primary>time to string</primary>
</indexterm>
<indexterm>
<primary>date to string</primary>
</indexterm>
<para>This built-in converts a date to a string, with the specified
formatting. (when the default format dictated by the
<literal>date_format</literal>, <literal>time_format</literal> and
<literal>datetime_format</literal> <link
linkend="ref.directive.setting">settings</link> of FreeMarker are
good for you, then you do not need this built-in.)</para>
<para>The format can be one of the predefined formats, or you can
specify the formatting pattern explicitly.</para>
<para>The predefined formats are <literal>short</literal>,
<literal>medium</literal>, <literal>long</literal>, and
<literal>full</literal> which define how verbose the resulting text
will be. For example, if the locale of the output is U.S. English,
and the time zone is the U.S. Pacific Time zone, then this:</para>
<programlisting role="template">${openingTime?string.short}
${openingTime?string.medium}
${openingTime?string.long}
${openingTime?string.full}
${nextDiscountDay?string.short}
${nextDiscountDay?string.medium}
${nextDiscountDay?string.long}
${nextDiscountDay?string.full}
${lastUpdated?string.short}
${lastUpdated?string.medium}
${lastUpdated?string.long}
${lastUpdated?string.full}</programlisting>
<para>will prints something like this:</para>
<programlisting role="output">12:45 PM
12:45:09 PM
12:45:09 PM CEST
12:45:09 PM CEST
4/20/07
Apr 20, 2007
April 20, 2007
Friday, April 20, 2007
4/20/07 12:45 PM
Apr 20, 2007 12:45:09 PM
April 20, 2007 12:45:09 PM CEST
Friday, April 20, 2007 12:45:09 PM CEST</programlisting>
<para>The exact meaning of <literal>short</literal>,
<literal>medium</literal>, <literal>long</literal>, and
<literal>full</literal> depends on the current locale (language).
Furthermore, it is specified not by FreeMarker, but the Java
platform implementation you run FreeMarker on.</para>
<para>For dates that contains both date and time part, you can
specify the length of the date and time part independently:</para>
<programlisting role="template">${lastUpdated?string.short_long} <#-- short date, long time -->
${lastUpdated?string.medium_short} <#-- medium date, short time --></programlisting>
<para>will output:</para>
<programlisting role="output">4/8/03 9:24:44 PM PDT
Apr 8, 2003 9:24 PM</programlisting>
<para>Note that <literal>?string.short</literal> is the same as
<literal>?string.short_short</literal>,
<literal>?string.medium</literal> is the same as
<literal>?string.medium_medium</literal>, etc.</para>
<warning>
<para>Unfortunately, because of the limitations of the Java
platform, it can happen that you have date variables in the
data-model, where FreeMarker can't decide if the variable stores
only date part (year, month, day), only time part (hour, minute,
second, millisecond) or both. In this case, FreeMarker don't know
how to display the date when you write something like
<literal>${lastUpdated?string.short}</literal> or simply
<literal>${lastUpdated}</literal>, and thus it will stop with
error. To prevent this, you can help FreeMarker with the <link
linkend="ref_builtin_date_datetype"><literal>?date</literal>,
<literal>?time</literal> and <literal>?datetime</literal>
built-ins</link>. For example:
<literal>${lastUpdated?datetime?string.short}</literal>. Ask the
programmer if certain variables of the data-model has this
problem, or always use <literal>?date</literal>,
<literal>?time</literal> and <literal>?datetime</literal>
built-ins.</para>
</warning>
<para>Instead of using the predefined formats, you can specify the
formatting pattern explicitly with
<literal>?string(<replaceable>pattern_string</replaceable>)</literal>.
The pattern uses <link
xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html">Java
date format syntax</link>. Example:</para>
<programlisting role="template">${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")}
${lastUpdated?string("EEE, MMM d, ''yy")}
${lastUpdated?string("EEEE, MMMM dd, yyyy, hh:mm:ss a '('zzz')'")}</programlisting>
<para>will output:</para>
<programlisting role="output">2003-04-08 21:24:44 Pacific Daylight Time
Tue, Apr 8, '03
Tuesday, April 08, 2003, 09:24:44 PM (PDT)</programlisting>
<note>
<para>Unlike with the predefined formats, you never need to use
<literal>?date</literal>, <literal>?time</literal> and
<literal>?datetime</literal> with explicitly given patterns, since
with the pattern you tell FreeMarker what parts of the date to
show. However, FreeMarker will trust you blindly, so you can show
"noise" if you display parts that are actually not stored in the
variable. For example, <literal>${openingTime?string("yyyy-MM-dd
hh:mm:ss a")}</literal>, where <literal>openingTime</literal>
stores only time, will display <literal>1970-01-01 09:24:44
PM</literal>.</para>
</note>
<para>The pattern string also can be <literal>"short"</literal>,
<literal>"medium"</literal>, ..., <literal>"short_medium"</literal>,
...etc. These are the same as if you would use the predefined
formats with the dot syntax:
<literal>someDate?string("short")</literal> and
<literal>someDate?string.short</literal> are equivalent.</para>
<para>See also: <link
linkend="dgui_template_valueinserion_universal_date">the
interpolation of dates</link></para>
</section>
<section xml:id="ref_builtin_date_datetype">
<title>date, time, datetime (when used with a date value)</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>date built-in</primary>
</indexterm>
<indexterm>
<primary>time built-in</primary>
</indexterm>
<indexterm>
<primary>datetime built-in</primary>
</indexterm>
<para>These built-ins can be used to specify which parts of the date
variable are in use:</para>
<itemizedlist>
<listitem>
<para><literal>date</literal>: Only the year, month and day
parts are used.</para>
</listitem>
<listitem>
<para><literal>time</literal>: Only the hour, minute, second and
millisecond parts are used.</para>
</listitem>
<listitem>
<para><literal>datetime</literal>: Both the date and the time
parts are used.</para>
</listitem>
</itemizedlist>
<para>In optimal case, you do not need to use these built-ins.
Unfortunately, because of the technical limitations of the Java
platform, FreeMarker sometimes can't find out which parts of the
date are in use (i.e. only the year+month+day, or only
hour+minute+second+millisecond, or both); ask the programmers which
variables has this problem. If FreeMarker has to execute an
operation where this information is needed -- such as displaying the
date as text -- but it does not know which parts are in use, it will
stop with error. This is when you have to use these built-ins. For
example, assume <literal>openingTime</literal> is a such problematic
variable:</para>
<programlisting role="template"><#assign x = openingTime> <#-- no problem can occur here -->
${openingTime?time} <#-- without ?time it would fail -->
<#-- For the sake of better understanding, consider this: -->
<#assign openingTime = openingTime?time>
${openingTime} <#-- this will work now --></programlisting>
<para>There is another usage of these built-ins: to truncate dates.
For example:</para>
<programlisting role="template">Last updated: ${lastUpdated} <#-- assume that lastUpdated is a date-time value -->
Last updated date: ${lastUpdated?date}
Last updated time: ${lastUpdated?time}</programlisting>
<para>will output something like:</para>
<programlisting role="output">Last updated: 04/25/2003 08:00:54 PM
Last updated date: 04/25/2003
Last updated time: 08:00:54 PM</programlisting>
<para>If the left side of the <literal>?</literal> is string, then
these built-ins <link linkend="ref_builtin_string_date">convert
strings to date variable</link>.</para>
</section>
<section xml:id="ref_builtin_date_iso">
<title>iso_...</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>iso built-in</primary>
</indexterm>
<indexterm>
<primary>iso_... built-ins</primary>
</indexterm>
<indexterm>
<primary>format</primary>
<secondary>date</secondary>
</indexterm>
<indexterm>
<primary>converting date to string</primary>
</indexterm>
<indexterm>
<primary>converting time to string</primary>
</indexterm>
<indexterm>
<primary>time to string</primary>
</indexterm>
<indexterm>
<primary>date to string</primary>
</indexterm>
<indexterm>
<primary>ISO 8601</primary>
</indexterm>
<para>These built-ins convert a date, time or date-time value to
string that follows ISO 8601 "extended" format. This built-in has
several variations: <literal>iso_utc</literal>,
<literal>iso_local</literal>, <literal>iso_utc_nz</literal>,
<literal>iso_local_nz</literal>, <literal>iso_utc_m</literal>,
<literal>iso_utc_m_nz</literal>, etc. The name is constructed from
the following words in this order, each separated with a
<literal>_</literal> from the next:</para>
<orderedlist>
<listitem>
<para><literal>iso</literal> (required)</para>
</listitem>
<listitem>
<para>Either <literal>utc</literal> or <literal>local</literal>
(required (except when it's given with a parameter, but see that
later)): Specifies whether you want to print the date according
to UTC or according the current time zone. The current time zone
is decided by the <literal>time_zone</literal> FreeMarker
setting and is normally configured by the programmers outside
the templates (but it can also be set in a template, like
<literal><#setting time_zone="America/New_York"></literal>
for example).</para>
</listitem>
<listitem>
<para>Either <literal>h</literal> or <literal>m</literal> or
<literal>ms</literal> (optional): The accuracy of the time part.
When omitted, it defaults to seconds accuracy (like
<literal>12:30:18</literal>). <literal>h</literal> means hours
accuracy (like <literal>12</literal>), <literal>m</literal>
means minutes accuracy (<literal>12:30</literal>), and
<literal>ms</literal> means milliseconds accuracy
(<literal>12:30:18.25</literal>, where we have 250 ms). Note
that when using <literal>ms</literal>, the milliseconds are
displayed as fraction seconds (following the standard) and will
not have trailing <literal>0</literal>-s. Thus, if the the
millisecond part happens to be <literal>0</literal>, the whole
fraction second part will be omitted. Also note that the
fraction seconds are always separated with a dot (following the
Web and XSD conventions), not with comma.</para>
</listitem>
<listitem>
<para><literal>nz</literal> (optional): When present, the time
zone offset (like <literal>+02</literal> or or
<literal>-04:30</literal> or <literal>Z</literal>) will not be
displayed. Otherwise it will be displayed, except for date-only
values.</para>
</listitem>
</orderedlist>
<para>Example:</para>
<programlisting role="template"><#assign aDateTime = .now>
<#assign aDate = aDateTime?date>
<#assign aTime = aDateTime?time>
Basic formats:
${aDate?iso_utc}
${aTime?iso_utc}
${aDateTime?iso_utc}
Different accuracies:
${aTime?iso_utc_ms}
${aDateTime?iso_utc_m}
Local time zone:
${aDateTime?iso_local}</programlisting>
<para>A possible output (depends on current time and time
zone):</para>
<programlisting role="output">Basic formats:
2011-05-16
21:32:13Z
2011-05-16T21:32:13Z
Different accuracies:
21:32:13.868Z
2011-05-16T21:32Z
Local time zone:
2011-05-16T23:32:13+02</programlisting>
<para>There is yet another group of <literal>iso_...</literal>
built-in variants, where you omit the <literal>local</literal> or
<literal>utc</literal> word from the name and instead specify the
time zone as a parameter to the built-in. Example:</para>
<programlisting role="template"><#assign aDateTime = .now>
${aDateTime?iso("UTC")}
${aDateTime?iso("GMT-02:30")}
${aDateTime?iso("Europe/Rome")}
The usual variations are supported:
${aDateTime?iso_m("GMT+02")}
${aDateTime?iso_m_nz("GMT+02")}
${aDateTime?iso_nz("GMT+02")}</programlisting>
<para>A possible output (depends on current time and time
zone):</para>
<programlisting role="output">2011-05-16T21:43:58Z
2011-05-16T19:13:58-02:30
2011-05-16T23:43:58+02
The usual variations are supported:
2011-05-16T23:43+02
2011-05-16T23:43
2011-05-16T23:43:58</programlisting>
<para>If the time zone parameter can't be interpreted, the template
processing will be terminated with error.</para>
<para role="forProgrammers">The parameter can be a
<literal>java.util.TimeZone</literal> object too (which is possibly
the return value of a Java method, or it's in the date-model), not
just a string.</para>
</section>
</section>
<section xml:id="ref_builtins_boolean">
<title>Built-ins for booleans</title>
<indexterm>
<primary>boolean</primary>
<secondary>built-ins</secondary>
</indexterm>
<section xml:id="ref_builtin_string_for_boolean">
<title>string (when used with a boolean value)</title>
<indexterm>
<primary>boolean</primary>
<secondary>printing</secondary>
</indexterm>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>string built-in</primary>
</indexterm>
<indexterm>
<primary>format</primary>
<secondary>boolean</secondary>
</indexterm>
<para>Converts a boolean to a string. You can use it in two
ways:</para>
<itemizedlist>
<listitem>
<para>As <literal>foo?string</literal>: This will convert the
boolean to string using the default strings for representing
true and false values. By default, true is rendered as
<literal>"true"</literal> and false is rendered as
<literal>"false"</literal>. This is mostly useful if you
generate source code with FreeMarker, since the values are not
locale (language, country) sensitive. To change these default
strings, you can use the <literal>boolean_format</literal> <link
linkend="ref_directive_setting">setting</link>. Note, that if
the variable is multi-type variable that is both boolean and
string, then the string value of the variable will be
returned.</para>
</listitem>
<listitem>
<para>As <literal>foo?string("yes", "no")</literal>: This will
return the first parameter (here: <literal>"yes"</literal>) if
the boolean is true, otherwise the second parameter (here:
<literal>"no"</literal>). Note that the return value is always a
string; if the parameters were numbers, they would be converted
to strings first.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="ref_builtins_sequence">
<title>Built-ins for sequences</title>
<indexterm>
<primary>sequence</primary>
<secondary>built-ins</secondary>
</indexterm>
<section xml:id="ref_builtin_first">
<title>first</title>
<indexterm>
<primary>first built-in</primary>
</indexterm>
<para>The first subvariable of the sequence. Template processing
will die with error if the sequence is empty.</para>
</section>
<section xml:id="ref_builtin_last">
<title>last</title>
<indexterm>
<primary>last built-in</primary>
</indexterm>
<para>The last subvariable of the sequence. Template processing will
die with error if the sequence is empty.</para>
</section>
<section xml:id="ref_builtin_seq_contains">
<title>seq_contains</title>
<indexterm>
<primary>seq_contains built-in</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<note>
<para>The <literal>seq_</literal> prefix is required in the
built-in name to differentiate it from the <link
linkend="ref_builtin_contains"><literal>contains</literal>
built-in</link> that searches a substring in a string (since a
variable can be both string and sequence on the same time).</para>
</note>
<para>Tells if the sequence contains the specified value. It has 1
parameter, the value to find. Example:</para>
<programlisting role="template"><#assign x = ["red", 16, "blue", "cyan"]>
"blue": ${x?seq_contains("blue")?string("yes", "no")}
"yellow": ${x?seq_contains("yellow")?string("yes", "no")}
16: ${x?seq_contains(16)?string("yes", "no")}
"16": ${x?seq_contains("16")?string("yes", "no")}</programlisting>
<para>The output will be:</para>
<programlisting role="output">"blue": yes
"yellow": no
16: yes
"16": no</programlisting>
<para>To find the value the built-in uses FreeMarker's comparison
rules (as if you was using <link
linkend="dgui_template_exp_comparison"><literal>==</literal>
operator</link>), except that comparing two values of different
types or of types for which FreeMarker doesn't support comparison
will not cause error, just will be evaluated as the two values are
not equal. Thus, you can use it only to find scalar values (i.e.
string, number, boolean or date/time values). For other types the
result will be always <literal>false</literal>.</para>
<para>For fault tolerance, this built-in also works with
collections.</para>
</section>
<section xml:id="ref_builtin_seq_index_of">
<title>seq_index_of</title>
<indexterm>
<primary>seq_index_of built-in</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<note>
<para>The <literal>seq_</literal> prefix is required in the
built-in name to differentiate it from the <link
linkend="ref_builtin_index_of"><literal>index_of</literal>
built-in</link> that searches a substring in a string (since a
variable can be both string and sequence on the same time).</para>
</note>
<para>Returns the index of the first occurrence of a value in the
sequence, or <literal>-1</literal> if the sequence doesn't contain
the specified value. The value to find is specified as the first
parameter. For example this template:</para>
<programlisting role="template"><#assign colors = ["red", "green", "blue"]>
${colors?seq_index_of("blue")}
${colors?seq_index_of("red")}
${colors?seq_index_of("purple")}</programlisting>
<para>will output this:</para>
<programlisting role="output">2
0
-1</programlisting>
<para>To find the value the built-in uses FreeMarker's comparison
rules (as if you was using <link
linkend="dgui_template_exp_comparison"><literal>==</literal>
operator</link>), except that comparing two values of different
types or of types for which FreeMarker doesn't support comparison
will not cause error, just will be evaluated as the two values are
not equal. Thus, you can use it only to find scalar values (i.e.
string, number, boolean or date/time values). For other types the
result will be always <literal>-1</literal>.</para>
<para>The index where the searching is started can be optionally
given as the 2nd parameter. This may be useful if the same item can
occur for multiple times in the same sequence. There is no
restriction on the numerical value of the second parameter: if it is
negative, it has the same effect as if it were zero, and if it is
greater than the length of the sequence, it has the same effect as
if it were equal to the length of the sequence. Decimal values will
be truncated to integers. For example:</para>
<programlisting role="template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_index_of("Joe")}
-2: ${names?seq_index_of("Joe", -2)}
-1: ${names?seq_index_of("Joe", -1)}
0: ${names?seq_index_of("Joe", 0)}
1: ${names?seq_index_of("Joe", 1)}
2: ${names?seq_index_of("Joe", 2)}
3: ${names?seq_index_of("Joe", 3)}
4: ${names?seq_index_of("Joe", 4)}</programlisting>
<para>will output this:</para>
<programlisting role="output">No 2nd param: 0
-2: 0
-1: 0
0: 0
1: 2
2: 2
3: -1
4: -1</programlisting>
</section>
<section xml:id="ref_builtin_seq_last_index_of">
<title>seq_last_index_of</title>
<indexterm>
<primary>seq_last_index_of built-in</primary>
</indexterm>
<note>
<para>This built-in is available since FreeMarker 2.3.1. It
doesn't exist in 2.3.</para>
</note>
<note>
<para>The <literal>seq_</literal> prefix is required in the
built-in name to differentiate it from the <link
linkend="ref_builtin_last_index_of"><literal>last_index_of</literal>
built-in</link> that searches a substring in a string (since a
variable can be both string and sequence on the same time).</para>
</note>
<para>Returns the index of the last occurrence of a value in the
sequence, or <literal>-1</literal> if the sequence doesn't contain
the specified value. That is, it is the same as <link
linkend="ref_builtin_seq_index_of"><literal>seq_index_of</literal></link>,
just it searches backward starting from the last item of the
sequence. It also supports the optional 2nd parameter that specifies
the index where the searching is started. For example:</para>
<programlisting role="template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_last_index_of("Joe")}
-2: ${names?seq_last_index_of("Joe", -2)}
-1: ${names?seq_last_index_of("Joe", -1)}
0: ${names?seq_last_index_of("Joe", 0)}
1: ${names?seq_last_index_of("Joe", 1)}
2: ${names?seq_last_index_of("Joe", 2)}
3: ${names?seq_last_index_of("Joe", 3)}
4: ${names?seq_last_index_of("Joe", 4)}</programlisting>
<para>will output this:</para>
<programlisting role="output">No 2nd param: 2
-2: -1
-1: -1
0: 0
1: 0
2: 2
3: 2
4: 2</programlisting>
</section>
<section xml:id="ref_builtin_reverse">
<title>reverse</title>
<indexterm>
<primary>reverse built-in</primary>
</indexterm>
<para>The sequence with reversed order.</para>
</section>
<section xml:id="ref_builtin_size">
<title>size</title>
<indexterm>
<primary>size built-in</primary>
</indexterm>
<para>The number of subvariables in sequence (as a numerical value).
The highest possible index in sequence <literal>s</literal> is
<literal>s?size - 1</literal> (since the index of the first
subvariable is 0) assuming that the sequence has at least one
subvariable.</para>
</section>
<section xml:id="ref_builtin_sort">
<title>sort</title>
<indexterm>
<primary>sort built-in</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>sorting</secondary>
</indexterm>
<para>Returns the sequence sorted in ascending order. (For
descending order use this and then the <link
linkend="ref_builtin_reverse"><literal>reverse</literal> built
in</link>.) This will work only if all subvariables are strings, or
if all subvariables are numbers, or if all subvariables are date
values (date, time, or date+time), or if all subvariables are
booleans (since 2.3.17). If the subvariables are strings, it uses
locale (language) specific lexical sorting (which is usually not
case sensitive). For example:</para>
<programlisting role="template"><#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort>
<#list ls as i>${i} </#list></programlisting>
<para>will print (with US locale at least):</para>
<programlisting role="output">aardvark Barbara beetroot whale zeppelin</programlisting>
</section>
<section xml:id="ref_builtin_sort_by">
<title>sort_by</title>
<indexterm>
<primary>sort_by built-in</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>sorting</secondary>
</indexterm>
<para>Returns the sequence of hashes sorted by the given hash
subvariable in ascending order. (For descending order use this and
then the <link
linkend="ref_builtin_reverse"><literal>reverse</literal> built
in</link>.) The rules are the same as with the <link
linkend="ref_builtin_sort"><literal>sort</literal> built-in</link>,
except that the subvariables of the sequence must be hashes, and you
have to give the name of a hash subvariable that will decide the
order. For example:</para>
<programlisting role="template"><#assign ls = [
{"name":"whale", "weight":2000},
{"name":"Barbara", "weight":53},
{"name":"zeppelin", "weight":-200},
{"name":"aardvark", "weight":30},
{"name":"beetroot", "weight":0.3}
]>
Order by name:
<#list ls?sort_by("name") as i>
- ${i.name}: ${i.weight}
</#list>
Order by weight:
<#list ls?sort_by("weight") as i>
- ${i.name}: ${i.weight}
</#list></programlisting>
<para>will print (with US locale at least):</para>
<programlisting role="output">Order by name:
- aardvark: 30
- Barbara: 53
- beetroot: 0.3
- whale: 2000
- zeppelin: -200
Order by weight:
- zeppelin: -200
- beetroot: 0.3
- aardvark: 30
- Barbara: 53
- whale: 2000</programlisting>
<para>If the subvariable that you want to use for the sorting is on
a deeper level (that is, if it is a subvariable of a subvariable and
so on), then you can use a sequence as parameter, that specifies the
names of the subvariables that lead down to the desired subvariable.
For example:</para>
<programlisting role="template"><#assign members = [
{"name": {"first": "Joe", "last": "Smith"}, "age": 40},
{"name": {"first": "Fred", "last": "Crooger"}, "age": 35},
{"name": {"first": "Amanda", "last": "Fox"}, "age": 25}]>
Sorted by name.last:
<#list members?sort_by(['name', 'last']) as m>
- ${m.name.last}, ${m.name.first}: ${m.age} years old
</#list></programlisting>
<para>will print (with US locale at least):</para>
<programlisting role="output">Sorted by name.last:
- Crooger, Fred: 35 years old
- Fox, Amanda: 25 years old
- Smith, Joe: 40 years old</programlisting>
</section>
<section xml:id="ref_builtin_chunk">
<title>chunk</title>
<indexterm>
<primary>chunk built-in</primary>
</indexterm>
<indexterm>
<primary>tabular printing of sequences</primary>
</indexterm>
<indexterm>
<primary>columnar printing of sequences</primary>
</indexterm>
<note>
<para>This built-in exists since FreeMarker 2.3.3.</para>
</note>
<para>This built-in splits a sequence into multiple sequences of the
size given with the 1st parameter to the built-in (like
<literal>mySeq?chunk(3)</literal>). The result is the sequence of
these sequences. The last sequence is possibly shorter than the
given size, unless the 2nd parameter is given (like
<literal>mySeq?chunk(3, '-')</literal>), that is the item used to
make up the size of the last sequence to the given size.
Example:</para>
<programlisting role="template"><#assign seq = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']>
<#list seq?chunk(4) as row>
<#list row as cell>${cell} </#list>
</#list>
<#list seq?chunk(4, '-') as row>
<#list row as cell>${cell} </#list>
</#list></programlisting>
<para>The output will be:</para>
<programlisting role="output">
a b c d
e f g h
i j
a b c d
e f g h
i j - -
</programlisting>
<para>This built in is mostly for outputting sequnces in
tabular/columnar format. When used with HTML tables, the 2nd
parameter is often <literal>"\xA0"</literal> (that is the code of
the no-break space character, also known as ``nbsp''), so the border
of the empty TD-s will not be missing.</para>
<para>The 1st parameter must be a number that is at least 1. If the
number is not integer, it will be silently rounded down to integer
(i.e. both 3.1 and 3.9 will be rounded to 3). The 2nd parameter can
be of any type and value.</para>
</section>
</section>
<section xml:id="ref_builtins_hash">
<title>Built-ins for hashes</title>
<indexterm>
<primary>hash</primary>
<secondary>built-ins</secondary>
</indexterm>
<section xml:id="ref_builtin_keys">
<title>keys</title>
<indexterm>
<primary>keys built-in</primary>
</indexterm>
<para>A sequence that contains all the lookup keys in the hash. Note
that not all hashes support this (ask the programmer if a certain
hash allows this or not).</para>
<programlisting role="template"><#assign h = {"name":"mouse", "price":50}>
<#assign keys = h?keys>
<#list keys as key>${key} = ${h[key]}; </#list></programlisting>
<para>Output:</para>
<programlisting role="output">name = mouse; price = 50;</programlisting>
<para>Since hashes do not define an order for their subvariables in
general, the order in which key names are returned can be arbitrary.
However, some hashes maintain a meaningful order (ask the programmer
if a certain hash does that or not). For example, hashes created
with the above <literal>{<replaceable>...</replaceable>}</literal>
syntax preserve the same order as you have specified the
subvariables.</para>
</section>
<section xml:id="ref_builtin_values">
<title>values</title>
<indexterm>
<primary>values built-in</primary>
</indexterm>
<para>A sequence that contains all the variables in the hash. Note
that not all hashes support this (ask the programmer if a certain
hash allows this or not).</para>
<para>As of the order in which the values are returned, the same
applies as with the <literal>keys</literal> built-in; see
there.</para>
</section>
</section>
<section xml:id="ref_builtins_node">
<title>Built-ins for nodes (for XML)</title>
<indexterm>
<primary>node</primary>
<secondary>built-ins</secondary>
</indexterm>
<para>Note that the variables returned by these built-ins are
generated by the node variable implementation it is used with. This
means that the returned variables can have extra features in
additional to what it stated here, for example, with the <link
linkend="xgui_expose_dom">XML DOM nodes</link> the sequence retuned by
the <literal>children</literal> built-in also can be used as hash and
maybe as string, as it is described in the <link linkend="xgui">part
about XML processing</link>.</para>
<section xml:id="ref_builtin_children">
<title>children</title>
<indexterm>
<primary>children built-in</primary>
</indexterm>
<para>A sequence that contains all of this node's child nodes (i.e.
immediate descendant nodes).</para>
<para>XML: This is almost the same as special hash key
<literal>*</literal>, except that it returns all nodes, not only
elements. So the possible children are element nodes, text nodes,
comment nodes, processing instruction nodes, etc. but
<emphasis>not</emphasis> attribute nodes. Attribute nodes are
excluded from the sequence.</para>
</section>
<section xml:id="ref_builtin_parent">
<title>parent</title>
<indexterm>
<primary>parent built-in</primary>
</indexterm>
<para>The node that is this node's immediate parent in the node
tree. The root node has no parent node, so for the root node, the
expression
<literal><replaceable>node</replaceable>?parent??</literal>
evaluates to <literal>false</literal>.</para>
<para>XML: Note that the value returned by this built-in is also a
sequence (same as the result of XPath expression
<literal>..</literal>, when you write
<literal>someNode[".."]</literal>). Also note that for attribute
nodes, it returns the element the attribute belongs to, despite that
attribute nodes are not counted as children of the element.</para>
</section>
<section xml:id="ref_builtin_root">
<title>root</title>
<indexterm>
<primary>root built-in</primary>
</indexterm>
<para>The node that is the root of the tree of nodes to which this
node belongs.</para>
<para>XML: According to W3C, the root of an XML document is not the
topmost element node, but the document itself, which is the parent
of the topmost element. For example, if you want to get the topmost
<emphasis>element</emphasis> of the XML (the so called ``document
element''; do not mix it with the ``document''), which is called
<literal>foo</literal>, then you have to write
<literal>someNode?root.foo</literal>. If you write just
<literal>someNode?root</literal>, then you get the document itself,
and not the document element.</para>
</section>
<section xml:id="ref_builtin_ancestors">
<title>ancestors</title>
<indexterm>
<primary>ancestors built-in</primary>
</indexterm>
<para>A sequence that contains all the node's ancestors, starting
with the immediate parent and ending with the root node. The result
of this built-in is also a method, by which you can filter the
result with the <link
linkend="gloss.fullQualifiedName">full-qualified name</link> of the
node. For example as <literal>node?ancestors("section")</literal> to
get the sequence of all ancestors with name
<literal>section</literal>.</para>
</section>
<section xml:id="ref_builtin_node_name">
<title>node_name</title>
<indexterm>
<primary>node_name built-in</primary>
</indexterm>
<para>Returns the string that is used to determine what user-defined
directive to invoke to handle this node when it is ``visited''. See:
the <link linkend="ref.directive.visit">visit</link> and <link
linkend="ref.directive.recurse">recurse</link> directives.</para>
<para>XML: If the node is an element or attribute, then the string
will be the local (prefix free) name of the element or attribute.
Otherwise the name usually starts with <literal>@</literal> followed
by the node type. See <link linkend="misc.xguiTable">this
table</link>. Note that this node name is not the same as the node
name returned in the DOM API; the goal of FreeMarker node names is
to give the name of the used-defined directive that will process the
node.</para>
</section>
<section xml:id="ref_builtin_node_type">
<title>node_type</title>
<indexterm>
<primary>node_type built-in</primary>
</indexterm>
<para>A string that describes the type of node this is. FreeMarker
does not define the exact meaning of node type; it depends on what
your variables are modeling. It's possible that a node doesn't
support node type at all. In this case, the built-in evaluates to an
undefined value, so you can't use the returned value. (You can still
check if a node supports the type property with
<literal><replaceable>node</replaceable>?node_type??</literal>.)</para>
<para>XML: The possible values are: <literal>"attribute"</literal>,
<literal>"text"</literal>, <literal>"comment"</literal>,
<literal>"document_fragment"</literal>,
<literal>"document"</literal>, <literal>"document_type"</literal>,
<literal>"element"</literal>, <literal>"entity"</literal>,
<literal>"entity_reference"</literal>,
<literal>"notation"</literal>, <literal>"pi"</literal>. Note that a
there is no <literal>"cdata"</literal> type, because CDATA is
considered as plain text node.</para>
</section>
<section xml:id="ref_builtin_node_namespace">
<title>node_namespace</title>
<indexterm>
<primary>node_namespace built-in</primary>
</indexterm>
<para>Returns the namespace string of the node. FreeMarker does not
define the exact meaning of node namespace; it depends on what your
node variables are modeling. It's possible that a node doesn't have
any node namespace defined. In this case, the built-in should
evaluate to undefined variable (i.e.
<literal>node?<replaceable>node_namespace</replaceable>??</literal>
is <literal>false</literal>), so you can't use the returned
value.</para>
<para>XML: In the case of XML, it's the XML namespace URI (such as
<literal>"http://www.w3.org/1999/xhtml"</literal>). If an element or
attribute node does not use XML namespace, then this built-in
evaluates to an empty string. For other XML nodes this built-in
always return undefined variable.</para>
</section>
</section>
<section xml:id="ref_builtins_expert">
<title>Seldom used and expert built-ins</title>
<para>These are the built-ins that normally you should not use, but in
exceptional situations (debugging, advanced macros) they can be
useful. If you need to use these in your normal page templates, you
may revisit the data-model so you don't need to use these.</para>
<section xml:id="ref_builtin_numType">
<title>byte, double, float, int, long, short</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>byte built-in</primary>
</indexterm>
<indexterm>
<primary>double built-in</primary>
</indexterm>
<indexterm>
<primary>float built-in</primary>
</indexterm>
<indexterm>
<primary>int built-in</primary>
</indexterm>
<indexterm>
<primary>long built-in</primary>
</indexterm>
<indexterm>
<primary>short built-in</primary>
</indexterm>
<indexterm>
<primary>converting date to long</primary>
</indexterm>
<indexterm>
<primary>date to long</primary>
</indexterm>
<para>Returns a <literal>SimpleNumber</literal> which contains the
same value as the original variable, but uses
<literal>java.lang.<replaceable>Type</replaceable></literal> for the
internal representation of the value. This is useful if a method is
overloaded, or if a <literal>TemplateModel</literal> unwrapper has
problem with automatically choosing the suitable
<literal>java.lang.*</literal> type. Note that since version 2.3.9
the unwrapper has been improved substantially, so you will hardly
ever need to use these built-ins to convert between numerical types,
except for resolving ambiguity in overloaded method
invocation.</para>
<para>The <literal>long</literal> built-in can also be used with
date, time and date-time values to get the value as
<literal>java.util.Date.getTime()</literal> would return. This is
useful if you have to call a Java methods that expect a timestamp as
a <literal>long</literal>. This conversion is not automatic.</para>
</section>
<section xml:id="ref_builtin_numToDate">
<title>number_to_date, number_to_time, number_to_datetime</title>
<indexterm>
<primary>type-casting</primary>
</indexterm>
<indexterm>
<primary>converting between types</primary>
</indexterm>
<indexterm>
<primary>number_to_date built-in</primary>
</indexterm>
<indexterm>
<primary>number_to_datetime built-in</primary>
</indexterm>
<indexterm>
<primary>number_to_time built-in</primary>
</indexterm>
<indexterm>
<primary>converting long to date</primary>
</indexterm>
<indexterm>
<primary>long to date</primary>
</indexterm>
<para>These are used to convert a number (usually a Java
<literal>long</literal>) to a date, time or date-time, respectively.
This does them same as <literal>new java.util.Date(long)</literal>
in Java, that is, the number is interpreted as the milliseconds
passed since the epoch. The number can be anything and of any type
as far as its value fits into a <literal>long</literal>. If the
number isn't a whole number, it will be rounded to whole with
half-up rule. This conversion is not automatic.</para>
<para>Example:</para>
<programlisting role="template">${1305575275540?number_to_datetime}
${1305575275540?number_to_date}
${1305575275540?number_to_time}</programlisting>
<para>The output will be something like this (depending on the
current locale and time zone):</para>
<programlisting role="output">May 16, 2011 3:47:55 PM
May 16, 2011
3:47:55 PM</programlisting>
</section>
<section xml:id="ref_builtin_eval">
<title>eval</title>
<indexterm>
<primary>eval</primary>
</indexterm>
<indexterm>
<primary>evaluate string</primary>
</indexterm>
<para>This built-in evaluates a string as an FTL expression. For
example <literal>"1+2"?eval</literal> returns number 3.</para>
</section>
<section xml:id="ref_builtin_has_content">
<title>has_content</title>
<indexterm>
<primary>has_content built-in</primary>
</indexterm>
<para>It is <literal>true</literal> if the variable exists (and
isn't Java <literal>null</literal>) and is not ``empty'', otherwise
it is <literal>false</literal>. The meaning of ``empty'' depends on
the concrete case. This follows intuitive common-sense ideas. The
following are empty: a string with 0 length, sequence or hash with
no subvariables, a collection which has passed the last element. If
the value is not a string or sequence or hash or collection, then it
counts as non-empty if it's a number or a date or a boolean (e.g.
<literal>0</literal> and <literal>false</literal> are not empty),
otherwise it counts as empty. Note that when your data-model
implements multiple template model interfaces you may get unexpected
results. However, when in doubt you can use always use
<literal>expr!?size > 0</literal> or <literal>expr!?length >
0</literal> instead of <literal>expr?has_content</literal>.</para>
<para>This buit-in is exceptional in that you can use the
parentheses trick like with the <link
linkend="dgui_template_exp_missing_default">default value
operator</link>. That is, you can write both
<literal>product.color?has_content</literal> and
<literal>(product.color)?has_content</literal>. The first doesn't
handle the case when <literal>product</literal> is missing, the last
does.</para>
</section>
<section xml:id="ref_builtin_interpret">
<title>interpret</title>
<indexterm>
<primary>interpret built-in</primary>
</indexterm>
<para>This built-in interprets a string as a FTL template, and
returns an user-defined directive that - when applied to any block -
executes the template just as if it was included at that point.
Example:</para>
<programlisting role="template"><#assign x=["a", "b", "c"]>
<#assign templateSource = r"<#list x as y>${y}</#list>">
<#-- Note: That r was needed so that the ${y} is not interpreted above -->
<#assign inlineTemplate = templateSource?interpret>
<@inlineTemplate /></programlisting>
<para>The output:</para>
<programlisting role="output">abc</programlisting>
<para>As you can see, <literal>inlineTemplate</literal> is a
user-defined directive that, when executed, runs the template that
was generated on-the-fly using the
<literal>interpret</literal>.</para>
<para>You can also apply this built-in to a two-element sequence. In
this case the first element of the sequence is the template source,
and the second element is a name for the inline template. It can be
useful to give an explicit name to the inline template for debugging
purposes. So, you could have written:</para>
<programlisting role="template"><#assign inlineTemplate = [templateSource, "myInlineTemplate"]?interpret></programlisting>
<para>as well in the above template. Note that giving the inline
template a name has no immediate effect - it is only useful as an
extra bit of information if you get an error report.</para>
</section>
<section xml:id="ref_builtin_isType">
<title>is_...</title>
<indexterm>
<primary>is_... built-in</primary>
</indexterm>
<indexterm>
<primary>type checking</primary>
</indexterm>
<para>These built-ins check the type of a variable, and returns
<literal>true</literal> or <literal>false</literal> depending on the
type. The list of
<literal>is_<replaceable>...</replaceable></literal>
built-ins:</para>
<informaltable border="1">
<thead>
<tr>
<th>Built-in</th>
<th>Returns <literal>true</literal> if the value is a ...</th>
</tr>
</thead>
<tbody>
<tr>
<td><literal>is_string</literal></td>
<td>string</td>
</tr>
<tr>
<td><literal>is_number</literal></td>
<td>number</td>
</tr>
<tr>
<td><literal>is_boolean</literal></td>
<td>boolean</td>
</tr>
<tr>
<td><literal>is_date</literal></td>
<td>date (all types: date-only, time-only and date-time)</td>
</tr>
<tr>
<td><literal>is_method</literal></td>
<td>method</td>
</tr>
<tr>
<td><literal>is_transform</literal></td>
<td>transform</td>
</tr>
<tr>
<td><literal>is_macro</literal></td>
<td>macro</td>
</tr>
<tr>
<td><literal>is_hash</literal></td>
<td>hash</td>
</tr>
<tr>
<td><literal>is_hash_ex</literal></td>
<td>extended hash (i.e. supports <literal>?keys</literal> and
<literal>?values</literal>)</td>
</tr>
<tr>
<td><literal>is_sequence</literal></td>
<td>sequence</td>
</tr>
<tr>
<td><literal>is_collection</literal></td>
<td>collection</td>
</tr>
<tr>
<td><literal>is_enumerable</literal></td>
<td>sequence or collection</td>
</tr>
<tr>
<td><literal>is_indexable</literal></td>
<td>sequence</td>
</tr>
<tr>
<td><literal>is_directive</literal></td>
<td>Whatever kind of directive (for example a macro, <phrase
role="forProgrammers">or
<literal>TemplateDirectiveModel</literal>,
<literal>TemplateTransformModel</literal>, etc.</phrase>)</td>
</tr>
<tr>
<td><literal>is_node</literal></td>
<td>node</td>
</tr>
</tbody>
</informaltable>
</section>
<section xml:id="ref_builtin_namespace">
<title>namespace</title>
<indexterm>
<primary>namespace built-in</primary>
</indexterm>
<para>This built-in returns the namespace (i.e. the ``gate'' hash to
the namespace) associated with a macro variable. You can use it with
macros only.</para>
</section>
<section xml:id="ref_builtin_new">
<title>new</title>
<indexterm>
<primary>instantiating variable</primary>
</indexterm>
<indexterm>
<primary>new built-in</primary>
</indexterm>
<para>This is to create a variable of a certain
<literal>TemplateModel</literal> implementation.</para>
<para>On the left side of <literal>?</literal> you specify a string,
the full-qualified class name of a <literal>TemplateModel</literal>
implementation. The result is a method variable that calls the
constructor, and returns the new variable.</para>
<para>Example:</para>
<programlisting role="template"><#-- Creates an user-defined directive be calling the parameterless constructor of the class -->
<#assign word_wrapp = "com.acmee.freemarker.WordWrapperDirective"?new()>
<#-- Creates an user-defined directive be calling the constructor with one numerical argument -->
<#assign word_wrapp_narrow = "com.acmee.freemarker.WordWrapperDirective"?new(40)></programlisting>
<para>For more information about how the constructor parameters are
unwrapped and how overloaded constructor is chosen, read: <xref
linkend="pgui_misc_beanwrapper" /></para>
<para>This built-in can be a security concern because the template
author can create arbitrary Java objects and then use them, as far
as they implement <literal>TemplateModel</literal>. Also the
template author can trigger static initialization for classes that
don't even implement <literal>TemplateModel</literal>. You can
(since 2.3.17) restrict the classes accessible with this built-in
using
<literal>Configuration.setNewBuiltinClassResolver(TemplateClassResolver)</literal>
or the <literal>new_builtin_class_resolver</literal> setting. See
the Java API docs for more information. If you are allowing
not-so-much-trusted users to upload templates then you should
definitely look into this topic.</para>
</section>
</section>
</chapter>
<chapter xml:id="ref_directives">
<title>Directive Reference</title>
<indexterm>
<primary>directive</primary>
</indexterm>
<section xml:id="ref_directive_alphaidx">
<title>Alphabetical index</title>
<indexterm>
<primary>directive</primary>
</indexterm>
<itemizedlist spacing="compact">
<listitem>
<para><link linkend="ref.directive.assign">assign</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.attempt">attempt</link></para>
</listitem>
<listitem>
<para>break: <link linkend="ref.directive.switch.break">in
switch</link>, <link linkend="ref.directive.list.break">in
list</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.case">case</link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.compress">compress</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.default">default</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.else">else</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.elseif">elseif</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.escape">escape</link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.fallback">fallback</link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.function">function</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.flush">flush</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.ftl">ftl</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.global">global</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.if">if</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.import">import</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.include">include</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.list">list</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.local">local</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.lt">lt</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.macro">macro</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.nested">nested</link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.noescape">noescape</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.nt">nt</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.attempt">recover</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.recurse">recurse</link></para>
</listitem>
<listitem>
<para>return: <link linkend="ref.directive.macro.return">in
macro</link>, <link linkend="ref.directive.function.return">in
function</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.rt">rt</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.setting">setting</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.stop">stop</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.switch">switch</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.t">t</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.userDefined">User-defined
directive (<@...>)</link></para>
</listitem>
<listitem>
<para><link linkend="ref.directive.visit">visit</link></para>
</listitem>
</itemizedlist>
<para>If you don't find a directive here that you have seen in a
working template, probably you will find it in: <xref
linkend="ref_deprecated" /></para>
</section>
<section xml:id="ref_directive_if">
<title>if, else, elseif</title>
<anchor xml:id="ref.directive.if" />
<anchor xml:id="ref.directive.else" />
<anchor xml:id="ref.directive.elseif" />
<indexterm>
<primary>if directive</primary>
</indexterm>
<indexterm>
<primary>else directive</primary>
</indexterm>
<indexterm>
<primary>elseif directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#if <replaceable>condition</replaceable>>
<replaceable>...</replaceable>
<#elseif <replaceable>condition2</replaceable>>
<replaceable>...</replaceable>
<#elseif <replaceable>condition3</replaceable>>
<replaceable>...</replaceable>
<replaceable>...</replaceable>
<#else>
<replaceable>...</replaceable>
</#if></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>condition</replaceable></literal>,
<literal><replaceable>condition2</replaceable></literal>,
...etc.: Expression evaluates to a boolean value.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>You can use <literal>if</literal>, <literal>elseif</literal>
and <literal>else</literal> directives to conditionally skip a
section of the template. The
<literal><replaceable>condition</replaceable></literal>-s must
evaluate to a boolean value, or else an error will abort template
processing. The <literal>elseif</literal>-s and
<literal>else</literal>-s must occur inside <literal>if</literal>
(that is, between the <literal>if</literal> start-tag and end-tag).
The <literal>if</literal> can contain any number of
<literal>elseif</literal>-s (including 0) and at the end optionally
one <literal>else</literal>. Examples:</para>
<para><literal>if</literal> with 0 <literal>elseif</literal> and no
<literal>else</literal>:</para>
<programlisting role="template"><#if x == 1>
x is 1
</#if></programlisting>
<para><literal>if</literal> with 0 <literal>elseif</literal> and
<literal>else</literal>:</para>
<programlisting role="template"><#if x == 1>
x is 1
<#else>
x is not 1
</#if></programlisting>
<para><literal>if</literal> with 2 <literal>elseif</literal> and no
<literal>else</literal>:</para>
<programlisting role="template"><#if x == 1>
x is 1
<#elseif x == 2>
x is 2
<#elseif x == 3>
x is 3
</#if></programlisting>
<para><literal>if</literal> with 3 <literal>elseif</literal> and
<literal>else</literal>:</para>
<programlisting role="template"><#if x == 1>
x is 1
<#elseif x == 2>
x is 2
<#elseif x == 3>
x is 3
<#elseif x == 4>
x is 4
<#else>
x is not 1 nor 2 nor 3 nor 4
</#if></programlisting>
<para>To see more about boolean expressions, see: <xref
linkend="dgui_template_exp" />.</para>
<para>You can nest <literal>if</literal> directives (of
course):</para>
<programlisting role="template"><#if x == 1>
x is 1
<#if y == 1>
and y is 1 too
<#else>
but y is not
</#if>
<#else>
x is not 1
<#if y < 0>
and y is less than 0
</#if>
</#if></programlisting>
<note>
<para>How to test if x is greater than 1? <literal><#if x >
1></literal> will be <emphasis>wrong</emphasis>, as FreeMarker
will interpret the first <literal>></literal> as the end of the
tag. Thus, either write <literal><#if (x > 1)></literal>
or <literal><#if x &gt; 1></literal>.</para>
</note>
</section>
</section>
<section xml:id="ref_directive_switch">
<title>switch, case, default, break</title>
<anchor xml:id="ref.directive.switch" />
<anchor xml:id="ref.directive.case" />
<anchor xml:id="ref.directive.default" />
<anchor xml:id="ref.directive.switch.break" />
<indexterm>
<primary>switch directive</primary>
</indexterm>
<indexterm>
<primary>case directive</primary>
</indexterm>
<indexterm>
<primary>default directive</primary>
</indexterm>
<indexterm>
<primary>break directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#switch <replaceable>value</replaceable>>
<#case <replaceable>refValue1</replaceable>>
<replaceable>...</replaceable>
<#break>
<#case <replaceable>refValue2</replaceable>>
<replaceable>...</replaceable>
<#break>
<replaceable>...</replaceable>
<#case <replaceable>refValueN</replaceable>>
<replaceable>...</replaceable>
<#break>
<#default>
<replaceable>...</replaceable>
</#switch>
</literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>value</replaceable></literal>,
<literal><replaceable>refValue1</replaceable></literal>, etc.:
Expressions evaluates to scalars of the same type.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>The usage of this directive is not recommended, as it is
error-prone because of the fall-through behavior. Use <link
linkend="ref.directive.elseif"><literal>elseif</literal></link>-s
instead unless you want to exploit the fall-through behavior.</para>
<para>Switch is used to choose a fragment of template depending on
the value of an expression:</para>
<programlisting role="template"><#switch being.size>
<#case "small">
This will be processed if it is small
<#break>
<#case "medium">
This will be processed if it is medium
<#break>
<#case "large">
This will be processed if it is large
<#break>
<#default>
This will be processed if it is neither
</#switch></programlisting>
<para>Inside the <literal>switch</literal> must be one or more
<literal><#case <replaceable>value</replaceable>></literal>,
and after all such <literal>case</literal> tags optionally one
<literal><#default></literal>. When FM reaches the
<literal>switch</literal> directive, it chooses a
<literal>case</literal> directive where
<literal><replaceable>refValue</replaceable></literal> equals with
<literal><replaceable>value</replaceable></literal> and continues
the processing of the template there. If there is no
<literal>case</literal> directive with appropriate value then it
continues processing at the <literal>default</literal> directive if
that exists, otherwise it continues the processing after the end-tag
of <literal>switch</literal>. And now comes the confusing thing:
when it has chosen a <literal>case</literal> directive, it will
continue the processing there, and will go ahead until it reaches a
<literal>break</literal> directive. That is, it will not
automatically leave the <literal>switch</literal> directive when it
reaches another <literal>case</literal> directive or the
<literal><#default></literal> tag. Example:</para>
<programlisting role="template"><#switch x>
<#case x = 1>
1
<#case x = 2>
2
<#default>
d
</#switch></programlisting>
<para>If <literal>x</literal> is 1, then it will print 1 2 d; if
<literal>x</literal> is 2 then it will print 2 d; if
<literal>x</literal> is 3 then it will print d. This is the
mentioned fall-through behavior. The <literal>break</literal> tag
instructs FM to immediately skip past the <literal>switch</literal>
end-tag.</para>
</section>
</section>
<section xml:id="ref_directive_list">
<title>list, break</title>
<anchor xml:id="ref.directive.list" />
<indexterm>
<primary>list directive</primary>
</indexterm>
<indexterm>
<primary>break directive</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>iterate</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#list <replaceable>sequence</replaceable> as <replaceable>item</replaceable>>
<replaceable>...</replaceable>
</#list></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>sequence</replaceable></literal>:
Expressions evaluates to a sequence or collection</para>
</listitem>
<listitem>
<para><literal><replaceable>item</replaceable></literal>: Name
of the <link linkend="dgui_misc_var">loop variable</link> (not
an expression)</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>You can use the <literal>list</literal> directive to process a
section of template for each variable contained within a sequence.
The code between the start-tag and end-tag will be processed for the
1st subvariable, then for the 2nd subvariable, then for the 3rd
subvariable, etc until it passes the last one. For each such
iteration the loop variable will contain the current
subvariable.</para>
<para>There are two special loop variables available inside the list
loop:</para>
<itemizedlist>
<listitem>
<para><literal><replaceable>item</replaceable>_index</literal>:
This is a numerical value that contains the index of the current
item being stepped over in the loop.</para>
</listitem>
<listitem>
<para><literal><replaceable>item</replaceable>_has_next</literal>:
Boolean value that tells if the current item the last in the
sequence or not.</para>
</listitem>
</itemizedlist>
<para>Example 1:</para>
<programlisting role="template"><#assign seq = ["winter", "spring", "summer", "autumn"]>
<#list seq as x>
${<emphasis>x_index</emphasis> + 1}. ${x}<#if <emphasis>x_has_next</emphasis>>,</#if>
</#list></programlisting>
<para>will output:</para>
<programlisting role="output"> 1. winter,
2. spring,
3. summer,
4. autumn</programlisting>
<para>Example 2: You can use <literal>list</literal> to count
between two numbers, using a <link
linkend="dgui_template_exp_direct_seuqence">numerical range sequence
expression</link>:</para>
<programlisting role="template"><#assign x=3>
<#list 1..x as i>
${i}
</#list></programlisting>
<para>The output will be:</para>
<programlisting role="output"> 1
2
3
</programlisting>
<para>Note that the above example will not work as you may expected
if <literal>x</literal> is 0, as then it will print 0 and -1.</para>
<anchor xml:id="ref.directive.list.break" />
<para>You can leave the <literal>list</literal> loop before it
passes the last subvariable of the sequence with the
<literal>break</literal> directive. For example this will print
``winter'' and ``spring'' only:</para>
<programlisting role="template"><#list seq as x>
${x}
<#if x = "spring"><emphasis><#break></emphasis></#if>
</#list></programlisting>
<para><phrase role="forProgrammers">Note that if you turn on the
classic compatible mode, then the <literal>list</literal> accepts a
scalar as well and treats it as a single-element
sequence.</phrase></para>
<para><phrase role="forProgrammers">In general, it is best to avoid
using collection that wraps an <literal>Iterator</literal> as
parameters to <literal>list</literal> and use collection that wraps
<literal>java.util.Collection</literal> or sequence whenever
possible. There are situations however, when you only have an
<literal>Iterator</literal> at your disposal. Note that if you pass
an collection that wraps an <literal>Iterator</literal> to the
<literal>list</literal>, you can iterate over its elements only once
since <literal>Iterator</literal>s are by their nature one-off
objects. When you try to list a such collection variable for the
second time, an error will abort template
processing.</phrase></para>
</section>
</section>
<section xml:id="ref_directive_include">
<title>include</title>
<anchor xml:id="ref.directive.include" />
<indexterm>
<primary>include directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#include <replaceable>path</replaceable>></literal>
or
<literal><#include <replaceable>path</replaceable> <replaceable>options</replaceable>></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>path</replaceable></literal>: The
path of the file to include; an expression that evaluates to a
string. (With other words, it doesn't have to be a fixed string,
it can also be something like, for example,
<literal>profile.baseDir + "/menu.ftl"</literal>.)</para>
</listitem>
<listitem>
<para><literal><replaceable>options</replaceable></literal>: One
or more of these:
<literal>encoding=<replaceable>encoding</replaceable></literal>,
<literal>parse=<replaceable>parse</replaceable></literal></para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>encoding</replaceable></literal>:
Expression evaluates to string</para>
</listitem>
<listitem>
<para><literal><replaceable>parse</replaceable></literal>:
Expression evaluates to boolean (also accepts a few string
values for backward compatibility)</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>You can use it to insert another FreeMarker template file
(specified by the <literal><replaceable>path</replaceable></literal>
parameter) into your template. The output from the included template
is inserted at the point where the <literal>include</literal> tag
occurs. The included file shares the variables with the including
template, similarly like if it was copy-pasted into it. The
<literal>include</literal> directive is not replaced by the content
of the included file, it just processes the included file each time
when FreeMarker reaches the <literal>include</literal> directive in
the course of template processing. So for example if the
<literal>include</literal> is inside a <literal>list</literal>loop,
you can specify different file names in each cycle.</para>
<note>
<para>This directive is not be confused with the JSP (Servlet)
include, as it doesn't involve the Servlet container at all, just
processes another FreeMarker template, without "leaving"
FreeMarker. Regarding how to do a "JSP include" <link
linkend="faq_servlet_include">read this...</link></para>
</note>
<para>The <literal><replaceable>path</replaceable></literal>
parameter can be a relative path like <literal>"foo.ftl"</literal>
and <literal>"../foo.ftl"</literal>, or an absolute like
<literal>"/foo.ftl"</literal>. Relative paths are relative to the
directory of the template that uses the <literal>import</literal>
directive. Absolute paths are relative to a base (often referred as
the ''root directory of the templates'') that the programmer defines
when he configures FreeMarker.</para>
<note>
<para>This is different than the way it worked prior FreeMarker
2.1, where the path was always absolute. To preserve the old
behavior, enable the classic compatible mode in the
<literal>Configuration</literal> object.</para>
</note>
<para>Always use <literal>/</literal> (slash) to separate path
components, never <literal>\</literal> (backslash). If you are
loading templates from your local file system and it uses
backslashes (like under. Windows), FreeMarker will convert them
automatically.</para>
<para>Example:</para>
<para>Assume /common/copyright.ftl contains:</para>
<programlisting role="template">Copyright 2001-2002 ${me}<br>
All rights reserved.</programlisting>
<para>Then this:</para>
<programlisting role="template"><#assign me = "Juila Smith">
<h1>Some test</h1>
<p>Yeah.
<hr>
<emphasis><#include "/common/copyright.ftl"></emphasis></programlisting>
<para>will output this:</para>
<programlisting role="output"><h1>Some test</h1>
<p>Yeah.
<hr>
<emphasis>Copyright 2001-2002 Juila Smith
All rights reserved.</emphasis></programlisting>
<para>The supported
<literal><replaceable>options</replaceable></literal> are:</para>
<itemizedlist>
<listitem>
<para>parse: If it is true, then the included file will be
parsed as FTL, otherwise the whole file will be considered as
simple text (i.e, no FreeMarker constructs will be searched in
it). If you omit this option, then it defaults to true.</para>
</listitem>
<listitem>
<para>encoding: The included file inherits the encoding (in
practice: the charset) of the including template, unless you
specify an encoding with this option. <phrase
role="forProgrammers">Encoding names are the same as the ones
supported be java.io.InputStreamReader (as of Java API 1.3:
MIME-preferred charset names from the IANA Charset
Registry).</phrase> Examples of valid names: ISO-8859-2, UTF-8,
Shift_JIS, Big5, EUC-KR, GB2312.</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting role="template"><#include "/common/navbar.html" parse=false encoding="Shift_JIS"></programlisting>
<para><phrase role="forProgrammers">Note, that it is possible to
automatically do the commonly used inclusions for all templates,
with the "auto includes" setting of
<literal>Configuration</literal>.</phrase></para>
<section xml:id="ref_directive_include_acquisition">
<title>Using acquisition</title>
<indexterm>
<primary>acquisition</primary>
</indexterm>
<para>There's a special path component represented by an asterisk
(<literal>*</literal>). It is interpreted as "this directory or
any of its parents". Therefore, if the template located in
<literal>/foo/bar/template.ftl</literal> has the following
line:</para>
<programlisting role="template"><#include "*/footer.ftl"></programlisting>
<para>then the engine will look for the template in following
locations, in this order:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>/foo/bar/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/footer.ftl</literal></para>
</listitem>
</itemizedlist>
<para>This mechanism is called <emphasis
role="term">acquisition</emphasis> and allows the designers to
place commonly included files in a parent directory, and redefine
them on a per-subdirectory basis as needed. We say that the
including template acquires the template to include from the first
parent directory that has it. Note that you can specify not only a
template name to the right of the asterisk, but a subpath as well.
I.e. if the previous template instead read:</para>
<programlisting role="template"><#include "*/commons/footer.ftl"></programlisting>
<para>then the engine would look for the template in following
locations, in this order:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>/foo/bar/commons/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/commons/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/commons/footer.ftl</literal></para>
</listitem>
</itemizedlist>
<para>Finally, the asterisk needn't be the first element of the
path:</para>
<programlisting role="template"><#include "commons/*/footer.ftl"></programlisting>
<para>would cause the engine to look for the template in following
locations, in this order:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>/foo/bar/commons/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/bar/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/footer.ftl</literal></para>
</listitem>
</itemizedlist>
<para>However, there can be at most one asterisk in the path.
Specifying more than one asterisk will result in a template not
being found.</para>
</section>
<section xml:id="ref_directive_include_localized">
<title>Localized lookup</title>
<indexterm>
<primary>localization</primary>
</indexterm>
<para>Whenever a template is loaded, it is assigned a locale. A
locale is a language and an optional country or dialect
identifier. A template is typically loaded by some code that the
programmer wrote and he chooses a locale for the template based on
some aspect. For example, when the
<literal>FreemarkerServlet</literal> loads templates, it always
requests the template with locale matching the language preference
of the browser that requested the web page.</para>
<para>When a template includes another template, it attempts to
load a template with the same locale. Suppose your template was
loaded with locale <literal>en_US</literal>, which means U.S.
English. When you include another template:</para>
<programlisting role="template"><include "footer.ftl"></programlisting>
<para>the engine will in fact look for several templates, in this
order:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>footer_en_US.ftl</literal>,</para>
</listitem>
<listitem>
<para><literal>footer_en.ftl</literal>, and finally</para>
</listitem>
<listitem>
<para><literal>footer.ftl</literal></para>
</listitem>
</itemizedlist>
<para><phrase role="forProgrammers">Note that you can disable
localized lookup feature with the
<literal>setLocalizedLookup</literal> method of
<literal>Configuration</literal>.</phrase></para>
<para>When you use both acquisition and localized template lookup,
the template with more specific locale in a parent directory takes
precedence over template with less specific locale in a child
directory. Suppose you use the following include from
<literal>/foo/bar/template.ftl</literal>:</para>
<programlisting role="template"><#include "*/footer.ftl"></programlisting>
<para>the engine will look for these templates, in this
order:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>/foo/bar/footer_en_US.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/footer_en_US.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/footer_en_US.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/bar/footer_en.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/footer_en.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/footer_en.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/bar/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/foo/footer.ftl</literal></para>
</listitem>
<listitem>
<para><literal>/footer.ftl</literal></para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
<section xml:id="ref_directive_import">
<title>import</title>
<anchor xml:id="ref.directive.import" />
<indexterm>
<primary>import directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#import <replaceable>path</replaceable> as <replaceable>hash</replaceable>></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>path</replaceable></literal>: The
path of a template. This is an expression that evaluates to a
string. (With other words, it doesn't have to be a fixed string,
it can also be something like, for example,
<literal>profile.baseDir + "/menu.ftl"</literal>.)</para>
</listitem>
<listitem>
<para><literal><replaceable>hash</replaceable></literal>: The
unquoted name of hash variable by which you can access the
namespace. Not an expression.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>Imports a library. That is, it creates a new empty namespace,
and then executes the template given with
<literal><replaceable>path</replaceable></literal> parameter in that
namespace so the template populates the namespace with variables
(macros, functions, ...etc.). Then it makes the newly created
namespace available to the caller with a hash variable. The hash
variable will be created as a plain variable in the namespace used
by the caller of <literal>import</literal> (as if you would create
it with <literal>assign</literal> directive), with the name given
with the <literal><replaceable>hash</replaceable></literal>
parameter.</para>
<para>If you call <literal>import</literal> with the same
<literal><replaceable>path</replaceable></literal> for multiple
times, it will create the namespace and run the template for the
very first call of <literal>import</literal> only. The later calls
will just create a hash by which you can access the
<emphasis>same</emphasis> namespace.</para>
<para>The output printed by the imported template will be ignored
(will not be inserted at the place of importing). The template is
executed to populate the namespace with variables, and not to write
to the output.</para>
<para>Example:</para>
<programlisting role="template"><#import "/libs/mylib.ftl" as my>
<@my.copyright date="1999-2002"/></programlisting>
<para>The <literal><replaceable>path</replaceable></literal>
parameter can be a relative path like <literal>"foo.ftl"</literal>
and <literal>"../foo.ftl"</literal>, or an absolute like
<literal>"/foo.ftl"</literal>. Relative paths are relative to the
directory of the template that uses the <literal>import</literal>
directive. Absolute paths are relative to a base (often referred as
the ''root directory of the templates'') that the programmer defines
when he configures FreeMarker.</para>
<para>Always use <literal>/</literal> (slash) to separate path
components, never <literal>\</literal> (backslash). If you are
loading templates from your local file system and it uses
backslashes (like under. Windows), FreeMarker will convert them
automatically.</para>
<para>Like with the <literal>include</literal> directive, <link
linkend="ref_directive_include_acquisition">acquisition</link> and
<link linkend="ref_directive_include_localized">localized
lookup</link> may be used for resolving the path.</para>
<para><phrase role="forProgrammers">Note, that it is possible to
automatically do the commonly used imports for all templates, with
the "auto imports" setting of
<literal>Configuration</literal>.</phrase></para>
<para>If you are new to namespaces, you should read: <xref
linkend="dgui_misc_namespace" /></para>
</section>
</section>
<section xml:id="ref_directive_noparse">
<title>noparse</title>
<anchor xml:id="ref.directive.noparse" />
<indexterm>
<primary>noparse directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#noparse>
<replaceable>...</replaceable>
</#noparse></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>FreeMarker will not search FTL tags and interpolations and
other special character sequences in the body of this directive,
except the noparse end-tag.</para>
<para>Example:</para>
<programlisting role="template">Example:
--------
<emphasis><#noparse></emphasis>
<#list animals as being>
<tr><td>${being.name}<td>${being.price} Euros
</#list>
<emphasis></#noparse></emphasis></programlisting>
<para>will output:</para>
<programlisting role="output">Example:
--------
<#list animals as being>
<tr><td>${being.name}<td>${being.price} Euros
</#list>
</programlisting>
</section>
</section>
<section xml:id="ref_directive_compress">
<title>compress</title>
<anchor xml:id="ref.directive.compress" />
<indexterm>
<primary>compress directive</primary>
</indexterm>
<indexterm>
<primary>white-space removal</primary>
<secondary>compress</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#compress>
<replaceable>...</replaceable>
</#compress></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>The compress directive is useful for removing superfluous
<link linkend="gloss.whiteSpace">white-space</link> when you use a
white-space insensitive format (e.g. HTML or XML). It captures the
output generated inside its body (i.e. between its start-tag and
end-tag), and reduces all unbroken white-space sequences to a single
white-space character. The inserted character will be a <link
linkend="gloss.lineBreak">line break</link> if the replaced sequence
contains line breaks, or a space otherwise. The very first and very
last unbroken white-space sequences will be completely
removed.</para>
<programlisting role="template"><#assign x = " moo \n\n ">
(<#compress>
1 2 3 4 5
${moo}
test only
I said, test only
</#compress>)</programlisting>
<para>will output:</para>
<programlisting role="output">(1 2 3 4 5
moo
test only
I said, test only)</programlisting>
</section>
</section>
<section xml:id="ref_directive_escape">
<title>escape, noescape</title>
<anchor xml:id="ref.directive.escape" />
<anchor xml:id="ref.directive.noescape" />
<indexterm>
<primary>escape directive</primary>
</indexterm>
<indexterm>
<primary>noescape directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#escape <replaceable>identifier</replaceable> as <replaceable>expression</replaceable>>
<replaceable>...</replaceable>
<#noescape>...</#noescape>
<replaceable>...</replaceable>
</#escape></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>When you surround a part of the template with an escape
directive, interpolations
(<literal>${<replaceable>...</replaceable>}</literal>) that occur
inside the block are combined with the escaping expression
automatically. This is a convenience method for avoiding writing
similar expressions all over. It does not affect interpolations in
string literals (as in <literal><#assign x =
"Hello ${user}!"></literal>). Also, it does not affect numerical
interpolations
(<literal>#{<replaceable>...</replaceable>}</literal>).</para>
<para>Example:</para>
<programlisting role="template"><emphasis><#escape x as x?html></emphasis>
First name: ${firstName}
Last name: ${lastName}
Maiden name: ${maidenName}
<emphasis></#escape></emphasis></programlisting>
<para>is actually equivalent to:</para>
<programlisting role="template"> First name: ${firstName<emphasis>?html</emphasis>}
Last name: ${lastName<emphasis>?html</emphasis>}
Maiden name: ${maidenName<emphasis>?html</emphasis>}</programlisting>
<para>Note that it is irrelevant what identifier you use in the
directive - it just serves as a formal parameter to the escaping
expression.</para>
<para>When you are calling macros or the <literal>include</literal>
directive, it is important to understand that escape has effect only
on interpolations that occur between the <literal><#escape
<replaceable>...</replaceable>></literal> and
<literal></#escape></literal> <emphasis>in the template
text</emphasis>. That is, it will not escape anything that is before
<literal><#escape <replaceable>...</replaceable>></literal> in
the text, or after the <literal></#escape></literal> in the
text, not even if that part is called from inside the
<literal>escape</literal>-d section.</para>
<programlisting role="template"><#assign x = "<test>">
<#macro m1>
m1: ${x}
</#macro>
<#escape x as x?html>
<#macro m2>m2: ${x}</#macro>
${x}
<@m1/>
</#escape>
${x}
<@m2/></programlisting>
<para>the output will be:</para>
<programlisting role="output"> &lt;test&gt;
m1: <test>
<test>
m2: &lt;test&gt;</programlisting>
<para><phrase role="forProgrammers">More technically, the effects of
<literal>escape</literal> directive are applied at template parsing
time rather than at template processing time. This means that if you
call a macro or include another template from within an escape
block, it won't affect the interpolations in the macro/included
template, since macro calls and template includes are evaluated at
template processing time. On the other hand, if you surround one or
more macro declarations (which are evaluated at template parsing
time, as opposed to macro calls) with an escape block, the
interpolations in those macros will be combined with the escaping
expression.</phrase></para>
<para>Sometimes there is a need to temporarily turn off escaping for
one or two interpolations in an escape block. You can achieve this
by closing and later reopening the escape block, but then you have
to write the escaping expression twice. You can instead use the
noescape directive:</para>
<programlisting role="template"><#escape x as x?html>
From: ${mailMessage.From}
Subject: ${mailMessage.Subject}
<emphasis><#noescape></emphasis>Message: ${mailMessage.htmlFormattedBody}<emphasis></#noescape></emphasis>
<replaceable>...</replaceable>
</#escape></programlisting>
<para>is equivalent to:</para>
<programlisting role="template"> From: ${mailMessage.From?html}
Subject: ${mailMessage.Subject?html}
Message: ${mailMessage.htmlFormattedBody}
...</programlisting>
<para>Escapes can be nested (although you will do it only in rare
circumstances). Therefore, you can write something like the below
code (the example is admittedly a bit stretched, as you'd probably
place item codes in a sequence and use <literal>list</literal> to
iterate over them, but we're now doing it this way just to
illustrate the point):</para>
<programlisting role="template"><emphasis><#escape x as x?html></emphasis>
Customer Name: ${customerName}
Items to ship:
<emphasis><#escape x as itemCodeToNameMap[x]></emphasis>
${itemCode1}
${itemCode2}
${itemCode3}
${itemCode4}
<emphasis></#escape></emphasis>
<emphasis></#escape></emphasis></programlisting>
<para>is actually equivalent to:</para>
<programlisting role="template"> Customer Name: ${customerName?html}
Items to ship:
${itemCodeToNameMap[itemCode1]?html}
${itemCodeToNameMap[itemCode2]?html}
${itemCodeToNameMap[itemCode3]?html}
${itemCodeToNameMap[itemCode4]?html}</programlisting>
<para>When you use the noescape directive in a nested escape block,
it undoes only a single level of escaping. Therefore, to completely
turn off escaping in a two-level deep escaped block, you need to use
two nested noescape directives as well.</para>
</section>
</section>
<section xml:id="ref_directive_assign">
<title>assign</title>
<anchor xml:id="ref.directive.assign" />
<indexterm>
<primary>assign directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#assign <replaceable>name</replaceable>=<replaceable>value</replaceable>></literal>
or
<literal><#assign <replaceable>name1</replaceable>=<replaceable>value1</replaceable> <replaceable>name2</replaceable>=<replaceable>value2</replaceable> <replaceable>... nameN</replaceable>=<replaceable>valueN</replaceable>></literal>
or
<literal><#assign <replaceable>same as above...</replaceable> in <replaceable>namespacehash</replaceable>></literal>
or
<literal><#assign <replaceable>name</replaceable>>
<replaceable>capture this</replaceable>
</#assign></literal>
or
<literal><#assign <replaceable>name</replaceable> in <replaceable>namespacehash</replaceable>>
<replaceable>capture this</replaceable>
</#assign></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of the variable. It is not expression. However, it can be
written as a string literal, which is useful if the variable
name contains reserved characters, for example
<literal><#assign "foo-bar" = 1></literal>. Note that this
string literal does not expand interpolations (as
<literal>"${foo}"</literal>).</para>
</listitem>
<listitem>
<para><literal><replaceable>value</replaceable></literal>: the
value to store. Expression.</para>
</listitem>
<listitem>
<para><literal><replaceable>namespacehash</replaceable></literal>:
a hash that was created for a namespace (by <link
linkend="ref.directive.import"><literal>import</literal></link>).
Expression.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>With this you can create a new variable, or replace an
existing variable. Note that only top-level variables can be
created/replaced (i.e. you can't create/replace
<literal>some_hash.subvar</literal>, but
<literal>some_hash</literal>).</para>
<para>For more information about variables, read this: <xref
linkend="dgui_misc_var" /></para>
<para>Example: variable <literal>seasons</literal> will store a
sequence:</para>
<programlisting role="template"><#assign seasons = ["winter", "spring", "summer", "autumn"]></programlisting>
<para>Example: Increments the numerical value stored in variable
<literal>test</literal>:</para>
<programlisting role="template"><#assign test = test + 1></programlisting>
<para>As a convenience feature, you can do more assignments with one
<literal>assign</literal> tag. For example this will do the same as
the two previous examples:</para>
<programlisting role="template"><#assign
seasons = ["winter", "spring", "summer", "autumn"]
test = test + 1
></programlisting>
<para>If you know what namespaces are: <literal>assign</literal>
directive creates variables in namespaces. Normally it creates the
variable in the current namespace (i.e. in the namespace associated
with the template where the tag is). However, if you use <literal>in
<replaceable>namespacehash</replaceable></literal> then you can
create/replace a variable of another <link
linkend="dgui_misc_namespace">namespace</link> than the current
namespace. For example, here you create/replace variable
<literal>bgColor</literal> of the namespace used for
<literal>/mylib.ftl</literal>:</para>
<programlisting role="template"><#import "/mylib.ftl" as my>
<#assign bgColor="red" in my></programlisting>
<para>An extreme usage of <literal>assign</literal> is when it
captures the output generated between its start-tag and end-tag.
That is, things that are printed between the tags will not be shown
on the page, but will be stored in the variable. For example:</para>
<programlisting role="template"><#macro myMacro>foo</#macro>
<#assign x>
<#list 1..3 as n>
${n} <@myMacro />
</#list>
</#assign>
Number of words: ${x?word_list?size}
${x}</programlisting>
<para>will print:</para>
<programlisting role="output">Number of words: 6
1 foo
2 foo
3 foo
</programlisting>
<para>Please note that you should not to use this to insert
variables into strings:</para>
<programlisting role="template"><#assign x>Hello ${user}!</#assign> <#-- BAD PRACTICE! --></programlisting>
<para>You should simply write:</para>
<programlisting role="template"><#assign x="Hello ${user}!"></programlisting>
</section>
</section>
<section xml:id="ref_directive_global">
<title>global</title>
<anchor xml:id="ref.directive.global" />
<indexterm>
<primary>global directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#global <replaceable>name</replaceable>=<replaceable>value</replaceable>></literal>
or
<literal><#global <replaceable>name1</replaceable>=<replaceable>value1</replaceable> <replaceable>name2</replaceable>=<replaceable>value2</replaceable> <replaceable>... nameN</replaceable>=<replaceable>valueN</replaceable>></literal>
or
<literal><#global <replaceable>name</replaceable>>
<replaceable>capture this</replaceable>
</#global></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of the variable. It is not expression. However, it can be
written as a string literal, which is useful if the variable
name contains reserved characters, for example
<literal><#global "foo-bar" = 1></literal>. Note that this
string literal does not expand interpolations (as
<literal>"${foo}"</literal>).</para>
</listitem>
<listitem>
<para><literal><replaceable>value</replaceable></literal>: the
value to store. Expression.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>This directive is similar to <link
linkend="ref.directive.assign"><literal>assign</literal></link>, but
the variable created will be visible in all <link
linkend="dgui_misc_namespace">namespaces</link>, and will not be
inside any namespace. Exactly as if you would create (or replace) a
variable of the data-model. Hence, the variable is global. If a
variable with the same name already exists in the data-model, it
will be hidden by the variable created with this directive. If a
variable with the same name already exists in the current namespace,
that will hide the variable created with <literal>global</literal>
directive.</para>
<para>For example, with <literal><#global x = 1></literal> you
create a variable that is visible as <literal>x</literal> in all
namespaces, unless another variable called <literal>x</literal>
hides it (for example a variable what you have created as
<literal><#assign x = 2></literal>). In this case, you can use
<link linkend="dgui_template_exp_var_special">special
variable</link> <literal>globals</literal>, like
<literal>${.globals.x}</literal>. Note that with
<literal>globals</literal> you see all globally accessible
variables; not only the variables that were created with
<literal>global</literal> directive, but also the variables of the
data-model.</para>
<para>Note for custom JSP tag users: The set of variables created
with this directive corresponds to the JSP page-scope. This means,
that if a custom JSP tag wants to get a page-scope attribute
(page-scope bean), a variable with the same name in the current
namespace will not hide it from the viewpoint of the JSP tag.</para>
</section>
</section>
<section xml:id="ref_directive_local">
<title>local</title>
<anchor xml:id="ref.directive.local" />
<indexterm>
<primary>local directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#local <replaceable>name</replaceable>=<replaceable>value</replaceable>></literal>
or
<literal><#local <replaceable>name1</replaceable>=<replaceable>value1</replaceable> <replaceable>name2</replaceable>=<replaceable>value2</replaceable> <replaceable>... nameN</replaceable>=<replaceable>valueN</replaceable>></literal>
or
<literal><#local <replaceable>name</replaceable>>
<replaceable>capture this</replaceable>
</#local>
</literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: the
name of the local object in the root. It is not an expression.
However, it can be written as a string literal, which is useful
if the variable name contains reserved characters, for example
<literal><#local "foo-bar" = 1></literal>. Note that this
string literal does not expand interpolations (as
<literal>"${foo}"</literal>).</para>
</listitem>
<listitem>
<para><literal><replaceable>value</replaceable></literal>: the
value to store. Expression.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>It is similar to <link linkend="ref.directive.assign">assign
directive</link>, but it creates or replaces local variables. This
only works inside macro definitions and function definitons.</para>
<para>For more information about variables, read this: <xref
linkend="dgui_misc_var" /></para>
</section>
</section>
<section xml:id="ref_directive_setting">
<title>setting</title>
<anchor xml:id="ref.directive.setting" />
<indexterm>
<primary>setting directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#setting <replaceable>name</replaceable>=<replaceable>value</replaceable>></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of the setting. It is not expression!</para>
</listitem>
<listitem>
<para><literal><replaceable>value</replaceable></literal>: New
value of the setting. Expression</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>Sets a setting for the further part of processing. Settings
are values that influence the behavior of FreeMarker. The new value
will be present only in the template processing where it was set,
and does not touch the template itself. The initial value of
settings is set by the programmer <phrase
role="forProgrammers">(see: <xref
linkend="pgui_config_settings" />)</phrase>.</para>
<para>The supported settings are:</para>
<itemizedlist>
<listitem>
<para><indexterm>
<primary>locale</primary>
</indexterm><literal>locale</literal>: The locale (language)
of the output. It can influence the presentation format of
numbers, dates, etc. The value is a string which consist of a
language code (lowercase two-letter ISO-639 code) plus optional
county code (uppercase two-letter ISO-3166 code) separated from
the language code with underscore, and if we have specified the
country then an optional variant code (not standardized)
separated from the country with underscore. Examples of valid
values: <literal>en</literal>, <literal>en_US</literal>,
<literal>en_US_MAC</literal>. FreeMarker will try to use the
most specific available locale, so if you specify
<literal>en_US_MAC</literal> but that is not known, then it will
try <literal>en_US</literal>, and then <literal>en</literal>,
and then the default locale of the computer (which is may set by
the programmer).</para>
</listitem>
<listitem>
<para xml:id="ref.setting.number_format"><indexterm>
<primary>number_format</primary>
</indexterm><indexterm>
<primary>format</primary>
<secondary>number</secondary>
</indexterm><literal>number_format</literal>: The number
format that is used to convert numbers to strings when no
explicit format is specified. Can be one of predefined values
<literal>number</literal> (the default),
<literal>computer</literal>, <literal>currency</literal>, or
<literal>percent</literal>. Additionally, arbitrary format
pattern written in <link
xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java
decimal number format syntax</link> can also be specified. More
information about format patterns:<link
linkend="ref_builtin_string_for_number"><literal>string</literal>
built-in</link>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>boolean_format</primary>
</indexterm><indexterm>
<primary>format</primary>
<secondary>boolean</secondary>
</indexterm><literal>boolean_format</literal>: The
comma-separated pair of strings for representing true and false
values respectively that is used to convert booleans to strings
when no explicit format is specified. Default value is
<literal>"true,false"</literal>. See also:<link
linkend="ref_builtin_string_for_boolean"><literal>string</literal>
built-in</link>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>date_format</primary>
</indexterm><indexterm>
<primary>time_format</primary>
</indexterm><indexterm>
<primary>datetime_format</primary>
</indexterm><indexterm>
<primary>format</primary>
<secondary>date</secondary>
</indexterm> <literal>date_format</literal>,
<literal>time_format</literal>,
<literal>datetime_format</literal>: The date/time format used to
convert dates to strings when no explicit format is specified,
as in the case of <literal>${someDate}</literal>.
<literal>date_format</literal> affects only the formatting of
date-only dates (year, month, day),
<literal>time_format</literal> affects only the formatting of
time-only dates (hour,minute, second, millisecond),
<literal>datetime_format</literal> affects only the formatting
of date-time dates (year, month, day, hour, minute, second,
millisecond). The possible values of the settings are similar to
the parameters of <link
linkend="ref_builtin_string_for_date"><literal>string</literal>
built-in</link> of dates; see more explanation there. Examples:
<literal>"short"</literal>, <literal>"long_medium"</literal>,
<literal>"MM/dd/yyyy"</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>time_zone</primary>
</indexterm><literal>time_zone</literal>: The name of the time
zone used to format times for display. By default, the system
time zone is used. Can be any value that is accepted by <link
xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/util/TimeZone.html">Java
TimeZone API</link>. Examples: <literal>"GMT"</literal>,
<literal>"GMT+2"</literal>, <literal>"GMT-1:30"</literal>,
<literal>"CET"</literal>, <literal>"PST"</literal>,
<literal>"America/Los_Angeles"</literal></para>
</listitem>
<listitem>
<para><indexterm>
<primary>url_escaping_charset</primary>
</indexterm><literal>url_escaping_charset</literal>: The
charset used for URL escaping (e.g. for
<literal>${foo?url}</literal>) to calculate the escaped
(<literal>%<replaceable>XX</replaceable></literal>) parts.
Usually the framework that encloses FreeMarker should set it, so
you hardly ever should set this setting in templates. <phrase
role="forProgrammers">(Programmers can read more about this
<link
linkend="pgui_misc_charset">here...</link>)</phrase></para>
</listitem>
<listitem>
<para><indexterm>
<primary>classic_compatible</primary>
</indexterm><literal>classic_compatible</literal>: This is for
experts. Its value should be a boolean. See the documentation of
<literal>freemarker.template.Configurable</literal> for more
information.</para>
</listitem>
</itemizedlist>
<para>Example: Assume that the initial locale of template is hu
(Hungarian). Then this:</para>
<programlisting role="template">${1.2}
<#setting locale="en_US">
${1.2}</programlisting>
<para>will output this:</para>
<programlisting role="output">1,2
1.2</programlisting>
<para>because Hungarian people use the comma as their decimal
separator, while US people use the dot.</para>
</section>
</section>
<section xml:id="ref_directive_userDefined">
<title>User-defined directive (<@...>)</title>
<anchor xml:id="ref.directive.userDefined" />
<indexterm>
<primary>user-defined directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><@<replaceable>user_def_dir_exp</replaceable> <replaceable>param1</replaceable>=<replaceable>val1</replaceable> <replaceable>param2</replaceable>=<replaceable>val2</replaceable> <replaceable>...</replaceable> <replaceable>paramN</replaceable>=<replaceable>valN</replaceable>/></literal>
(Note the XML-style <literal>/</literal> before the <literal>></literal>)
or if you need loop variables (<link
linkend="ref_directive_userDefined_loopVar">more details...</link>)
<literal><@<replaceable>user_def_dir_exp</replaceable> <replaceable>param1</replaceable>=<replaceable>val1</replaceable> <replaceable>param2</replaceable>=<replaceable>val2</replaceable> <replaceable>...</replaceable> <replaceable>paramN</replaceable>=<replaceable>valN</replaceable> ; <replaceable>lv1</replaceable>, <replaceable>lv2</replaceable>, <replaceable>...</replaceable>, <replaceable>lvN</replaceable>/></literal>
Or the same as the above two but with end-tag (<link
linkend="ref_directive_userDefined_entTag">more details...</link>):
<literal><@<replaceable>user_def_dir_exp</replaceable> <replaceable>...</replaceable>>
...
</@<replaceable>user_def_dir_exp</replaceable>></literal>
or
<literal><@<replaceable>user_def_dir_exp</replaceable> <replaceable>...</replaceable>>
...
</@></literal>
Or all above but with positional parameter passing (<link
linkend="ref_directive_userDefined_positionalParam">more details...</link>):
<literal><@<replaceable>user</replaceable> <replaceable>val1</replaceable>, <replaceable>val2</replaceable>, <replaceable>...</replaceable>, <replaceable>valN</replaceable>/></literal>
...etc.
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>user_def_dir_exp</replaceable></literal>:
Expression evaluates to an user-defined directive (for example a
macro), that will be called.</para>
</listitem>
<listitem>
<para><literal><replaceable>param1</replaceable></literal>,
<literal><replaceable>param2</replaceable></literal>, ...etc.:
The name of parameters. They are <emphasis>not</emphasis>
expressions.</para>
</listitem>
<listitem>
<para><literal><replaceable>val1</replaceable></literal>,
<literal><replaceable>val2</replaceable></literal>, ...etc.: The
value of parameters. They <emphasis>are</emphasis>
expressions.</para>
</listitem>
<listitem>
<para><literal><replaceable>lv1</replaceable></literal>,
<literal><replaceable>lv2</replaceable></literal>, ...etc.: The
name of <link linkend="dgui_misc_var">loop variables</link>.
They are <emphasis>not</emphasis> expressions.</para>
</listitem>
</itemizedlist>
<para>The number of parameters can be 0 (i.e. no parameters).</para>
<para>The order of parameters is not significant (unless you use
positional parameter passing). The name of parameters must be
unique. Lower- and uppercase letters are considered as different
letters in parameter names (i.e. <literal>Color</literal> and
<literal>color</literal> is not the same).</para>
</section>
<section>
<title>Description</title>
<para>This will call an user-defined directive, for example a macro.
The meaning of parameters, and the set of supported and required
parameters depend on the concrete user-defined directive.</para>
<para>You may read <link linkend="dgui_misc_userdefdir">the tutorial
about user-defined directives</link>.</para>
<para>Example 1: Calls the directive that is stored in the variable
<literal>html_escape</literal>:</para>
<programlisting role="template"><@html_escape>
a < b
Romeo & Juliet
</@html_escape></programlisting>
<para>Output:</para>
<programlisting role="output"> a &lt; b
Romeo &amp; Juliet</programlisting>
<para>Example 2: Calls a macro with parameters:</para>
<programlisting role="template"><@list items=["mouse", "elephant", "python"] title="Animals"/>
<replaceable>...</replaceable>
<#macro list title items>
<p>${title?cap_first}:
<ul>
<#list items as x>
<li>${x?cap_first}
</#list>
</ul>
</#macro></programlisting>
<para>Output:</para>
<programlisting role="output"> <p>Animals:
<ul>
<li>Mouse
<li>Elephant
<li>Python
</ul>
<replaceable>...</replaceable></programlisting>
<section xml:id="ref_directive_userDefined_entTag">
<title>End-tag</title>
<para>You can omit the
<literal><replaceable>user_def_dir_exp</replaceable></literal> in
the <link linkend="gloss.endTag">end-tag</link>. That is, you can
always write <literal></@></literal> instead of
<literal></@<replaceable>anything</replaceable>></literal>.
This rule is mostly useful when the
<literal><replaceable>user_def_dir_exp</replaceable></literal>
expression is too complex, because you don't have to repeat the
expression in the end-tag. Furthermore, if the expression contains
other than simple variable names and dots, you are not allowed to
repeat the expression. For example,
<literal><@a_hash[a_method()]><replaceable>...</replaceable></@a_hash[a_method()]></literal>
is an error; you must write
<literal><@a_hash[a_method()]><replaceable>...</replaceable></@></literal>.
But
<literal><@a_hash.foo><replaceable>...</replaceable></@a_hash.foo></literal>
is OK.</para>
</section>
<section xml:id="ref_directive_userDefined_loopVar">
<title>Loop variables</title>
<para>Some user-defined directives create loop variables
(similarly to <literal>list</literal> directive). As with the
predefined directives (as <literal>list</literal>) the
<emphasis>name</emphasis> of loop variables is given when you call
the directive (as <literal>foo</literal> in <literal><#list
foos as
foo><replaceable>...</replaceable></#list></literal>),
while the <emphasis>value</emphasis> of the variable is set by the
directive itself. In the case of user-defined directives the
syntax is that the name of loop variables is given after a
semicolon. For example:</para>
<programlisting role="template"><@myRepeatMacro count=4 ; <emphasis>x, last</emphasis>>
${<emphasis>x</emphasis>}. Something... <#if <emphasis>last</emphasis>> This was the last!</#if>
</@myRepeatMacro></programlisting>
<para>Note that the number of loop variable created by the
user-defined directive and the number of loop variables specified
after the semicolon need not match. Say, if you are not interested
if the repetition is the last, you can simply write:</para>
<programlisting role="template"><@myRepeatMacro count=4 ; <emphasis>x</emphasis>>
${<emphasis>x</emphasis>}. Something...
</@myRepeatMacro></programlisting>
<para>or you can even:</para>
<programlisting role="template"><@myRepeatMacro count=4>
Something...
</@myRepeatMacro></programlisting>
<para>Furthermore, it does not cause error if you specify more
loop variables after the semicolon than the user-defined directive
creates, just the last few loop variables will not be created
(i.e. those will be undefined in the nested content). Trying to
use the undefined loop variables, however, will cause error
(unless you use built-ins like <literal>?default</literal>), since
you try to access a non-existing variable.</para>
<para>See the <link linkend="dgui_misc_userdefdir">the tutorial
about user-defined directives</link> for more explanation.</para>
</section>
<section xml:id="ref_directive_userDefined_positionalParam">
<title>Positional parameter passing</title>
<indexterm>
<primary>positional parameter passing</primary>
</indexterm>
<para>Positional parameter passing (as <literal><@heading
"Preface", 1/></literal>) is a shorthand form of normal named
parameter passing (as <literal><@heading title="Preface"
level=1/></literal>), where you omit the parameter name. This
shorthand form should be used if a user-defined directive has only
one parameter, or if it is easy to remember the order of
parameters for a frequently used user-defined directive. To use
this form, you have to know the order in which the named
parameters are declared (trivial if the directive has only one
parameter). Say, if <literal>heading</literal> was created as
<literal><#macro heading title
level><replaceable>...</replaceable></literal>, then
<literal><@heading "Preface", 1/></literal> is equivalent
with <literal><@heading title="Preface" level=1/></literal>
(or <literal><@heading level=1 title="Preface"/></literal>;
if you use parameter names, the order is not important). Note that
positional parameter passing is currently only supported for
macros.</para>
</section>
</section>
</section>
<section xml:id="ref_directive_macro">
<title>macro, nested, return</title>
<anchor xml:id="ref.directive.macro" />
<indexterm>
<primary>macro directive</primary>
</indexterm>
<indexterm>
<primary>nested directive</primary>
</indexterm>
<indexterm>
<primary>return directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#macro <replaceable>name</replaceable> <replaceable>param1</replaceable> <replaceable>param2</replaceable> <replaceable>... paramN</replaceable>>
<replaceable>...</replaceable>
<#nested <replaceable>loopvar1</replaceable>, <replaceable>loopvar2</replaceable>, <replaceable>...</replaceable>, <replaceable>loopvarN</replaceable>>
<replaceable>...</replaceable>
<#return>
<replaceable>...</replaceable>
</#macro></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of macro variable. It's not an expression. However, it can be
written as a string literal, which is useful if the macro name
contains reserved characters, for example <literal><#macro
"foo-bar"><replaceable>...</replaceable></literal>. Note that
this string literal does not expand interpolations (as
<literal>"${foo}"</literal>).</para>
</listitem>
<listitem>
<para><literal><replaceable>param1</replaceable></literal>,
<literal><replaceable>param2</replaceable></literal>, ...etc.:
the name of the <link linkend="dgui_misc_var">local
variables</link> store the parameter values (not expression),
optionally followed by <literal>=</literal> and the default
value (that's an expression). The default value can even be
another parameter, for example <literal><#macro section title
label=title></literal>.</para>
</listitem>
<listitem>
<para><literal><replaceable>paramN</replaceable></literal>, the
last parameter, may optionally include a trailing ellipsis
(<literal>...</literal>), which indicates the macro takes a
variable number of parameters. If called using named parameters,
<literal><replaceable>paramN</replaceable></literal> will be a
hash containing all of the undeclared key/value pairs passed to
the macro. If called using positional parameters,
<literal><replaceable>paramN</replaceable></literal> will be a
sequence of the extra parameters.</para>
</listitem>
<listitem>
<para><literal><replaceable>loopvar1</replaceable></literal>,
<literal><replaceable>loopvar2</replaceable></literal>, ...etc.:
Optional. The values of <link linkend="dgui_misc_var">loop
variables</link> that the <literal>nested</literal> directive
wants to create for the nested content. These are
expressions.</para>
</listitem>
</itemizedlist>
<para>The <literal>return</literal> and <literal>nested</literal>
directives are optional and can be used anywhere and for any times
between the <literal><#macro
<replaceable>...</replaceable>></literal> and
<literal></#macro></literal>.</para>
<para>Parameters without default value must precede parameters with
default value
(<literal><replaceable>paramName</replaceable>=<replaceable>defaultValue</replaceable></literal>).</para>
</section>
<section>
<title>Description</title>
<para>Creates a macro variable (in the current namespace, if you
know namespace feature). If you are new to macros and user-defined
directives you should read the <link
linkend="dgui_misc_userdefdir">the tutorial about user-defined
directives</link>.</para>
<para>Macro variable stores a template fragment (called macro
definition body) that can be used as <link
linkend="ref.directive.userDefined">user-defined directive</link>.
The variable also stores the name of allowed parameters to the
user-defined directive. You must give value for all of those
parameters when you use the variable as directive, except for
parameters that has a default value. The default value will be used
if and only if you don't give value for the parameter when you call
the macro.</para>
<para>The variable will be created at the beginning of the template;
it does not mater where the <literal>macro</literal> directive is
placed in the template. Thus, this will work:</para>
<programlisting role="template"><#-- call the macro; the macro variable is already created: -->
<@test/>
...
<#-- create the macro variable: -->
<#macro test>
Test text
</#macro></programlisting>
<para>However, if the macro definitions are inserted with
<literal>include</literal> directive, they will not be available
until FreeMarker has executed the <literal>include</literal>
directive.</para>
<para>Example: Macro without parameters:</para>
<programlisting role="template"><#macro test>
Test text
</#macro>
<#-- call the macro: -->
<@test/></programlisting>
<para>Output:</para>
<programlisting role="output"> Test text
</programlisting>
<para>Example: Macro with parameters:</para>
<programlisting role="template"><#macro test foo bar baaz>
Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>
<#-- call the macro: -->
<@test foo="a" bar="b" baaz=5*5-2/></programlisting>
<para>Output:</para>
<programlisting role="output"> Test text, and the params: a, b, 23
</programlisting>
<para>Example: Macro with parameters and default parameter
values:</para>
<programlisting role="template"><#macro test foo bar="Bar" baaz=-1>
Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>
<@test foo="a" bar="b" baaz=5*5-2/>
<@test foo="a" bar="b"/>
<@test foo="a" baaz=5*5-2/>
<@test foo="a"/></programlisting>
<para>Output:</para>
<programlisting role="output"> Test text, and the params: a, b, 23
Test text, and the params: a, b, -1
Test text, and the params: a, Bar, 23
Test text, and the params: a, Bar, -1
</programlisting>
<para>Example: A more complex macro.</para>
<programlisting role="template"><#macro list title items>
<p>${title?cap_first}:
<ul>
<#list items as x>
<li>${x?cap_first}
</#list>
</ul>
</#macro>
<@list items=["mouse", "elephant", "python"] title="Animals"/></programlisting>
<para>Output:</para>
<programlisting role="output"> <p>Animals:
<ul>
<li>Mouse
<li>Elephant
<li>Python
</ul>
</programlisting>
<para>Example: A macro with support for a variable number of named
parameters:</para>
<programlisting role="template"><#macro img src extra...>
<img src="/context${src?html}"
<#list extra?keys as attr>
${attr}="${extra[attr]?html}"
</#list>
>
</#macro>
<@img src="/images/test.png" width=100 height=50 alt="Test"/></programlisting>
<para>Output:</para>
<programlisting role="output"> <img src="/context/images/test.png"
alt="Test"
height="50"
width="100"
></programlisting>
<section>
<title>nested</title>
<anchor xml:id="ref.directive.nested" />
<para>The <literal>nested</literal> directive executes the
template fragment between the start-tag and end-tags of the
user-defined directive. The nested part can contain anything what
is valid in templates; interpolations, directives, ...etc. It is
executed in the context where the macro was called from, rather
than in the context of the macro definition body. Thus, for
example, you don't see the local variables of the macro in the
nested part. If you don't call the <literal>nested</literal>
directive, the part between the start-tag and end-tags of the
user-defined directive will be ignored.</para>
<para>Example:</para>
<programlisting role="template"><#macro do_twice>
1. <#nested>
2. <#nested>
</#macro>
<@do_twice>something</@do_twice></programlisting>
<para>Output:</para>
<programlisting role="output"> 1. something
2. something
</programlisting>
<para>The nested directive can create loop variables for the
nested content. For example:</para>
<programlisting role="template"><#macro do_thrice>
<#nested <emphasis>1</emphasis>>
<#nested <emphasis>2</emphasis>>
<#nested <emphasis>3</emphasis>>
</#macro>
<@do_thrice <emphasis>; x</emphasis>>
${<emphasis>x</emphasis>} Anything.
</@do_thrice></programlisting>
<para>This will print:</para>
<programlisting role="output"> 1 Anything.
2 Anything.
3 Anything.
</programlisting>
<para>A more complex example:</para>
<programlisting role="template"><#macro repeat count>
<#list 1..count as x>
<#nested <emphasis>x, x/2, x==count</emphasis>>
</#list>
</#macro>
<@repeat count=4 ; <emphasis>c, halfc, last</emphasis>>
${<emphasis>c</emphasis>}. ${<emphasis>halfc</emphasis>}<#if <emphasis>last</emphasis>> Last!</#if>
</@repeat></programlisting>
<para>The output will be:</para>
<programlisting role="output"> 1. 0.5
2. 1
3. 1.5
4. 2 Last!
</programlisting>
</section>
<section>
<title>return</title>
<anchor xml:id="ref.directive.macro.return" />
<para>With the <literal>return</literal> directive, you can leave
a macro or function definition body anywhere. Example:</para>
<programlisting role="template"><#macro test>
Test text
<#return>
Will not be printed.
</#macro>
<@test/></programlisting>
<para>Output:</para>
<programlisting role="output"> Test text
</programlisting>
</section>
</section>
</section>
<section xml:id="ref_directive_function">
<title>function, return</title>
<anchor xml:id="ref.directive.function" />
<anchor xml:id="ref.directive.function.return" />
<indexterm>
<primary>function directive</primary>
</indexterm>
<indexterm>
<primary>return directive</primary>
</indexterm>
<indexterm>
<primary>method</primary>
<secondary>defining with FTL</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#function <replaceable>name</replaceable> <replaceable>param1</replaceable> <replaceable>param2</replaceable> <replaceable>... paramN</replaceable>>
<replaceable>...</replaceable>
<#return <replaceable>returnValue</replaceable>>
<replaceable>...</replaceable>
</#function></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of method variable (not expression)</para>
</listitem>
<listitem>
<para><literal><replaceable>param1</replaceable></literal>,
<literal><replaceable>param2</replaceable></literal>, ...etc.:
the name of the <link linkend="dgui_misc_var">local
variables</link> store the parameter values (not expression),
optionally followed by <literal>=</literal> and the default
value (that's an expression).</para>
</listitem>
<listitem>
<para><literal><replaceable>paramN</replaceable></literal>, the
last parameter, may optionally include a trailing ellipsis
(<literal>...</literal>), which indicates the macro takes a
variable number of parameters. Local variable
<literal><replaceable>paramN</replaceable></literal> will be a
sequence of the extra parameters.</para>
</listitem>
<listitem>
<para><literal><replaceable>returnValue</replaceable></literal>:
the expression that calculates the value of the method
call.</para>
</listitem>
</itemizedlist>
<para>The <literal>return</literal> directive can be used anywhere
and for any times between the <literal><#function
<replaceable>...</replaceable>></literal> and
<literal></#function></literal>.</para>
<para>Parameters without default value must precede parameters with
default value
(<literal><replaceable>paramName</replaceable>=<replaceable>defaultValue</replaceable></literal>).</para>
</section>
<section>
<title>Description</title>
<para>Creates a method variable (in the current namespace, if you
know namespace feature). This directive works in the same way as the
<link linkend="ref.directive.macro"><literal>macro</literal>
directive</link>, except that <literal>return</literal> directive
<emphasis>must</emphasis> have a parameter that specifies the return
value of the method, and that attempts to write to the output will
be ignored. If the <literal></#function></literal> is reached
(i.e. there was no <literal>return
<replaceable>returnValue</replaceable></literal>), then the return
value of the method is an undefined variable.</para>
<para>Example 1: Creating a method that calculates the average of
two numbers:</para>
<programlisting role="template"><#function avg x y>
<#return (x + y) / 2>
</#function>
${avg(10, 20)}</programlisting>
<para>will print:</para>
<programlisting role="output">15</programlisting>
<para>Example 2: Creating a method that calculates the average of
multiple numbers:</para>
<programlisting role="template"><#function avg nums...>
<#local sum = 0>
<#list nums as num>
<#local sum = sum + num>
</#list>
<#if nums?size != 0>
<#return sum / nums?size>
</#if>
</#function>
${avg(10, 20)}
${avg(10, 20, 30, 40)}
${avg()!"N/A"}</programlisting>
<para>will print:</para>
<programlisting role="output">15
25
N/A</programlisting>
</section>
</section>
<section xml:id="ref_directive_flush">
<title>flush</title>
<anchor xml:id="ref.directive.flush" />
<indexterm>
<primary>flush directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#flush></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>When FreeMarker generates the output it typically stockpiles
the generated output and send it to the client in one or in a few
big pieces. This act of sending is called flushing (as flushing the
toilet). Although flushing happens automatically, sometimes you want
to force it on certain points of the template processing, and this
is what <literal>flush</literal> directive does. If it is needed,
then the programmer could tell it to you; typically you should not
use this directive. The mechanism of automatic flushing and the
precise effect of <literal>flush</literal> directive are under the
control of the programmer.</para>
<para><phrase role="forProgrammers">Flush simply calls the flush
method of the currently used java.io.Writer instance. The whole
buffering and flushing mechanism is implemented in the writer (what
you have passed as the parameter of the
<literal>Template.process</literal> method); FreeMarker does not
deal with it.</phrase></para>
</section>
</section>
<section xml:id="ref_directive_stop">
<title>stop</title>
<anchor xml:id="ref.directive.stop" />
<indexterm>
<primary>stop directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#stop></literal>
or
<literal><#stop <replaceable>reason</replaceable>></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>reason</replaceable></literal>:
Informative message about the reason of termination. Expression
evaluates to string.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>Aborts the processing of template. This is something like an
emergency brake: don't use it in normal situations. <phrase
role="forProgrammers">Aborting happens by throwing a
<literal>StopException</literal>, and the
<literal>StopException</literal> will hold the value of reason
parameter.</phrase></para>
</section>
</section>
<section xml:id="ref_directive_ftl">
<title>ftl</title>
<anchor xml:id="ref.directive.ftl" />
<indexterm>
<primary>ftl directive</primary>
</indexterm>
<indexterm>
<primary>header</primary>
</indexterm>
<indexterm>
<primary>charset</primary>
</indexterm>
<indexterm>
<primary>encoding</primary>
</indexterm>
<indexterm>
<primary>white-space removal</primary>
<secondary>stripping</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#ftl <replaceable>param1</replaceable>=<replaceable>value1</replaceable> <replaceable>param2</replaceable>=<replaceable>value2</replaceable> <replaceable>...</replaceable> <replaceable>paramN</replaceable>=<replaceable>valueN</replaceable>></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>param1</replaceable></literal>,
<literal><replaceable>param2</replaceable></literal>, ...etc.:
Name of the parameter. Not an expression. Allowed parameters
are: <literal>encoding</literal>,
<literal>strip_whitespace</literal>,
<literal>strip_text</literal>, ...etc. See below.</para>
</listitem>
<listitem>
<para><literal><replaceable>value1</replaceable></literal>,
<literal><replaceable>value2</replaceable></literal>, ...etc.:
The value of parameter. This must be a constant expression (as
<literal>true</literal>, or <literal>"ISO-8859-5"</literal>, or
<literal>{x:1, y:2}</literal>). It can't use variables.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>Tells information about the template for FreeMarker and for
other tools, also helps programs to automatically detect if a text
file is an FTL file. This directive, if present, must be the very
first thing in the template. Any <link
linkend="gloss.whiteSpace">white-space</link> before this directive
will be ignored. The old-syntax (<literal>#</literal>-less) format
of this directive is not supported.</para>
<para>The settings (encoding, white-space stripping, etc.) given
here has the highest precedence, that is, they will be used for the
template regardless of any FreeMarker configuration settings.</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para><literal>encoding</literal>: With this you can specify the
encoding (charset) of the template in the template file itself.
<phrase role="forProgrammers">(That is, this will be the
<literal>encoding</literal> setting of the newly created
<literal>Template</literal>, and not even the
<literal>encoding</literal> parameter to
<literal>Configuration.getTemplate</literal> can override
it)</phrase>. Note however, that FreeMarker will try to find and
interpret the <literal>ftl</literal> directive first with the
automatically guessed encoding (which depends on the FreeMarker
configuration set by the programmers), and only then realizes if
the <literal>ftl</literal> directive dictates something
different, and re-read the template with the new encoding. Thus,
the template must be valid FTL until the end of
<literal>ftl</literal> tag with the encoding tried first. The
valid values of this parameter are MIME-preferred charset names
from the IANA Charset Registry, like ISO-8859-5, UTF-8 or
Shift_JIS.</para>
</listitem>
<listitem>
<para><literal>strip_whitespace</literal>: This enables/disables
<link linkend="dgui_misc_whitespace_stripping">white-space
stripping</link>. Valid values are the boolean constants
<literal>true</literal> and <literal>false</literal>. (And for
backward compatibility, strings <literal>"yes"</literal>,
<literal>"no"</literal>, <literal>"true"</literal>,
<literal>"false"</literal>). The default value (i.e. when you
don't use this parameter) depends on the FreeMarker
configuration set by the programmers, but it should be
<literal>true</literal> for new projects.</para>
</listitem>
<listitem>
<para><literal>strip_text</literal>: When enabled, all top-level
text in a template is removed when the template is parsed. This
does not affect text within macros, directives, or
interpolations. Valid values are the boolean constants
<literal>true</literal> and <literal>false</literal>. (And for
backward compatibility, strings <literal>"yes"</literal>,
<literal>"no"</literal>, <literal>"true"</literal>,
<literal>"false"</literal>). The default value (i.e. when you
don't use this parameter) is <literal>false</literal>.</para>
</listitem>
<listitem>
<para><literal>strict_syntax</literal>: This turns on/off
``strict syntax''. Valid values are the boolean constants
<literal>true</literal> and <literal>false</literal>. (And for
backward compatibility, strings <literal>"yes"</literal>,
<literal>"no"</literal>, <literal>"true"</literal>,
<literal>"false"</literal>). The default value (i.e. when you
don't use this parameter) depends on the FreeMarker
configuration set by the programmers, but it should be
<literal>true</literal> for new projects. <phrase
role="forProgrammers">(Programmers: you must set explicitly this
setting to <literal>true</literal> for this:
<literal>config.setStrictSyntaxMode(true);</literal>)</phrase>
For more information read: <xref
linkend="ref_depr_oldsyntax" /></para>
</listitem>
<listitem>
<para><literal>ns_prefixes</literal>: This is a hash that
associates prefixes with node namespaces. For example:
<literal>{"e":"http://example.com/ebook",
"vg":"http://example.com/vektorGraphics"}</literal>. This is
mostly used with XML processing where the prefixes can be used
in XML queries, but it also influences the working of <link
linkend="ref_directive_visit">directives
<literal>visit</literal> and <literal>recurse</literal></link>.
Only one prefix can be registered for the same node namespace
(otherwise an error will occur), so there is one-to-one relation
between prefixes and node namespaces. Prefixes
<literal>D</literal> and <literal>N</literal> are reserved. If
you register prefix <literal>D</literal>, then other than you
associate the node namespace with prefix <literal>D</literal>,
you also set the default node namespace. Prefix
<literal>N</literal> can't be registered; it is used to denote
nodes with no node namespace in certain places, when (and only
when) prefix <literal>D</literal> is registered. (To see the
usage of default node namespace, <literal>N</literal>, and
prefixes in general, see the part about <link linkend="xgui">XML
processing</link> and <link
linkend="ref_directive_visit"><literal>visit</literal> and
<literal>recurse</literal></link> in the reference.) The effect
of <literal>ns_prefixes</literal> is limited to a single <link
linkend="dgui_misc_namespace">FTL namespace</link>, namely, to
the FTL namespace that was created for the template. This also
means that <literal>ns_prefixes</literal> has effect only when
an FTL namespace is created for the template that contains it,
otherwise the <literal>ns_prefixes</literal> parameter has no
effect. An FTL namespace is made for a template when: (a) the
template is the ``main'' template, that is, it is not invoked as
a result of an <literal><#include ...></literal>, but it
is directly invoked (<phrase role="forProgrammers">with the
<literal>process</literal> Java method of class
<literal>Template</literal> or
<literal>Environment</literal></phrase>); (b) the template is
invoked directly with <literal><#import
...></literal>.</para>
</listitem>
<listitem>
<para><literal>attributes</literal>: This is a hash that
associates arbitrary attributes (name-value pairs) to the
template. The values of the attributes can be of any type
(string, number, sequence... etc.). FreeMarker doesn't try to
understand the meaning of the attributes. It's up to the
application that encapsulates FreeMarker (as a Web application
framework). Thus, the set of allowed attributes and their
semantic is application (Web application framework) dependent.
<phrase role="forProgrammers">Programmers: you can get the
attributes associated with a <literal>Template</literal> object
with its <literal>getCustomAttributeNames</literal> and
<literal>getCustomAttribute</literal> methods (inherited from
<literal>freemarker.core.Configurable</literal>). As the
template attributes are associated with the
<literal>Template</literal> object when the template is parsed,
the attributes can be read anytime, the template need not be
executed. The methods mentioned return the attribute values
unwrapped, that is, with FreeMarker independent type as
<literal>java.util.List</literal>.</phrase></para>
</listitem>
</itemizedlist>
<para>This directive also determines if the template uses angle
bracket syntax (e.g. <literal><#include 'foo.ftl'></literal>)
or <link linkend="dgui_misc_alternativesyntax">square bracket
syntax</link> (e.g. <literal>[#include 'foo.ftl']</literal>).
Simply, the syntax used for this directive will be the syntax used
for the whole template, regardless of the FreeMarker configuration
settings.</para>
</section>
</section>
<section xml:id="ref_directive_t">
<title>t, lt, rt</title>
<anchor xml:id="ref.directive.t" />
<anchor xml:id="ref.directive.lt" />
<anchor xml:id="ref.directive.rt" />
<indexterm>
<primary>t directive</primary>
</indexterm>
<indexterm>
<primary>lt directive</primary>
</indexterm>
<indexterm>
<primary>rt directive</primary>
</indexterm>
<indexterm>
<primary>trimmer directives</primary>
</indexterm>
<indexterm>
<primary>white-space removal</primary>
<secondary>trimming</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#t></literal>
<literal><#lt></literal>
<literal><#rt></literal>
<literal><#nt></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>These directives, instruct FreeMarker to ignore certain
white-space in the line of the tag:</para>
<itemizedlist>
<listitem>
<para><literal>t</literal> (for trim): Ignore all leading and
trailing white-space in this line.</para>
</listitem>
<listitem>
<para><literal>lt</literal> (for left trim): Ignore all leading
white-space in this line.</para>
</listitem>
<listitem>
<para><literal>rt</literal> (for right trim): Ignore all
trailing white-space in this line.</para>
</listitem>
</itemizedlist>
<para>where:</para>
<itemizedlist>
<listitem>
<para>``leading white-space'' means all space and tab (and other
character that are white-space according to <link
linkend="gloss.unicode">UNICODE</link>, except <link
linkend="gloss.lineBreak">line breaks</link>) before the first
non-white-space character of the line.</para>
</listitem>
<listitem>
<para>``trailing white-space'' means all space and tab (and
other character that are white-space according to <link
linkend="gloss.unicode">UNICODE</link>, except line breaks)
after the last non-white-space character of the line,
<emphasis>and</emphasis> the line break at the end of the
line.</para>
</listitem>
</itemizedlist>
<para>It is important to understand that these directives examine
the template itself, and <emphasis>not</emphasis> the output what
the template generates when you merge it with the data-model.
<phrase role="forProgrammers">(That is, the white-space removal
happens on parse time.)</phrase></para>
<para>For example this:</para>
<programlisting role="template">--
1 <#t>
2<#t>
3<#lt>
4
5<#rt>
6
--
</programlisting>
<para>will output this:</para>
<programlisting role="output">--
1 23
4
5 6
--</programlisting>
<para>The placement of these directives inside the line has no
importance. That is, the effect will be the same regardless if you
put the directive at the beginning of the line, or at the end of the
line, or in the middle of the line.</para>
</section>
</section>
<section xml:id="ref_directive_nt">
<title>nt</title>
<anchor xml:id="ref.directive.nt" />
<indexterm>
<primary>nt directive</primary>
</indexterm>
<indexterm>
<primary>trimmer directives</primary>
</indexterm>
<indexterm>
<primary>white-space removal</primary>
<secondary>trimming</secondary>
</indexterm>
<indexterm>
<primary>white-space removal</primary>
<secondary>stripping</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#nt></literal>
</programlisting>
</section>
<section>
<title>Description</title>
<para>``No Trim''. This directive disables <link
linkend="dgui_misc_whitespace_stripping">white-space
stripping</link> in the line where it occurs. It also disables the
effect of other trim directives occuring in the same line (the
effect of <literal>t</literal>, <literal>rt</literal>,
<literal>lt</literal>).</para>
</section>
</section>
<section xml:id="ref_directive_attempt">
<title>attempt, recover</title>
<anchor xml:id="ref.directive.attempt" />
<indexterm>
<primary>attempt directive</primary>
</indexterm>
<indexterm>
<primary>recover directive</primary>
</indexterm>
<indexterm>
<primary>error handling</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><#attempt>
<replaceable>attempt block</replaceable>
<#recover>
<replaceable>recover block</replaceable>
</#attempt>
</literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>attempt
block</replaceable></literal>: Template block with any content.
This will be always executed, but if an error occurs during
that, all output from this block is rolled back, and the
<literal><replaceable>recover block</replaceable></literal> will
be executed.</para>
</listitem>
<listitem>
<para><literal><replaceable>recover
block</replaceable></literal>: Template block with any content.
This will be executed only if there was an error during the
execution of the <literal><replaceable>attempt
block</replaceable></literal>. You may print an error messages
here and such.</para>
</listitem>
</itemizedlist>
<para>The <literal><replaceable>recover</replaceable></literal> is
mandatory. <literal>attempt</literal>/<literal>recover</literal> can
be nested freely into other <literal><replaceable>attempt
block</replaceable></literal>s or <literal><replaceable>recover
block</replaceable></literal>s.</para>
<note>
<para>The format shown here is supported starting from 2.3.3;
earlier it was
<literal><#attempt><replaceable>...</replaceable><#recover><replaceable>...</replaceable></#recover></literal>,
which is still supported for backward compatibility. Furthermore,
these directives were introduced with FreeMarker 2.3.1, so they
aren't exist in 2.3.</para>
</note>
</section>
<section>
<title>Description</title>
<para>These directives are used if you want the page successfully
outputted even if the outputting of a certain part of the page
fails. If an error occurs during the execution of the
<literal><replaceable>attempt block</replaceable></literal>, then
the template execution is not aborted, but the
<literal><replaceable>recover block</replaceable></literal> is
executed instead of the <literal><replaceable>attempt
block</replaceable></literal>. If no error occurs during the
execution of the <literal><replaceable>attempt
block</replaceable></literal>, then the
<literal><replaceable>recover block</replaceable></literal> is
ignored. A simple example:</para>
<programlisting role="template">Primary content
<#attempt>
Optional content: ${thisMayFails}
<#recover>
Ops! The optional content is not available.
</#attempt>
Primary content continued</programlisting>
<para>If the <literal>thisMayFails</literal> variable doesn't exist,
then the output is:</para>
<programlisting role="output">Primary content
Ops! The optional content is not available.
Primary content continued</programlisting>
<para>If the <literal>thisMayFails</literal> variable exists and
it's value is <literal>123</literal>, then the output is:</para>
<programlisting role="output">Primary content
Optional content: 123
Primary content continued</programlisting>
<para>The <literal><replaceable>attempt
block</replaceable></literal> has an all-or-none semantic: either
the entire content of the <literal><replaceable>attempt
block</replaceable></literal> is output (when there was no error),
or no output at all results from the execution of the
<literal><replaceable>attempt block</replaceable></literal> (when
there was an error). For example, above, the failure happens after
``Optional content: '' was printed, still it is not there in the
output before the ``Ops!''. (<phrase role="forProgrammers">This is
implemented with the aggressive buffering of the output inside the
<literal><replaceable>attempt block</replaceable></literal>. Not
even the <literal>flush</literal> directive will send the output to
the client.</phrase>)</para>
<para>To prevent misunderstandings coming from the above example:
<literal>attempt</literal>/<literal>recover</literal> is not (only)
for handling undefined variables (for that use <link
linkend="dgui_template_exp_missing">missing value handler
operators</link>). It can handle all kind of errors that occurs when
the block is executed (i.e. not syntactical errors, which are
detected earlier). And it's meant to enclose bigger template
fragments, where error can occur at various points. For example, you
have a part in your template that deals with printing
advertisements, but that's not the primary content of the page, so
you don't want your whole page be down just because some error
occurs with the printing of the advertisements (say, because of a
temporal database server faliure). So you put the whole
advertisement printing into an <literal><replaceable>attempt
block</replaceable></literal>.</para>
<para>In some environments programmers configure FreeMarker so that
it doesn't abort template execution for certain errors, but
continues execution, possibly after printing some error indicator to
the output (<phrase role="forProgrammers">see more <link
linkend="pgui_config_errorhandling">here...</link></phrase>). The
<literal>attempt</literal> directive doesn't consider such
suppressed errors as errors.</para>
<para>Inside a <literal><replaceable>recover
block</replaceable></literal> the error message of the error is
available with the <literal>error</literal> <link
linkend="ref_specvar">special variable</link>. Don't forget that
references to special variable are started with dot (for example:
<literal>${.error}</literal>).</para>
<para><phrase role="forProgrammers">Errors occurring during template
execution are always <link
linkend="pgui_misc_logging">logged</link>, even if they occur inside
an <literal><replaceable>attempt
block</replaceable></literal>.</phrase></para>
</section>
</section>
<section xml:id="ref_directive_visit">
<title>visit, recurse, fallback</title>
<anchor xml:id="ref.directive.visit" />
<indexterm>
<primary>visit directive</primary>
</indexterm>
<indexterm>
<primary>recurse directive</primary>
</indexterm>
<indexterm>
<primary>fallback directive</primary>
</indexterm>
<indexterm>
<primary>recursion</primary>
<secondary>iterate</secondary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate"><literal><#visit <replaceable>node</replaceable> using <replaceable>namespace</replaceable>></literal>
or
<literal><#visit <replaceable>node</replaceable>></literal></programlisting>
<programlisting role="metaTemplate"><literal><#recurse <replaceable>node</replaceable> using <replaceable>namespace</replaceable>></literal>
or
<literal><#recurse <replaceable>node</replaceable>></literal>
or
<literal><#recurse using <replaceable>namespace</replaceable>></literal>
or
<literal><#recurse></literal></programlisting>
<programlisting role="metaTemplate"><literal><#fallback></literal></programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>node</replaceable></literal>:
Expression evaluates to a <link linkend="xgui_expose_dom">node
variable</link>.</para>
</listitem>
<listitem>
<para><literal><replaceable>namespace</replaceable></literal>: A
<link linkend="dgui_misc_namespace">namespace</link>, or a
sequence of namespaces. A namespace can be given with the
namespace hash (a.k.a. gate hash), or with a string literal that
store the path of template that could be imported. Instead of
namespace hashes, you can use plain hashes as well.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>The <literal>visit</literal> and <literal>recurse</literal>
directives are used for the recursive processing of trees. In
practice, this will mostly be used for <link
linkend="xgui">processing XML.</link></para>
<section>
<title>Visit</title>
<para>When you call <literal><#visit
<replaceable>node</replaceable>></literal>, it looks for a
user-defined directive (like a macro) to invoke that has the name
deducted from the node's name
(<literal><replaceable>node</replaceable>?node_name</literal>) and
namespace
(<literal><replaceable>node</replaceable>?node_namesoace</literal>).
The rules of name deduction:</para>
<itemizedlist>
<listitem>
<para>If the node doesn't support node namespaces (as text
nodes in XML), then the directive name is simply the name of
the node
(<literal><replaceable>node</replaceable>?node_name</literal>).
<phrase role="forProgrammers">A node does not support node
namespaces if the <literal>getNodeNamespace</literal> method
returns <literal>null</literal>.</phrase></para>
</listitem>
<listitem>
<para>If the node does support node namespaces (as element
nodes in XML), then a prefix deduced from the node namespace
maybe appended before the node name with a colon used as
separator (e.g. <literal>e:book</literal>). The prefix, and if
there is a prefix used at all, depends on what prefixes has
been registered with the <literal>ns_prefixes</literal>
parameter of the <literal>ftl</literal> directive in the <link
linkend="dgui_misc_namespace">FTL namespace</link> where
<literal>visit</literal> looks for the handler directive
(which is not necessary the same as the FTL namespace where
<literal>visit</literal> was called from, as you will see
later). Concretely, if there was no default namespace
registered with <literal>ns_prefixes</literal> then for nodes
that does not belong to any namespace (<phrase
role="forProgrammers">when <literal>getNodeNamespace</literal>
returns <literal>""</literal></phrase>) no prefix is used. If
there was a default namespace registered with
<literal>ns_prefixes</literal> then for nodes that does not
belong to any namespace prefix <literal>N</literal> is used,
and for nodes that belong to the default node namespace no
prefix is used. Otherwise, in both case, the prefix associated
to the node namespace with the <literal>ns_prefixes</literal>
is used. If there is not prefix associated to the node
namespace of the node, then <literal>visit</literal> simply
behave as if there was no directive found with the proper
name.</para>
</listitem>
</itemizedlist>
<para>The node for which the user-defined directive was invoked is
available for it as special variable <literal>.node</literal>.
Example:</para>
<programlisting role="template"><#-- Assume that nodeWithNameX?node_name is "x" -->
<#visit nodeWithNameX>
Done.
<#macro x>
Now I'm handling a node that has the name "x".
Just to show how to access this node: this node has ${.node?children?size} children.
</#macro></programlisting>
<para>The output will be something like:</para>
<programlisting role="output"> Now I'm handling a node that has the name "x".
Just to show how to access this node: this node has 3 children.
Done.</programlisting>
<para>If one or more namespaces is specified using the optional
<literal>using</literal> clause, then <literal>visit</literal>
will look for the directives in those namespaces only, with the
earlier specified namespaces in the list getting priority. If no
<literal>using</literal> clause is specified, the namespace or
sequence of namespaces specified with the <literal>using</literal>
clause of the last uncompleted <literal>visit</literal> call is
reused. If there is no such pending <literal>visit</literal> call,
then the current namespace is used. For example, if you execute
this template:</para>
<programlisting role="template"><#import "n1.ftl" as n1>
<#import "n2.ftl" as n2>
<#-- This will call n2.x (because there is no n1.x): -->
<#visit nodeWithNameX using [n1, n2]>
<#-- This will call the x of the current namespace: -->
<#visit nodeWithNameX>
<#macro x>
Simply x
</#macro></programlisting>
<para>and this is <literal>n1.ftl</literal>:</para>
<programlisting role="template"><#macro y>
n1.y
</#macro></programlisting>
<para>and this is <literal>n2.ftl</literal>:</para>
<programlisting role="template"><#macro x>
n2.x
<#-- This will call n1.y, becuase it inherits the "using [n1, n2]" from the pending visit call: -->
<#visit nodeWithNameY>
<#-- This will call n2.y: -->
<#visit nodeWithNameY using .namespace>
</#macro>
<#macro y>
n2.y
</#macro></programlisting>
<para>then this will print:</para>
<programlisting role="output">
n2.x
n1.y
n2.y
Simply x
</programlisting>
<para>If <literal>visit</literal> doesn't find a user-defined
directive in either FTL namespaces with the name identical to the
name deduced with the rules described earlier, then it tries to
find an user-defined directive with name
<literal>@<replaceable>node_type</replaceable></literal>, or if
the node does not support node type property (i.e.
<literal><replaceable>node</replaceable>?node_type</literal>
returns undefined variable), then with name
<literal>@default</literal>. For the lookup, it uses the same
mechanism as was explained earlier. If it still doesn't find an
user-defined directive to handle the node, then
<literal>visit</literal> stops template processing with error.
Some XML specific node types have special handling in this regard;
see: <xref linkend="xgui_declarative_details" />. Example:</para>
<programlisting role="template"><#-- Assume that nodeWithNameX?node_name is "x" -->
<#visit nodeWithNameX>
<#-- Assume that nodeWithNameY?node_type is "foo" -->
<#visit nodeWithNameY>
<#macro x>
Handling node x
</#macro>
<#macro @foo>
There was no specific handler for node ${node?node_name}
</#macro></programlisting>
<para>This would print:</para>
<programlisting role="output">Handling node x
There was no specific handler for node y
</programlisting>
</section>
<section>
<title>Recurse</title>
<anchor xml:id="ref.directive.recurse" />
<para>The <literal><#recurse></literal> directive is really
syntactic sugar. It visits all children nodes of the node (and not
the node itself). So, to write:</para>
<programlisting role="template"><#recurse <replaceable>someNode</replaceable> using <replaceable>someLib</replaceable>></programlisting>
<para>is equivalent to writing:</para>
<programlisting role="template"><#list <replaceable>someNode</replaceable>?children as <replaceable>child</replaceable>><#visit <replaceable>child</replaceable> using <replaceable>someLib</replaceable>></#list></programlisting>
<para>However, target node is optional in the
<literal>recurse</literal> directive. If the target node is
unspecified, it simply uses the <literal>.node</literal>. Thus,
the terse instruction <literal><#recurse></literal> is
equivalent to:</para>
<programlisting role="template"><#list .node?children as child><#visit child></#list></programlisting>
<para>As a side comment for those who are familiar with XSLT,
<literal><#recurse></literal> is pretty much exactly
analogous to the <literal><xsl:apply-templates/></literal>
instruction in XSLT.</para>
</section>
<section>
<title>Fallback</title>
<anchor xml:id="ref.directive.fallback" />
<para>As you could learn earlier, in the documentation of the
<literal>visit</literal> directive, the user-defined directive
that handles the node is maybe searched in multiple FTL
name-spaces. The <literal>fallback</literal> directive can be used
in a user-defined directive that was invoked to handle a node. It
directs FreeMarker to continue the searching for the user-defined
directive in the further name-spaces (that is, in the name-spaces
that are after the name-space of the currently invoked
user-defined directive in the list of name-spaces). If a handler
for the node is found then it is invoked, otherwise
<literal>fallback</literal> does nothing.</para>
<para>A typical usage of this to write customization layer over a
handler library, that sometimes passes the handling to the
customized library:</para>
<programlisting role="template"><#import "/lib/docbook.ftl" as docbook>
<#--
We use the docbook library, but we override some handlers
in this namespace.
-->
<#visit document using [.namespace, docbook]>
<#--
Override the "programlisting" handler, but only in the case if
its "role" attribute is "java"
-->
<#macro programlisting>
<#if .node.@role[0]!"" == "java">
<#-- Do something special here... -->
...
<#else>
<#-- Just use the original (overidden) handler -->
<#fallback>
</#if>
</#macro></programlisting>
</section>
</section>
</section>
</chapter>
<chapter xml:id="ref_specvar">
<title>Special Variable Reference</title>
<indexterm>
<primary>special variable</primary>
</indexterm>
<para>Special variables are variables defined by the FreeMarker engine
itself. To access them, you use the
<literal>.<replaceable>variable_name</replaceable></literal> syntax. For
example, you can't write simply <literal>version</literal>; you have to
write <literal>.version</literal>.</para>
<para>The supported special variables are:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>data_model</literal>: A hash that you can use to
access the data-model directly. That is, variables you did with
<literal>global</literal> directive are not visible here.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>error</primary>
</indexterm><literal>error</literal> (available since FreeMarker
2.3.1): This variable accessible in the body of the <link
linkend="ref.directive.attempt"><literal>recover</literal>
directive</link>, where it stores the error message of the error we
recover from.</para>
</listitem>
<listitem>
<para><literal>globals</literal>: A hash that you can use to access
the globally accessible variables: the data-model and the variables
created with <literal>global</literal> directive. Note that
variables created with <literal>assign</literal> or
<literal>macro</literal> are not globals, thus they never hide the
variables when you use <literal>globals</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>language</primary>
</indexterm><indexterm>
<primary>lang</primary>
</indexterm><literal>lang</literal>: Returns the language part of
the current value of the locale setting. For example if
<literal>.locale</literal> is <literal>en_US</literal>, then
<literal>.lang</literal> is <literal>en</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>locale</primary>
</indexterm><literal>locale</literal>: Returns the current value
of the locale setting. This is a string, for example
<literal>en_US</literal>. For more information about locale strings
<link linkend="ref.directive.setting">see the
<literal>setting</literal> directive</link>.</para>
</listitem>
<listitem>
<para><literal>locals</literal>: A hash that you can use to access
the local variables (the variables created with the
<literal>local</literal> directive, and the parameters of
macro).</para>
</listitem>
<listitem>
<para><literal>main</literal>: A hash that you can use to access the
main <link linkend="dgui_misc_namespace">namespace</link>. Note that
global variables like the variables of data-model are
<emphasis>not</emphasis> visible through this hash.</para>
</listitem>
<listitem>
<para><literal>namespace</literal>: A hash that you can use to
access the current <link
linkend="dgui_misc_namespace">namespace</link>. Note that global
variables like the variables of data-model are
<emphasis>not</emphasis> visible through this hash.</para>
</listitem>
<listitem>
<para><literal>node</literal> (alias <literal>current_node</literal>
for historical reasons): The node you are currently processing with
the visitor pattern (i.e. with the <link
linkend="ref_directive_visit"><literal>visit</literal>,
<literal>recurse</literal>, ...etc. directives</link>). Also, it
initially stores the root node when you use the <link
linkend="pgui_misc_ant">FreeMarker XML Ant task</link>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>now</primary>
</indexterm><indexterm>
<primary>current date-time</primary>
</indexterm><literal>now</literal>: Returns the current date-time.
Usage examples: "<literal>Page generated: ${.now}</literal>",
"<literal>Today is ${.now?date}</literal>", "<literal>The current
time is ${.now?time}</literal>".</para>
</listitem>
<listitem>
<para><indexterm>
<primary>output encoding</primary>
</indexterm><indexterm>
<primary>output charset</primary>
</indexterm><literal>output_encoding</literal> (available since
FreeMarker 2.3.1): Returns the name of the current output charset.
This special variable is not existent if the framework that
encapsulates FreeMarker doesn't specify the output charset for
FreeMarker. <phrase role="forProgrammers">(Programmers can read more
about charset issues <link
linkend="pgui_misc_charset">here...</link>)</phrase></para>
</listitem>
<listitem>
<para><literal>template_name</literal>: The name of the current
template (available since FreeMarker 2.3.14).</para>
</listitem>
<listitem>
<para><indexterm>
<primary>URL escaping charset</primary>
</indexterm><indexterm>
<primary>URL escaping charset</primary>
</indexterm><literal>url_escaping_charset</literal> (available
since FreeMarker 2.3.1): If exists, it stores the name of the
charset that should be used for URL escaping. If this variable
doesn't exist that means that nobody has specified what charset
should be used for URL encoding yet. In this case the <link
linkend="ref_builtin_url"><literal>url</literal> built-in</link>
uses the charset specified by the <literal>output_encoding</literal>
special variable for URL encoding; custom mechanism may follow the
same logic. <phrase role="forProgrammers">(Programmers can read more
about charset issues <link
linkend="pgui_misc_charset">here...</link>)</phrase></para>
</listitem>
<listitem>
<para><literal>vars</literal>: Expression
<literal>.vars.foo</literal> returns the same variable as expression
<literal>foo</literal>. It's useful if for some reasons you have to
use square bracket syntax, since that works only for hash
subvariables, so you need an artificial parent hash. For example, to
read a top-level variable that has a strange name that would confuse
FreeMarker, you can write
<literal>.vars["A strange name!"]</literal>. Or, to access a
top-level variable with dynamic name given with variable
<literal>varName</literal> you can write
<literal>.vars[varName]</literal>. Note that the hash returned by
<literal>.vars</literal> does not support <literal>?keys</literal>
and <literal>?values</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>version</primary>
</indexterm><literal>version</literal>: Returns the FreeMarker
version number as string, for example <literal>2.2.8</literal>. This
can be used to check which FreeMarker version does your application
use, but note that this special variable does not exist prior to the
2.3-final or 2.2.8 versions. The version number of non-final
releases contain abbreviation ``pre'' for ``preview'' (e.g.
<literal>2.3pre6</literal>), or abbrevation ``rc'' for ``release
candidate''.</para>
</listitem>
</itemizedlist>
</chapter>
<chapter xml:id="ref_reservednames">
<title>Reserved names in FTL</title>
<indexterm>
<primary>reserved name</primary>
</indexterm>
<para>The following names cannot be used for top-level variables without
square-bracket syntax (as <literal>.vars["in"]</literal>), since they
are keywords in FTL:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>true</literal>: boolean value ``true''</para>
</listitem>
<listitem>
<para><literal>false</literal>: boolean value ``false''</para>
</listitem>
<listitem>
<para><literal>gt</literal>: comparison operator ``greater
than''</para>
</listitem>
<listitem>
<para><literal>gte</literal>: comparison operator ``greater than or
equivalent''</para>
</listitem>
<listitem>
<para><literal>lt</literal>: comparison operator ``less
than''</para>
</listitem>
<listitem>
<para><literal>lte</literal>: comparison operator ``less than or
equivalent''</para>
</listitem>
<listitem>
<para><literal>as</literal>: used by a few directives</para>
</listitem>
<listitem>
<para><literal>in</literal>: used by a few directives</para>
</listitem>
<listitem>
<para><literal>using</literal>: used by a few directives</para>
</listitem>
</itemizedlist>
</chapter>
<chapter xml:id="ref_deprecated">
<title>Deprecated FTL constructs</title>
<indexterm>
<primary>deprecated</primary>
</indexterm>
<section xml:id="ref_depr_directive">
<title>List of deprecated directives</title>
<para>The following directives are deprecated, but still
working:</para>
<itemizedlist>
<listitem>
<para><link
linkend="ref.directive.call"><literal>call</literal></link>: use
<link linkend="ref.directive.userDefined">user-defined directive
call</link> instead</para>
</listitem>
<listitem>
<para><literal>comment</literal>: This is the old format of
<literal><#--<replaceable>...</replaceable>--></literal>.
Anything between the <literal><#comment></literal> and
<literal></#comment></literal> will be ignored.</para>
</listitem>
<listitem>
<para><literal>foreach</literal>: it is a synonym of the
<literal>list</literal> directive with slightly different
parameter syntax. The syntax is <literal><#foreach
<replaceable>item</replaceable> in
<replaceable>sequence</replaceable>></literal> that is
equivalent with <literal><#list
<replaceable>sequence</replaceable> as
<replaceable>item</replaceable>></literal>.</para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.transform"><literal>transform</literal></link>:
use <link linkend="ref.directive.userDefined">user-defined
directive call</link> instead</para>
</listitem>
</itemizedlist>
<para>The following directives are not working anymore:</para>
<itemizedlist>
<listitem>
<para>Legacy <literal>function</literal>: Originally
<literal>function</literal> was used to define macros, and was
deprecated in favor of the <literal>macro</literal> directive. As
of FreeMarker 2.3, this directive is reintroduced with different
meaning: it is used to define methods.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="ref_depr_builtin">
<title>List of deprecated built-ins</title>
<para>The following built-ins are deprecated, but still
working:</para>
<itemizedlist>
<listitem>
<para><indexterm>
<primary>default built-in</primary>
</indexterm> <literal>default</literal>: This was deprecated
with the introduction of the <link
linkend="dgui_template_exp_missing_default">default value
operator</link>.
<literal><replaceable>exp1</replaceable>?default(<replaceable>exp2</replaceable>)</literal>
is near equivalent with
<literal><replaceable>exp1</replaceable>!<replaceable>exp2</replaceable></literal>,
and
<literal>(<replaceable>exp1</replaceable>)?default(<replaceable>exp2</replaceable>)</literal>
is near equivalent with with
<literal>(<replaceable>exp1</replaceable>)!<replaceable>exp2</replaceable></literal>.
The only difference is that prior to FreeMarker 2.4, the
<literal>default</literal> built-in has always evaluated
<literal><replaceable>exp2</replaceable></literal>, while the
default value operator only evaluates it when the default value is
really needed. Starting from FreeMarker 2.4, however, the
<literal>default</literal> built-in was improved, and behaves
exactly like the default value operator.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>exists built-in</primary>
</indexterm><literal>exists</literal>: This was deprecated with
the introduction of the <link
linkend="dgui_template_exp_missing_test">missing value test
operator</link>.
<literal><replaceable>exp1</replaceable>?exists</literal> is
equivalent with
<literal><replaceable>exp1</replaceable>??</literal>, also
<literal>(<replaceable>exp1</replaceable>)?exists</literal> is
equivalent with with
<literal>(<replaceable>exp1</replaceable>)??</literal>.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>if_exists built-in</primary>
</indexterm><literal>if_exists</literal>: This was deprecated
with the introduction of the <link
linkend="dgui_template_exp_missing_default">default value
operator</link>.
<literal><replaceable>exp1</replaceable>?if_exists</literal> is
similar to <literal><replaceable>exp1</replaceable>!</literal>,
and <literal>(<replaceable>exp1</replaceable>)?if_exists</literal>
is similar to
<literal>(<replaceable>exp1</replaceable>)!</literal>. The
difference is that the default value with
<literal>if_exists</literal> is not only empty string, empty
sequence and empty hashs at the same time, but also boolean
<literal>false</literal> and a transform that does nothing and
ignores all parameters.</para>
</listitem>
<listitem>
<para><indexterm>
<primary>web_safe built-in</primary>
</indexterm><literal>web_safe</literal>: the same as <link
linkend="ref_builtin_html"><literal>html</literal></link></para>
</listitem>
</itemizedlist>
</section>
<section xml:id="ref_depr_oldmacro">
<title>Old-style macro and call directives</title>
<anchor xml:id="ref.directive.oldmacro" />
<anchor xml:id="ref.directive.call" />
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate"><literal><#macro <replaceable>name</replaceable>(<replaceable>argName1</replaceable>, <replaceable>argName2</replaceable>, <replaceable>... argNameN</replaceable>)>
...
</#macro></literal>
<literal><#call <replaceable>name</replaceable>(<replaceable>argValue1</replaceable>, <replaceable>argValue2</replaceable>, <replaceable>... argValueN</replaceable>)></literal></programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>name</replaceable></literal>: name
of the macro (not expression)</para>
</listitem>
<listitem>
<para><literal><replaceable>argName1</replaceable></literal>,
<literal><replaceable>argName2</replaceable></literal>, ...etc.:
the name of the <link linkend="dgui_misc_var">local
variables</link> store the parameter values (not
expression)</para>
</listitem>
<listitem>
<para><literal><replaceable>argValue1</replaceable></literal>,
<literal><replaceable>argValue2</replaceable></literal>,
...etc.: expressions, the value of the parameters</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<note>
<para>This is the documentation of FreeMarker 2.1 macro and macro
related directives. These are still working, but deprecated. You
may want to read the FreeMarker 2.2+ references: <link
linkend="ref.directive.macro">macro, return</link>, <link
linkend="ref.directive.userDefined">user-defined directive
call</link></para>
</note>
<para>A macro is a template fragment with an associated name. You
can use that named fragment on multiple places in your template, so
it helps in repetitive tasks. A macro can have parameters that
influence the output generated when you use the macro.</para>
<para>You define a macro with the <literal>macro</literal>
directive, and then you can use the defined macro in the whole
template. The <literal>macro</literal> directive itself does not
write anything to the output, it just defines the macro. For example
this will define a macro called <literal>warning</literal>:</para>
<programlisting role="template"><emphasis><#macro warning(message)></emphasis>
<div align=center>
<table border=1 bgcolor=yellow width="80%"><tr><td align=center>
<b>Warning!</b>
<p>${message}
</td></tr></table>
</div>
<emphasis></#macro></emphasis></programlisting>
<para>The macro definition body (the section between the macro
start-tag and end-tag) will be processed whenever you use the
<literal>call</literal> directive with the name of the macro. For
example this calls the macro called
<literal>warning</literal>:</para>
<programlisting role="template"><#call warning("Unplug the machine before opening the cover!")></programlisting>
<para>and will write this to the output:</para>
<programlisting role="output"> <div align=center>
<table border=1 bgcolor=yellow width="80%"><tr><td align=center>
<b>Warning!</b>
<p>Unplug the machine before opening the cover!
</td></tr></table>
</div>
</programlisting>
<para>The parameters passed in as parameters to the
<literal>call</literal> directive will be accessible in the macro
definition body as <link linkend="dgui_misc_var">local
variables</link>.</para>
<para>When you call a macro, you must specify the same number of
parameters as were specified in the macro definition. For example if
this is the macro definition:</para>
<programlisting role="template"><#macro test(a, b, c)>Nothing...</#macro></programlisting>
<para>then these are valid macro calls:</para>
<programlisting role="template"><#call test(1, 2, 3)>
<#call test("one", 2 + x, [1234, 2341, 3412, 4123])></programlisting>
<para>If a macro has no parameters, then you can omit the
parentheses:</para>
<programlisting role="template"><#macro test>mooo</#macro>
<#call test></programlisting>
<para>When you define a macro it will be available in the template,
where you have defined it only. But probably you want to use the
same macros in more templates. In this case you can store your macro
definitions in a common file, and then include that file in all
templates where you need those macros.</para>
<para>It's fine to call a macro that's defined further down in the
template <phrase role="forProgrammers">(since macros are defined at
parse time, not in process time)</phrase>. However, if the macro
definitions are inserted with <literal>include</literal> directive,
they will not be available until FreeMarker has executed the
<literal>include</literal> directive.</para>
<para>You can leave a macro definition body before the
<literal></#macro></literal> tag with the
<literal>return</literal> directive.</para>
</section>
</section>
<section xml:id="ref_depr_transform">
<title>Transform directive</title>
<anchor xml:id="ref.directive.transform" />
<indexterm>
<primary>transform directive</primary>
</indexterm>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate">
<literal><transform <replaceable>transVar</replaceable>>
<replaceable>...</replaceable>
</transform></literal>
or
<literal><transform <replaceable>transVar</replaceable> <replaceable>name1</replaceable>=<replaceable>value1</replaceable> <replaceable>name2</replaceable>=<replaceable>value2</replaceable> <replaceable>...</replaceable> <replaceable>nameN</replaceable>=<replaceable>valueN</replaceable>>
<replaceable>...</replaceable>
</transform></literal>
</programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>transVar</replaceable></literal>:
Expression evaluates to a transform</para>
</listitem>
<listitem>
<para><literal><replaceable>name1</replaceable></literal>,
<literal><replaceable>name2</replaceable></literal>, ...
<literal><replaceable>nameN</replaceable></literal>: Name of
parameters. Literal value, not expression.</para>
</listitem>
<listitem>
<para><literal><replaceable>value1</replaceable></literal>,
<literal><replaceable>value2</replaceable></literal>, ...
<literal><replaceable>valueN</replaceable></literal>:
Expressions evaluate to the values of parameters</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<note>
<para>This directive is still working, but deprecated. You may
want to read about <link
linkend="ref.directive.userDefined">user-defined directive
calls</link> to see the replacement.</para>
</note>
<para>Captures the output generated inside its body (i.e. between
its start-tag and end-tag), and let the given transform modify it
before it is written to the final output.</para>
<para>Example:</para>
<programlisting role="template"><p>A very simple HTML file:
<pre>
<emphasis><transform html_escape></emphasis>
<html>
<body>
<p>Hello word!
</body>
</html>
<emphasis></transform></emphasis>
</pre></programlisting>
<para>the output will be:</para>
<programlisting role="output"><p>A very simple HTML file:
<pre>
&lt;html&gt;
&lt;body&gt;
&lt;p&gt;Hello word!
&lt;/body&gt;
&lt;/html&gt;
</pre></programlisting>
<para>Some transforms may take parameters. The name and meaning of
parameters depends on the transform in question. For example here we
give a parameter called ``var'':</para>
<programlisting role="template"><#-- This transform stores the output in the variable x,
rather than sending it to the output -->
<transform capture_output<emphasis> var="x"</emphasis>>
some test
</transform></programlisting>
<para>It is the task of the programmers to put the necessary
transforms into the data-model. For the name and usage of accessible
transforms ask the programmers. <phrase
role="forProgrammers">Initially there is a <link
linkend="pgui_config_sharedvariables">shared variable</link> for
most transforms in the
<literal>freemarker.template.utility</literal> package. For more
information see: <xref
linkend="pgui_config_sharedvariables" /></phrase></para>
</section>
</section>
<section xml:id="ref_depr_oldsyntax">
<title>Old FTL syntax</title>
<indexterm>
<primary>strict syntax</primary>
</indexterm>
<indexterm>
<primary>old FTL syntax</primary>
</indexterm>
<indexterm>
<primary>new FTL syntax</primary>
</indexterm>
<para>With the old FTL syntax the <literal>#</literal> was not
required (prior 2.1 not even allowed) in the FTL tags. For example,
you could write this:</para>
<programlisting role="template"><html>
<head>
<title>Welcome!</title>
</head>
<body>
<h1>Welcome ${user}!</h1>
<p>We have there animals:
<ul>
<emphasis><list animals as being></emphasis>
<li>${being.name} for ${being.price} Euros
<emphasis></list></emphasis>
</ul>
<emphasis><include "common_footer.html"></emphasis>
</body>
</html></programlisting>
<para>While the <literal>#</literal>-less syntax was more natural for
HTML authors, it had too many drawbacks, so finally we have decided to
deprecate it. With the newer syntax (a.k.a ``strict syntax''), the
<literal>#</literal> is strictly required. That is, things like
<literal><include "common_footer.html"></literal> will go to the
output as is, since they are not considered as FTL tags. Note that
user-defined directives use <literal>@</literal> <emphasis>instead
of</emphasis> <literal>#</literal>.</para>
<para>However, to give users time to prepare for this change, in
FreeMarker 2.1 and 2.2 the usage of <literal>#</literal> is optional,
unless the programmer enables strict syntax mode in the FreeMarker
configuration by calling <literal>setStrictSyntaxMode(true)</literal>
on <literal>Configuration</literal>. In fact, we strongly recommend
this to programmers. Starting from some later release this setting
will be initially set to <literal>true</literal>. Also, you can
specify if you want to use strict syntax or old syntax in the template
files with the <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link>.</para>
<para>The advantages of ``strict syntax'' over the legacy FTL syntax
are:</para>
<itemizedlist>
<listitem>
<para>Since all
<literal><#<replaceable>...</replaceable>></literal> and
<literal></#<replaceable>...</replaceable>></literal> are
reserved for FTL:</para>
<itemizedlist>
<listitem>
<para>We can introduce new directives without breaking
backward compatibility.</para>
</listitem>
<listitem>
<para>We can detect if you made a typo, i.e.
<literal><#inculde
<replaceable>...</replaceable>></literal> is treated as
parse-time error, rather than silently treated as simple
text.</para>
</listitem>
<listitem>
<para>It is easier for third-party tools to handle templates
(e.g. do syntax highlighting), especially since they don't
have to know about the new directives introduced with new
releases.</para>
</listitem>
<listitem>
<para>Templates are more readable, since it is easier to spot
<literal><#...></literal> tags embedded into HTML or
other markup.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal><#</literal> and <literal></#</literal> is
illegal XML (except in CDATA sections), and illegal in almost all
other SGML applications, so they can't interfere with the tags
used in the static text parts (e.g. if you have
<literal>include</literal> element in the generated XML).</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="ref_depr_numerical_interpolation">
<title>#{...}: Numerical interpolation</title>
<indexterm>
<primary>#{...}</primary>
</indexterm>
<para>Deprecated: Use the <link
linkend="ref.setting.number_format"><literal>number_format</literal>
setting</link> and <link linkend="ref_builtin_string_for_number">the
<literal>string</literal> built-in</link> instead. For formatting for
computer audience (i.e., no localized formatting) use the <link
linkend="ref_builtin_c"><literal>c</literal> built-in</link> (like
<literal><replaceable>number</replaceable>?c</literal>).</para>
<section>
<title>Synopsis</title>
<programlisting role="metaTemplate"><literal>#{<replaceable>expression</replaceable>}</literal>
or
<literal>#{<replaceable>expression</replaceable>; <replaceable>format</replaceable>}</literal></programlisting>
<para>Where:</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal><replaceable>expression</replaceable></literal>:
expression that can be evaluated as a number.</para>
</listitem>
<listitem>
<para><literal><replaceable>format</replaceable></literal>:
optional format specifier.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Description</title>
<para>The numerical interpolation is used to output a number value.
If the expression doesn't evaluate to a number, the evaluation ends
with an error.</para>
<para>The optional format specifier specifies the minimum and the
maximum number of displayed fractional digits using syntax
<literal>m<replaceable>min</replaceable>M<replaceable>max</replaceable></literal>.
For example, <literal>m2M5</literal> means "at least two, at most
five fractional digits". The minimum or the maximum specifier part
can be omitted. If only the minimum is specified, the maximum is
equal to the minimum. If only maximum is specified, the minimum is
0.</para>
<para>The decimal separator character of the output is
internationalized (according the current locale setting), which
means that it is not necessarily a dot.</para>
<para>Unlike <literal>${...}</literal>, <literal>#{...}</literal>
ignores the <link
linkend="ref.setting.number_format"><literal>number_format</literal>
setting</link>. This is actually a backward compatibility quirk, but
it can be useful when you print numbers in situations like
<literal><a href="quertyDatabase?id=#{id}"></literal>, where
you surely don't want grouping separators or something fancy like
that. However, starting from FreeMarker 2.3.3 rather use the <link
linkend="ref_builtin_c"><literal>?c</literal> built-in</link> for
this purpose, like <literal><a
href="quertyDatabase?id=${id?c}"></literal>.</para>
<para>Examples. Assume that <literal>x</literal> is
<literal>2.582</literal> and <literal>y</literal> is
<literal>4</literal>:</para>
<programlisting role="template"> <#-- If the language is US English the output is: -->
#{x} <#-- 2.582 -->
#{y} <#-- 4 -->
#{x; M2} <#-- 2.58 -->
#{y; M2} <#-- 4 -->
#{x; m1} <#-- 2.6 -->
#{y; m1} <#-- 4.0 -->
#{x; m1M2} <#-- 2.58 -->
#{y; m1M2} <#-- 4.0 --></programlisting>
</section>
</section>
</chapter>
</part>
<part xml:id="app">
<title>Appendixes</title>
<appendix xml:id="app_faq">
<title>FAQ</title>
<indexterm>
<primary>FAQ</primary>
</indexterm>
<qandaset>
<qandaentry xml:id="faq_jsp_vs_freemarker">
<question>
<para>JSP versus FreeMarker?</para>
<indexterm>
<primary>JSP</primary>
</indexterm>
</question>
<answer>
<para>Note: JSP 1.x was really bad as an MVC template engine
because it was not made for that, so I don't deal with that here.
We compare FreeMarker with the JSP 2.0 + JSTL combo.</para>
<para>FreeMarker Pros:</para>
<itemizedlist>
<listitem>
<para>FreeMarker is not tied to Servlets, networking or the
Web; it is just a class library to generate text output by
merging a template with Java objects (the data-model). You can
execute templates anywhere and anytime; no HTTP request
forwarding or similar tricks needed, no Servlet environment
needed at all. Because of this you can easily integrate it
into any system.</para>
</listitem>
<listitem>
<para>No servlet specific scopes and other highly technical
things in templates. It was made for MVC from the beginning,
it focuses only on the presentation.</para>
</listitem>
<listitem>
<para>You can load the templates from anywhere; from the class
path, from a data-base, etc.</para>
</listitem>
<listitem>
<para>Locale sensitive number and date formatting by default.
Since we mostly output for a human audience all you need to do
is just write <literal>${x}</literal> rather than
<literal><fmt:formatNumber value="${x}" /></literal>.
You can easily switch this behavior and output non-localized
numbers by default.</para>
</listitem>
<listitem>
<para>Easier to define ad-hoc macros and functions.</para>
</listitem>
<listitem>
<para>No sweeping errors under the carpet. Missing variables
will cause an error by default, and not silently default to
arbitrary values. Also, <literal>null</literal>-s are not
treated silently as 0/false/empty string. <link
linkend="faq_picky_about_missing_vars">See more about this
here...</link></para>
</listitem>
<listitem>
<para>``Object wrapping''. This lets you show the objects to
templates in a customized, presentation oriented way (e.g.
<link linkend="xgui_imperative_learn">see here</link> how a
W3C DOM nodes can be seen by templates using this
technology.)</para>
</listitem>
<listitem>
<para>Macros and functions are just variables (compare it to
how JSP custom tags work), so they can be easily passed around
as parameter values, put into the data-model, ...etc, just
like any other value.</para>
</listitem>
<listitem>
<para>Easier to read, more terse syntax. For example:
<literal><#if x>...</#if></literal> instead of
<literal><c:if
test="${x}">...</c:if></literal></para>
</listitem>
<listitem>
<para>Virtually unnoticeable delay when visiting a page for
the first time (or after it was changed), because no expensive
compilation happens.</para>
</listitem>
</itemizedlist>
<para>FreeMarker Cons:</para>
<itemizedlist>
<listitem>
<para>Not a ``standard''. There are fewer tools and IDE
integrations, fewer developers knows it and there's much less
industry support in general. (However, JSP tag libraries work
without modification in FreeMarker templates, if they are not
using <literal>.tag</literal> files.)</para>
</listitem>
<listitem>
<para>Since macros and function are just variables, incorrect
directive and parameter names and missing required parameters
can be detected only on runtime.</para>
</listitem>
<listitem>
<para>Its syntax doesn't follow the HTML/XML rules apart from
some visual similarity, which is confusing for new users.
(It's the price of the terseness...)</para>
</listitem>
<listitem>
<para>Doesn't work with JSF. (It could work technically, but
nobody has implemented that yet.)</para>
</listitem>
</itemizedlist>
<para>You may read this if you are considering replacing JSP with
FreeMarker: <xref linkend="pgui_misc_servlet_model2" /></para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_jsp_vs_velocity">
<question>
<para>Velocity versus FreeMarker?</para>
<indexterm>
<primary>Velocity</primary>
</indexterm>
</question>
<answer>
<para><link
xlink:href="http://jakarta.apache.org/velocity/index.html">Velocity</link>
is a simpler, more lightweight tool. Thus, it does not address
many tasks that FreeMarker does, and its template language is less
powerful in general, but it is simpler; visit <link
xlink:href="http://freemarker.org/fmVsVel.html">http://freemarker.org/fmVsVel.html</link>
for details. Currently (2005) Velocity has wider third party
support and larger user community.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_picky_about_missing_vars">
<question>
<para>Why is FreeMarker so picky about <literal>null</literal>-s
and missing variables, and what to do with it?</para>
</question>
<answer>
<para>To recapitulate what's this entry is about: FreeMarker by
default treats an attempt to access a non-existent variable or a
<literal>null</literal> value (<link linkend="faq_null">this two
is the same for FreeMarker</link>) as error, which aborts the
template execution.</para>
<para>First of all, you should understand the reason of being
picky. Most scripting languages and template languages are rather
forgiving with missing variables (and with
<literal>null</literal>-s), and they usually treat them as empty
string and/or 0 and/or logical false. This behavior has several
problems:</para>
<itemizedlist>
<listitem>
<para>It potentially hides accidental mistakes, like a typo in
a variable name, or when the template author refers to a
variable that the programmer doesn't put into the data-model,
or for which the programmer uses a different name. Human is
prone to do such accidental mistakes, computers are not, so
missing this opportunity that the template engine can show
these errors is a bad business. Even if you very carefully
check the output of the templates during development, it is
easy to look over mistakes like <literal><#if
hasDetp><replaceable>print dept
here...</replaceable></#if></literal>, which would then
silently never print the dept of the visitor, since you have
mistyped the variable name (it should be
<literal>hasDept</literal>). Also think about maintenance,
when you later modify your application... most probably you
will not re-check templates that carefully each time.</para>
</listitem>
<listitem>
<para>Makes dangerous assumptions. The script language or
template engine knows nothing about the application domain, so
when it decides the value of something it don't know to be
0/false, it is a quite irresponsible and arbitrary thing. Just
because it is not know what's your current bank account
balance, can we just say it is $0 (and how easy it is to
accidentally write <literal>Balance: ${balanace}</literal>)?
Just because it is not known if a patient has penicillin
allergy, we can just say he/she doesn't have (and how easy it
is to accidentally write <literal><#if
hasPenicilinAllergy><replaceable>Warning...</replaceable><#else><replaceable>Allow...</replaceable></#if></literal>;
there is a typo in this, if you didn't see)? Just consider the
implications of such mistakes for a moment. They can be quite
severe and troubling. Showing an error page is often better
than showing incorrect information that formally looks
good.</para>
</listitem>
</itemizedlist>
<para>Being not picky is mostly sweeping under the carpet in this
case (not facing with the problems), which of course most people
feels more convenient, but still... we believe that in most cases
being strict will save your time and increase your software
quality in the long run.</para>
<para>On the other hand, we recognize that there are cases where
you don't want FreeMarker to be that picky with good reason, and
there is solution for them:</para>
<itemizedlist>
<listitem>
<para>It's often normal that your data-model contains
<literal>null</literal>-s or have optional variables. In such
cases use <link linkend="dgui_template_exp_missing">these
operators</link>. If you use them too often, try to rethink
your data-model, because depending on them too much is not
just results in awkward verbose templates, but increases the
probability of hiding errors and printing arbitrary incorrect
output (for the reasons described earlier).</para>
</listitem>
<listitem>
<para>On a production server you may rather want to show an
incomplete/damaged page than an error page. In this case you
can <link linkend="pgui_config_errorhandling">use other error
handler</link> than the default. Error handlers can be made
that rather skip the problematic part than abort the whole
page rendering. Note, however, that although the error
handlers don't give arbitrary default values to variables, for
pages that show critical information it's maybe still better
to show an error page. (Another feature you may interested in:
<link linkend="ref_directive_attempt">the
<literal>attempt</literal>/<literal>recover</literal>
directives</link>)</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>The documentation writes about feature
<replaceable>X</replaceable>, but it seems that FreeMarker doesn't
know that, or it behaves in a different way as documented, or a
bug that was supposedly fixed is still present.</para>
</question>
<answer>
<para>Are you sure that you are using the documentation written
for the same version of FreeMarker that you actually use?
Especially, note that our online documentation is for the latest
usable FreeMarker release. You may use an older release.</para>
<para>Are you sure that the Java class loader finds the same
<literal>freemarker.jar</literal> that you expect to use? Maybe
there is an older version of <literal>freemarker.jar</literal>
around (such as in the Ant <literal>lib</literal> directory),
which has higher priority. To check this, try to print the version
number in a template with <literal>${.version}</literal>. If it
dies with ``Unknown built-in variable: version'' error message,
then you use a release before 2.3-final or 2.2.8, but you can
still try to get the version number in the Java code of your
application with
<literal>Configuration.getVersionNumber()</literal>. If this
method is not present either, then you are using an early
2.3-preview, or a version before 2.2.6.</para>
<para>If you think that the documentation or FreeMarker is wrong,
please report it using the bug tracker, or the mailing list, or
the forums on <link
xlink:href="http://sourceforge.net/projects/freemarker/">http://sourceforge.net/projects/freemarker/</link>.
Thank you!</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_number_grouping">
<question>
<para>Why does FreeMarker print the numbers with strange
formatting (as 1,000,000 or 1 000 000 instead of 1000000)?</para>
</question>
<answer>
<para>FreeMarker uses the locale-sensitive number formatting
capability of the Java platform. The default number format for
your locale may uses grouping or other unwanted formatting. To
prevent this, you have to override the number format suggested by
the Java platform with the <literal>number_format</literal> <link
linkend="pgui_config_settings">FreeMarker setting</link>. For
example:</para>
<programlisting role="unspecified">cfg.setNumberFormat("0.######"); // now it will print 1000000
// where cfg is a freemarker.template.Configuration object</programlisting>
<para>Note however than humans often find it hard to read big
numbers without grouping separator. So in general it is
recommended to keep them, and in cases where the numbers are for
''computer audience'' that is confused on the grouping separators,
use the <link linkend="ref_builtin_c"><literal>c</literal>
built-in</link>. For example:</para>
<programlisting role="template"><a href="/shop/productdetails?id=${<emphasis>product.id?c</emphasis>}">Details...</a></programlisting>
</answer>
</qandaentry>
<qandaentry xml:id="faq_number_decimal_point">
<question>
<para>Why does FreeMarker print bad decimal and/or grouping
separator symbol (as 3.14 instead of 3,14)?</para>
</question>
<answer>
<para>Different countries use different decimal/grouping separator
symbols. If you see incorrect symbols, then probably your locale
is not set properly. Set the default locale of the JVM or override
the default locale with the <literal>locale</literal> <link
linkend="pgui_config_settings">FreeMarker setting</link>. For
example:</para>
<programlisting role="unspecified">cfg.setLocale(java.util.Locale.ITALY);
// where cfg is a freemarker.template.Configuration object</programlisting>
<para>However, sometimes you want to output a number not for human
audience, but for ``computer audience'' (like you want to print a
size in CSS), in which case you must use dot as decimal separator,
regardless of the locale (language) of the page. For that use the
<link linkend="ref_builtin_c"><literal>c</literal>
built-in</link>, for example:</para>
<programlisting role="template">font-size: ${<emphasis>fontSize?c</emphasis>}pt;</programlisting>
</answer>
</qandaentry>
<qandaentry xml:id="faq_number_boolean_formatting">
<question>
<para>Why does FreeMarker give an error when I try to print a
boolean like <literal>${aBoolean}</literal>, and how to fix
it?</para>
</question>
<answer>
<para>Unlike numbers, booleans has no commonly accepted format,
not even a common format within the same page. Like when you show
on a HTML page if a product is washable, you will hardly want to
show for the visitor "Washable: true", but rather "Washable: yes".
So we force the template author (by <literal>${washable}</literal>
causing error) to find out with his human knowledge how the
boolean value should be shown at the given place. The common way
of formatting a boolean is like <literal>${washable?string("yes",
"no")}</literal>, <literal>${caching?string("Enabled",
"Disabled")}</literal>, <literal>${heating?string("on",
"off")}</literal>, etc. However, for generating source code
<literal>${washable?string("true", "false")}</literal> would be
very often used, so <literal>${washable?string}</literal> (i.e.,
omitting the parameter list) is equivalent with that.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_alternative_syntax">
<question>
<para>The <literal><</literal> and <literal>></literal> of
FreeMarker tags confuses my editor or the XML parser. What to
do?</para>
</question>
<answer>
<para>Starting from FreeMarker 2.3.4 you can use
<literal>[</literal> and <literal>]</literal> instead of
<literal><</literal> and <literal>></literal>. For more
details <link linkend="dgui_misc_alternativesyntax">read
this...</link></para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_legal_variable_names">
<question>
<para>What are the legal variable names?</para>
<indexterm>
<primary>variables</primary>
<secondary>names</secondary>
</indexterm>
</question>
<answer>
<para>FreeMarker has no limitations regarding the characters used
in variable names, nor regarding the length of the variable names,
but for your convenience try to chose variable names that can be
used with the simple variable reference expressions (see it <link
linkend="dgui_template_exp_var_toplevel">here</link>). If you have
to choose a more extreme variable name, that's not a bid problem
either: <link linkend="faq_strange_variable_name">see
here</link>.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_strange_variable_name">
<question>
<para>How can I use variable (macro) names that contain space,
dash or other special characters?</para>
</question>
<answer>
<para>If you have a variable with strange name, such as
<literal>foo-bar</literal>, FreeMarker will misinterpret what do
you want when you write thing as <literal>${foo-bar}</literal>. In
this concrete case, it will believe that you want subtract the
value of <literal>bar</literal> from <literal>foo</literal>. This
FAQ entry explains how to handle situations like this.</para>
<para>First of all it should be clean that these are just
syntactical problems. FreeMarker has no limitations regarding the
characters used in variable names, nor regarding the length of the
variable names, but sometimes you need to use syntactical
tricks.</para>
<para>If you want to read the variable: Use the square bracket
syntax. An example of square bracket syntax is
<literal>baaz["foo"]</literal>, which is equivalent with
<literal>baaz.foo</literal>. As the subvariable name with the
square bracket syntax is a string literal (in fact, arbitrary
expression), it let you write <literal>baaz["foo-bar"]</literal>.
Now you may say that it can be used for hash subvariables only.
Yes, but top-level variables are accessible through special hash
variable <literal>.vars</literal>. For example,
<literal>foo</literal> is equivalent with
<literal>.vars["foo"]</literal>. So you can also write
<literal>.vars["foo-bar"]</literal>. Naturally, this trick works
with macro invocations too:
<literal><@.vars["foo-bar"]/></literal></para>
<para>If you want to create or modify the variable: All directives
that let you create or modify a variable (such as
<literal>assign</literal>, <literal>local</literal>,
<literal>global</literal>, <literal>macro</literal>,
<literal>function</literal>, etc.) allows the quotation of the
destination variable name. For example, <literal><#assign foo =
1></literal> is the same as <literal><#assign "foo" =
1></literal>. So you can write things like <literal><#assign
"foo-bar" = 1></literal> and <literal><#macro
"foo-bar"></literal>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why do I get "java.lang.IllegalArgumentException: argument
type mismatch" when I try to use <replaceable>X</replaceable> JSP
custom tag?</para>
</question>
<answer>
<para>On JSP pages you quote all parameter (attribute) values, it
does not mater if the type of the parameter is string or boolean
or number. But since custom tags are accessible in FTL templates
as plain user-defined FTL directives, you have to use the FTL
syntax rules inside the custom tags, not the JSP rules. Thus,
according to FTL rules, you must not quote boolean and numerical
parameter values, or they are interpreted as string values, and
this will cause a type mismatch error when FreeMarker tries to
pass the value to the custom tag that expects non-string
value.</para>
<para>For example, the <literal>flush</literal> parameter to
Struts Tiles <literal>insert</literal> tag is boolean. In JSP the
correct syntax was:</para>
<programlisting role="template"><tiles:insert page="/layout.jsp" <emphasis>flush="true"</emphasis>/>
<replaceable>...</replaceable></programlisting>
<para>but in FTL you should write:</para>
<programlisting role="template"><@tiles.insert page="/layout.ftl" <emphasis>flush=true</emphasis>/>
<replaceable>...</replaceable></programlisting>
<para>Also, for similar reasons, this is wrong:</para>
<programlisting role="template"><tiles:insert page="/layout.jsp" <emphasis>flush="${needFlushing}"</emphasis>/>
<replaceable>...</replaceable></programlisting>
<para>and you should write:</para>
<programlisting role="template"><tiles:insert page="/layout.jsp" <emphasis>flush=needFlushing</emphasis>/>
<replaceable>...</replaceable></programlisting>
<para>(Not <literal>flush=${needFlushing}</literal>!)</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_servlet_include">
<question>
<para>How to include other resources in a way as
<literal>jsp:include</literal> does it?</para>
</question>
<answer>
<para>Not with <literal><#include ...></literal>, as that
just includes another FreeMarker template without involving the
Servlet container.</para>
<para>Since the inclusion method you look for is Servlet-related,
and pure FreeMarker is unaware of Servlets or even HTTP, it's the
Web Application Framework that decides if you can do this and if
so how. For example, in Struts 2 you can do this like this:</para>
<programlisting role="template"><@s.include value="/WEB-INF/just-an-example.jspf" /></programlisting>
<para>If the FreeMarker support of the Web Application Framework
is based on
<literal>freemarker.ext.servlet.FreemarkerServlet</literal>, then
you can also do this (since FreeMarker 2.3.15):</para>
<programlisting role="template"><@include_page path="/WEB-INF/just-an-example.jspf" /></programlisting>
<para>but if the Web Application Framework provides its own
solution, then you may prefer that, after all it may does
something special.</para>
<para>For more information about <literal>include_page</literal>
<link linkend="pgui_misc_servlet_include">read
this...</link></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How can I get the parameters to my
plain-Java-method/<literal>TemplateMethodModelEx</literal>/<literal>TemplateTransformModel</literal>/<literal>TemplateDirectiveModel</literal>
implementation as plain
<literal>java.lang.*</literal>/<literal>java.util.*</literal>
objects?</para>
</question>
<answer>
<para>Unfortunately, there is no simple general-purpose solution
for this problem. The problem is that FreeMarker object wrapping
is very flexible, which is good when you access variables from
templates, but makes unwrapping on the Java side a tricky
question. For example, it is possible to wrap a
non-<literal>java.util.Map</literal> object as
<literal>TemplateHashModel</literal> (FTL hash variable). But
then, it can't be unwrapped to <literal>java.util.Map</literal>,
since there is no wrapped <literal>java.util.Map</literal> around
at all.</para>
<para>So what to do then? Basically there are two cases:</para>
<itemizedlist>
<listitem>
<para>Directives and methods that are written for presentation
purposes (like kind of ``tools'' for helping FreeMarker
templates) should declare their arguments as
<literal>TemplateModel</literal>-s and the more specific sub
interfaces of that. After all, the object wrapping is about
apparently transforming the data-model to something that
serves the purpose of the presentation layer, and these
methods are part of the presentation layer.</para>
</listitem>
<listitem>
<para>Methods that are not for presentation related tasks (but
for business logic and like) should be implemented as plain
Java methods, and should not use any FreeMarker specific
classes at all, since according the MVC paradigm they must be
independent of the presentation technology (FreeMarker). If
such a method is called from a template, then it is the
responsibility of the <link
linkend="pgui_datamodel_objectWrapper">object wrapper</link>
to ensure the conversion of the arguments to the proper type.
If you use the <literal>DefaultObjectWrapper</literal> or the
<link
linkend="pgui_misc_beanwrapper"><literal>BeansWrapper</literal></link>
then this will happen automatically (but be sure you are using
at least FreeMarker 2.3.3). Furthermore if you use
<literal>BeansWrapper</literal>, then the method will surely
get exactly the same instance that was earlier wrapped (as far
as it was wrapped by the
<literal>BeansWrapper</literal>).</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why I can't use non-string key in the
<literal>myMap[myKey]</literal> expression? And what to do
now?</para>
<indexterm>
<primary>hash</primary>
<secondary>key type</secondary>
</indexterm>
</question>
<answer>
<para>The ``hash'' type of the FreeMarker Template Language (FTL)
is not the same as Java's <literal>Map</literal>. FTL's hash is an
associative array too, but it uses string keys exclusively. This
is because it was introduced for subvariables (as
<literal>password</literal> in <literal>user.password</literal>,
which is the same as <literal>user["password"]</literal>), and
variable names are strings.</para>
<para>So FTL's hashes are not general purpose associate arrays
that could be used for looking up values with keys of arbitrary
type. FTL is presentation oriented language, and it has no feature
dedicated for that purpose. It has, however, methods. Methods are
part of the data-model, and they can do all kind of fancy
data-model related calculations, so of course you can add some
methods to the data-model for <literal>Map</literal> lookup. The
bad news is that the building of the data-model, as it's an
application specific issue, is the task of the programmers who use
FreeMarker, so it's their task to ensure that such methods are
present there to serve the template authors. (However, when
template authors need to call methods that are not about
presentation, then consider if the data-model is simple enough.
Maybe you should push some calculations back to the data-model
building phase. Ideally the data-model contains what should be
displayed, and not something that serves as the base of further
calculations.)</para>
<para>If you read the programmer's guide, then you know that
technically, the data-model is a tree of
<literal>freemarker.template.TemplateModel</literal> objects. The
building of the data-model usually (but not necessary) happens by
automatically wrapping (enclosing) plain Java objects into
<literal>TemplateModel</literal> objects. The object that does
this wrapping is the object wrapper, and it's specified when you
configure FreeMarker. FreeMarker comes with a few object wrapper
implementations out-of-the-box, and probably the most widely used
of them is <link
linkend="pgui_misc_beanwrapper"><literal>freemarker.ext.beans.BeansWrapper</literal></link>.
If you use an instance of this as the object wrapper, then
<literal>java.util.Map</literal>-s you put into the data-model
will also act as a method, so you can write
<literal>myMap(myKey)</literal> in the template, that will
internally call <literal>Map.get(myKey)</literal>. There will be
no restriction regarding the type of <literal>myKey</literal>, as
<literal>Map.get(Object key)</literal> has no such restriction. If
the value of <literal>myKey</literal> was wrapped with
<literal>BeansWrapper</literal> or other object wrapper whose
wrapped objects support unwrapping, or it is given as literal in
the template, then the value will be automatically unwrapped to
plain Java object before the actual invocation of the
<literal>Map.get(Object key)</literal> method, so it will not be
invoked with <literal>TemplateModel</literal>-s.</para>
<para>But there still will be a problem. Java's
<literal>Map</literal> is particular about the exact class of the
key, so for numerical keys calculated inside the templates you
will have to cast them to the proper Java type, otherwise the item
will not be found. For example if you use
<literal>Integer</literal> keys in a Map, then you have to write
<literal>${myMap.get(123?int)}</literal>. This is an ugly effect
caused by that FTL's deliberately simplified type system just has
a single numerical type, while Java distinguishes a lot of
numerical types. (Ideally, in the above case, the programmers
ensure that the <literal>get</literal> method automatically
converts the key to <literal>Integer</literal>, so it's not the
problem of the template author. This can be done with wrapper
customization, but the wrapper has to know that the particular
<literal>Map</literal> object uses <literal>Integer</literal>
keys, which assumes application specific knowledge.) Note that the
casting is not needed when the key value comes directly from the
data-model (i.e. you didn't modified its value with arithmetical
caluclations in the template), including the case when it's the
return value of a method, and it was of the proper class before
wrapping, because then the result of the unwrapping will be of the
original type.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_simple_map">
<question>
<para>When I list the contents of a map (a hash) with
<literal>?keys</literal>/<literal>?values</literal>, I get the
<literal>java.util.Map</literal> methods mixed with the real map
entries. Of course, I only want to get the map entries.</para>
</question>
<answer>
<para>Certainly you are using <literal>BeansWrapper</literal> as
your object wrapper, or a custom subclass of it, and the
<literal>simpleMapWrapper</literal> property of that is left to
<literal>false</literal>. Unfortunatelly, it's the default (for
backward compatibility), so you have to explicitly set it to
<literal>true</literal> where you create the object
wrapper.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_modify_seq_and_map">
<question>
<para>How can I modify sequences (lists) and hashes (maps) in
FreeMarker templates?</para>
<indexterm>
<primary>modify hashes</primary>
</indexterm>
<indexterm>
<primary>modify sequences</primary>
</indexterm>
<indexterm>
<primary>sequence</primary>
<secondary>modify</secondary>
</indexterm>
<indexterm>
<primary>hash</primary>
<secondary>modify</secondary>
</indexterm>
</question>
<answer>
<para>First of all, you may don't want to modify the
sequence/hash, just concatenate (add) two or more of them, which
results in a new sequence/hash, rather than modifying an existing
one. In this case use the <link
linkend="dgui_template_exp_sequenceop_cat">sequence
concatenation</link> and <link
linkend="dgui_template_exp_hashop_cat">hash concatenation
operators</link>. Also, you may use the <link
linkend="dgui_template_exp_seqenceop_slice">subsequence
operator</link> instead of removing sequence items. However, be
aware of the performance implications: these operations are fast,
but the hashes/sequences that are the result of many subseqent
applications of these operations (i.e. when you use the result of
the operation as the input of yet another operation, and so on)
will be slow to read.</para>
<para>Now if you still want to modify sequences/hashes, then read
on...</para>
<para>The FreeMarkes Template Language doesn't support the
modification of sequences/hashes. It's for displaying already
calculated things, not for calculating data. Keep templates
simple. But don't give it up, you will see some advices and tricks
bellow.</para>
<para>The best is if you can divide the work between the
data-model builder program and the template so that the template
doesn't need to modify sequences/hashes. Maybe if you rethink your
data-model, you will realize this is possible. But, seldom there
are cases where you need to modify sequences/hashes for some
complex but purely presentation related algorithms. It seldom
happens, so think twice whether that calculation (or parts of it)
rather belongs to the data-model domain than to the presentation
domain. Let's assume you are sure it belongs to the presentation
domain. For example, you want to display a keyword index on some
very smart way, whose algorithm need you to create and write some
sequence variables. Then you should do something like this (ugly
situations has ugly solutions...):</para>
<programlisting role="template"><#assign caculatedResults =
'com.example.foo.SmartKeywordIndexHelper'?new().calculate(keywords)>
<#-- some simple algorithms comes here, like: -->
<ul>
<#list caculatedResults as kw>
<li><a href="${kw.link}">${kw.word}</a>
</#list>
</ul></programlisting>
<para>That is, you move out the complex part of the presentation
task from the template into Java code. Note that it doesn't affect
the data-model, so the presentation is still kept separated from
other the other application logic. Of course the drawback is that
for this the template author will need the help of a Java
programmer, but for complex algorithms that's probably needed
anyway.</para>
<para>Now, if you still say you need to modify sequences/hashes
directly with the FreeMarker template, here are two solutions, but
please read the warning after them:</para>
<itemizedlist>
<listitem>
<para>You can write a <literal>TemplateMethodModelEx</literal>
and <literal>TemplateDirectiveModel</literal> implementation
that can modify certain types of sequences/hashes. Just
certain types, because
<literal>TemplateSequenceModel</literal> and
<literal>TemplateHashModel</literal> doesn't have methods for
modification, so you will need the sequence or hash to
implement some additional methods. An example of this solution
can be seen in FMPP. It allows you to do things like this
(<literal>pp</literal> stores the services provided by FMPP
for templates):</para>
<programlisting role="template"><#assign a = pp.newWritableSequence()>
<@pp.add seq=a value="red" /></programlisting>
<para>The <literal>pp.add</literal> directive works only with
sequences that were created with
<literal>pp.newWritableSequence()</literal>. So for example
the template author can't modify a sequence that comes from
the data-model with this.</para>
</listitem>
<listitem>
<para>A sequence can have some methods/directives if you use a
customized wrapper (so you can <literal><@myList.append foo
/></literal>). (Also, if you use
<literal>BeansWrapper</literal> and configure it so it exposes
the public methods, you can use the Java API for variables
that are for <literal>java.util.Map</literal>-s and
<literal>java.util.List-s</literal>. Just like with Apache
Velocity.)</para>
</listitem>
</itemizedlist>
<para>But beware, these solutions have a problem: The <link
linkend="dgui_template_exp_sequenceop_cat">sequence
concatenation</link>, <link
linkend="dgui_template_exp_seqenceop_slice">sequence slice</link>
operator (like <literal>seq[5..10]</literal>) and
<literal>?reverse</literal> do not copy the original sequence,
just wraps it (for efficiency), so the resulting sequence will
change if the original sequence is changed later (an abnormal
aliasing effect). The same problem exists with the result of <link
linkend="dgui_template_exp_hashop_cat">hash concatenation</link>;
it just wraps the two hashes, so the resulting hash will magically
change if you modify the hashes you have added earlier. As a
work-around, after you did the above problematic operations,
either be sure you will not modify the objects that were used as
input, or create a copy of the result with a method provided by
the solution described in above two points (e.g. in FMPP you could
do <literal><#assign b =
pp.newWritableSequence(a[5..10])></literal> and
<literal><#assign c = pp.newWritableHash(hashA +
hashB)></literal>). Of course this is easy to miss... so again,
rather try to build the data-model so you will not need to modify
collections, or use a presentation task helper class as was shown
earlier.</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq_null">
<question>
<para>What about <literal>null</literal> and the FreeMarker
template language? <indexterm>
<primary>null</primary>
</indexterm></para>
</question>
<answer>
<para>The FreeMarker template language doesn't know the Java
language <literal>null</literal> at all. It doesn't have
<literal>null</literal> keyword, and it can't test if something is
<literal>null</literal> or not. When it technically faces with a
<literal>null</literal>, it treats it exactly as a missing
variable. For example, both if <literal>x</literal> is
<literal>null</literal> in the data-model and if it's not present
at all, <literal>${x!'missing'}</literal> will print ``missing'',
you can't tell the difference. Also, if for example you want to
test if a Java method has returned <literal>null</literal>, just
write something like <literal><#if
foo.bar()??></literal>.</para>
<para>You may interested in the rationale behind this. From the
viewpoint of the presentation layer a <literal>null</literal> and
non-existent thing is almost always the same. The difference
between this two is usually just a technical detail, which is
rather the result of implementation details than of the
application logic. That you can't compare something to
<literal>null</literal> (unlike in Java); it doesn't make sense to
compare something with <literal>null</literal> in a template,
since the template language doesn't do identity comparison (like
the Java <literal>==</literal> operator when you compare two
objects) but the more common sense value comparison (like Java's
<literal>Object.equals(Object)</literal>; that doesn't work with
<literal>null</literal> either). And how could FreeMarker tell if
something concrete equals with something that is missing and thus
unknown? Or if two missing (unknown) things are equal? Of course
these questions can't be answered.</para>
<para>There is at least one problem with this
<literal>null</literal>-unaware approach. When you call a Java
method from a template, you may want to pass a
<literal>null</literal> value as argument (since the method was
designed to be used in Java language, where the concept of
<literal>null</literal> is known). In this case you can exploit a
bug of FreeMarker (that we will not fix until we provide a correct
solution for passing <literal>null</literal> values to a method):
if you specify a missing variable as the argument, then it will
not cause an error, but a <literal>null</literal> will be passed
to the method instead. Like <literal>foo.bar(nullArg)</literal>
will call the <literal>bar</literal> method with
<literal>null</literal> as argument, assuming that there is no
varaible exists with ``nullArg'' name.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How can I use the output of a directive (macro) in
expressions (as a parameter to another directive)?</para>
</question>
<answer>
<para>Capture the output into a variable with the
<literal>assign</literal> or <literal>local</literal> directive.
For example:</para>
<programlisting role="template"><#assign capturedOutput><@outputSomething /></#assign>
<@otherDirective someParam=capturedOutput /></programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why do I have ``?''-s in the output instead of character
<replaceable>X</replaceable>?</para>
</question>
<answer>
<para>This is because the character that you want to print can't
be represented with the <link
linkend="gloss.charset">charset</link> (encoding) used for the
output stream, so the Java platform (not FreeMarker) substitutes
the problematic character with question mark. In general you
should use the same charset for the output as for the template
(use the <literal>getEncoding()</literal> method of the template
object), or which is even safer, you should always use UTF-8
charset for the output. The charset used for the output stream is
not decided by FreeMarker, but by you, when you create the
<literal>Writer</literal> that you pass to the
<literal>process</literal> method of the template.</para>
<para>Example: Here I use UTF-8 charset in a servlet:</para>
<programlisting role="unspecified">...
resp.setContentType("text/html; charset=utf-8");
Writer out = resp.getWriter();
...
t.process(root, out);
...</programlisting>
<para>Note that the question marks (or other substitution
characters) may be produced outside FreeMarker, in which case the
above obviously will not help. For example a bad/missconfigured
database connection or JDBC driver may bring the text already with
substitution characters in it. HTML forms are another potential
source of encoding problems. It's a good idea to print the
numerical code of the characters of the string on various places,
to see where the problem occurs first.</para>
<para>You can read more about charsets and FreeMarker <link
linkend="pgui_misc_charset">here...</link></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How to retrieve values calculated in templates after
template execution done?</para>
</question>
<answer>
<para>First of all, be sure your application is designed well:
templates should display data, and almost never calculate data. If
you are still sure you want to do it, read on...</para>
<para>When you use <literal><#assign x = "foo"></literal>,
then you do not actually modify the data-model (since that is
read-only, see: <xref linkend="pgui_misc_multithreading" />), but
create the <literal>x</literal> variable in the runtime <link
linkend="gloss.environment">environment</link> of the processing
(see <xref linkend="pgui_misc_var" />). The problem is that this
runtime environment will be discarded when
<literal>Template.process</literal> returns, as it was created for
a single <literal>Template.process</literal> call:</para>
<programlisting role="unspecified">// internally an Environment will be created, and then discarded
myTemplate.process(root, out);</programlisting>
<para>To prevent this, you can do the below, which is equivalent
with the above, except that you have chance to return the
variables created in the template:</para>
<programlisting role="unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out);
env.process(); // process the template
TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
</answer>
</qandaentry>
<qandaentry xml:id="faq_implement_function_or_macro_in_java">
<question>
<para>How to implement a function or macro in Java Language
instead of in the template language?</para>
</question>
<answer>
<para>It's not possible (yet), but something very similar is
possible if you write a class that implements
<literal>freemarker.template.TemplateMethodModelEx</literal> or
<literal>freemarker.template.TemplateDirectiveModel</literal>
respectively, and then where you were write <literal><#function
my
<replaceable>...</replaceable>><replaceable>...</replaceable></#function></literal>
or <literal><#macro my
<replaceable>...</replaceable>><replaceable>...</replaceable></#macro></literal>
you write <literal><#assign my = "your.package.YourClass
"?</literal><link
linkend="ref_builtin_new"><literal>new</literal></link><literal>()></literal>
instead. Note that using the <literal>assign</literal> directive
for this works because functions (and methods) and macros are just
plain variables in FreeMarker. (For the same reason you could also
put <literal>TemplateMethodModelEx</literal> or
<literal>TemplateDirectiveModel</literal> instances into the
data-model before calling the template, or into the shared
variable map (see:
<literal>freemarker.template.Configuration.setSharedVariable(String,
TemplateModel)</literal>) when you initialize the
application.)</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why is FreeMarker logging suppressed for my
application?</para>
</question>
<answer>
<para>It is because FreeMarker does not find any logging system.
To fix this, you must make available one of the following logging
systems for your application: Avalon
(<literal>org.apache.log</literal>), Log4J
(<literal>org.apache.log4j</literal>), or use J2SE 1.4 or later
(that contains <literal>java.util.logging</literal>). That is, the
class-loader used with your application must find one of the
mentioned classes.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para><anchor xml:id="misc.faq.niceErrorPage" /> In my Servlet
based application, how do I show a nice error page instead of a
stack trace when error occurs during template processing?</para>
</question>
<answer>
<para>First of all, use <literal>RETHROW_HANDLER</literal> instead
of the default <literal>DEBUG_HANDLER</literal> (for more
information about template exception handlers <link
linkend="pgui_config_errorhandling">read this...</link>). Now
FreeMarker will not print anything to the output when an error
occurs, so the control is in your hands. After you have caught the
exception of
<literal>Template.process(<replaceable>...</replaceable>)</literal>
basically you can follow two strategies:</para>
<itemizedlist>
<listitem>
<para>Call <literal>httpResp.isCommitted()</literal>, and if
that returns <literal>false</literal>, then you call
<literal>httpResp.reset()</literal> and print a ``nice error
page'' for the visitor. If the return value was
<literal>true</literal>, then try to finish the page be
printing something that makes clear for the visitor that the
page generation was abruptly interrupted because of an error
on the Web server. You may have to print a lot of redundant
HTML end-tags and set colors and font size to ensure that the
error message will be actually readable in the browser window
(check the source code of the
<literal>HTML_DEBUG_HANDLER</literal> in
<literal>src\freemarker\template\TemplateException.java</literal>
to see an example).</para>
</listitem>
<listitem>
<para>Use full page buffering. This means that the
<literal>Writer</literal> doesn't send the output to the
client progressively, but buffers the whole page in the
memory. Since you provide the <literal>Writer</literal>
instance for the
<literal>Template.process(<replaceable>...</replaceable>)</literal>
method, this is your responsibility, FreeMarker has nothing to
do with it. For example, you may use a
<literal>StringWriter</literal>, and if
<literal>Template.process(<replaceable>...</replaceable>)</literal>
returns by throwing an exception, then ignore the content
accumulated by the <literal>StringWriter</literal>, and send
an error page instead, otherwise you print the content of
<literal>StringWriter</literal> to the output. With this
method you surely don't have to deal with partially sent
pages, but it can have negative performance implications
depending on the characteristic of the pages (for example, the
user will experience more response delay for a long page that
is generated slowly, also the server will consume more RAM).
Note that using a <literal>StringWriter</literal> is surely
not the most efficient solution, as it often reallocates its
buffer as the accumulated content grows.</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I'm using a visual HTML editor that mangles template tags.
Will you change the template language syntax to accommodate my
editor?</para>
</question>
<answer>
<para>We won't change the standard version, because a lot of
templates depend on it.</para>
<para>Our view is that the editors that break template code are
themselves broken. A good editor should ignore, not mangle, what
it doesn't understand.</para>
<para>You maybe interested in that starting from FreeMarker 2.3.4
you can use <literal>[</literal> and <literal>]</literal> instead
of <literal><</literal> and <literal>></literal>. For more
details <link linkend="dgui_misc_alternativesyntax">read
this...</link></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How fast is FreeMarker? Is it true that 2.x is slower than
1.x (FreeMarker classic)?</para>
</question>
<answer>
<para>First of all, don't forget that FreeMarker is only the view
rendering component in an <link linkend="gloss.MVC">MVC</link>
system. Furthermore MVC templates tend to be simple: many static
text with a few interpolations and loops and conditional block. So
it is not like PHP or Model 1 JSP; your application performance is
not affected that much by the execution time of templates.</para>
<para>FreeMarker is certainly fast enough that it will only very
rarely be a bottleneck in your application. Rather, other factors
such as the speed of the data-base operations or network bandwidth
will likely dominate. The impact of FreeMarker performance could
be noticeable only for really busy sites (say, over 30 hits per
second per server), where almost all database data is cached. If
you are finding FreeMarker slow, do make sure that the cache of
parsed templates works well
(<literal>Configuration.getTemplate</literal> be default uses
caching). Parsing a template file is a relatively costly step; in
most long-running server-side applications, you will want to parse
a template once and have it be used many times. (Note that
FreeMarker 2.1.4 and earlier versions have bugs that sometimes can
ruin caching.)</para>
<para>FreeMarker 2.1 is slower than 1.7.1. This surely depends on
your templates, but it could be slower by a factor of 2 or 3. But
again, it does not means that response time will be 2 or 3 times
slower; most FreeMarker user simply should not be able to perceive
the change in the final response time.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How can my Java classes ask a template for information about
its structure (e.g. a list of all the variables)?</para>
</question>
<answer>
<para>In FreeMarker 2.2, <literal>Template</literal> has an
undocumented method for examining the parsed template:
<literal>getRootTreeNode</literal>.</para>
<para>But listing all accessed variables is not possible, because
variable names can be dynamically generated from data. However,
there's a more important reason why FreeMarker doesn't support
this. The design of FreeMarker is based on the idea of a
separation between business objects and presentation objects. This
separation takes two forms:</para>
<orderedlist>
<listitem>
<para>The templates know what data to expect, but they don't
know how it's generated.</para>
</listitem>
<listitem>
<para>The business objects know what data to produce, but they
don't know how it's going to be displayed. Therefore, they
don't know anything about templates.</para>
</listitem>
</orderedlist>
<para>Since the business objects don't rely on the templates, if
you need to use them with some other presentation system, you
won't have to rewrite your application.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Will you ever provide backward compatibility?</para>
</question>
<answer>
<para>FreeMarker 2.0 was a complete rewrite of FreeMarker 1.x, by
a new author. The 1.x series continues as separated project:
FreeMarker Classic. Since 2.x follows different philosophy than
1.x, 2.0x releases were immature despite the high major version
number. This caused further radical changes between 2.01 and 2.1.
As of 2.1 things were much more matured, and 2.2 is almost
backward compatible with 2.1. We hope that this tendency
continues.</para>
<para>Currently, the rule is that releases with different second
version number (as 2.1.x and 2.2.x) are not (fully) compatible.
Releases where only the third version number differs (as 2.2.1 and
2.2.6) are compatible.</para>
<para>We always provide backward compatible bugfix releases for
the released versions. So basically, you don't
<emphasis>have</emphasis> to switch to a new, non-backward
compatible release in an already written product. It's a something
for something situation... FreeMarker recovers faster from design
mistakes than many other projects, but the price of this is that
major releases are not backward compatible. This is admittedly not
optimal, it would be better if there are fewer design mistakes...
but, well, it is the reality.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>If we distribute FreeMarker with our product, do we have to
release the source code for our product?</para>
</question>
<answer>
<para>No. As of 2.0, FreeMarker is released under a BSD-style
license. This means that source or binary distributions may be
made freely, and can be included in other products, whether
commercial or open source.</para>
<para>The only restrictions apply to the copyright of FreeMarker
itself, and the use of FreeMarker or its contributors as
endorsements of your own product. See the <link
linkend="app_license">LICENSE</link> for further details.</para>
<para>If you use FreeMarker, we hope you'll send us a link to some
information about your product, but that's optional as
well.</para>
</answer>
</qandaentry>
</qandaset>
</appendix>
<appendix xml:id="app_install">
<title>Installing FreeMarker</title>
<indexterm>
<primary>install</primary>
</indexterm>
<para>No real installation needed. Simply copy
<literal>lib/freemarker.jar</literal> to a location where your Java
application's class-loader will find it. For example, if you use
FreeMarker in a web application, you probably want to put
<literal>freemarker.jar</literal> into the
<literal>WEB-INF/lib</literal> directory of your web application.</para>
<para>No real installation needed. Simply copy
<literal>lib/freemarker.jar</literal> to a location where your Java
application's ClassLoader will find it. For example, if you use
FreeMarker in a web application, you probably want to put
<literal>freemarker.jar</literal> into the
<literal>WEB-INF/lib</literal> directory of your web application. (If
you want to use FreeMarker with JSP Model-2 style (which also means that
you can use custom JSP taglibs in the templates), some extra steps
needed. For more information please see <link
linkend="pgui_misc_servlet">the chapter about servlets</link>.)</para>
<para>However, some third party libraries have also be available for the
class-loader, if you want to enable certain
<emphasis>optional</emphasis> FreeMarker features:</para>
<itemizedlist>
<listitem>
<para>At least J2SE 1.4 is required for regular expression
built-ins.</para>
</listitem>
<listitem>
<para>At least J2SE 1.4 or a JAXP + DOM implementation + SAX
implementation is needed for the XML wrapping.</para>
</listitem>
<listitem>
<para>Jaxen (recommended, <link
xlink:href="http://jaxen.org/">download here</link>) or Apache Xalan
is needed for XML XPath support. Please use at least Jaxen
1.1-beta-8, not older versions! Apache Xalan classes are included in
Sun J2SE 1.4, 1.5 and 1.6 (and maybe later too), so no separate
Xalan jar is needed with those versions.</para>
</listitem>
<listitem>
<para>Obviously, <literal>javax.servlet</literal> classes are needed
for <literal>FreemarkerServlet</literal>. Servlet version 2.2 or
later is needed.</para>
</listitem>
<listitem>
<para>For the custom JSP taglib support, you will need JSP 1.2 API
classes. No JSP implementation needed, just the API. For more
information please see <link linkend="pgui_misc_servlet">the chapter
about servlets</link>.</para>
</listitem>
<listitem>
<para>Obviously, Jython classes are needed for the Jython
wrapper.</para>
</listitem>
<listitem>
<para>JDOM is needed for the deprecated freemarker.ext.jdom
package.</para>
</listitem>
</itemizedlist>
</appendix>
<appendix xml:id="app_build">
<title>Building FreeMarker</title>
<indexterm>
<primary>build</primary>
</indexterm>
<para>If you want to modify the source code and rebuild
<literal>freemarker.jar</literal>, you need <link
xlink:href="http://ant.apache.org/">Ant</link> 1.6.1 (or newer) and JDK
5 (or newer). If these are satisfied, just run Ant from the root
directory of the distribution, and it will create the new
<literal>freemarker.jar</literal>. Note that for the very first build
you must be on-line, because the build task will download a lot of
required dependencies (about 20 MB) into the <literal>lib</literal>
subdirectory of distribution root directory.</para>
<para>Maybe you should check the new jar file against our test suite.
This is done by running Ant with <literal>test</literal> target (go to
the root directory of the distribution, and issue "ant test"). If the
test fails, read the resulting <literal>.txt</literal> file in the
<literal>build/testcase</literal> directory for more details.</para>
<para>Note that building a full distribution, which includes the
FreeMarker Manual and the off-line Web site, is not possible purely from
the source code that is included with the distribution. You will have to
check out the "docgen" and "site" sub-projects from the SVN repository
of FreeMarker for that.</para>
</appendix>
<appendix xml:id="app_versions">
<title>Versions</title>
<section xml:id="versions_2_3_17">
<title>2.3.17</title>
<para>Date of release: 2011-05-17</para>
<para>It's urgent to update to this version because of a <link
linkend="v2317secfix">security fix</link>!</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para><literal>?seq_index_of</literal> and
<literal>?seq_last_index_of</literal> now works on collections
(<literal>freemarker.template.TemplateCollectionModel</literal>-s)
too, not only on sequences
(<literal>freemarker.template.TemplateSequenceModel</literal>-s).</para>
</listitem>
<listitem>
<para><literal>?long</literal> now works for date, date-time or
time values, and returns the milliseconds since the epoch (as
<literal>java.util.Date.getTime()</literal>).</para>
</listitem>
<listitem>
<para>To convert numbers (usually Java
<literal>long</literal>-s) to date or date-time and time values,
<literal>?number_to_date</literal>,
<literal>?number_to_time</literal>,
<literal>?number_to_datetime</literal> was added. <link
linkend="ref_builtin_numToDate">See more here...</link>
(Unfortunately, <literal>?date</literal> and like can't be
extended to support this due to backward compatibility
issues.)</para>
</listitem>
<listitem>
<para>New built-ins to format numbers with ISO 8601 "extended"
format regardless of the current date/time formatting settings,
and even regardless of the current time zone setting. For
example <literal>${myTimeStamp?iso_utc}</literal> will print
something like <literal>2010-05-16T23:05:45Z</literal>. <link
linkend="ref_builtin_date_iso">See more here...</link></para>
</listitem>
<listitem>
<para>New <link linkend="ref_specvar">special variable</link>,
<literal>now</literal>. This returns the current date-time.
Usage examples: "<literal>Page generated: ${.now}</literal>",
"<literal>Today is ${.now?date}</literal>", "<literal>The
current time is ${.now?time}</literal>".</para>
</listitem>
<listitem>
<para><literal>?sort</literal> and <literal>?sort_by</literal>
now supports sorting boolean values.</para>
</listitem>
<listitem>
<para>When using unsupported or unknown <link
linkend="ref_builtin_string_flags">string built-in flags</link>,
FreeMarker will now <link linkend="pgui_misc_logging">log</link>
warnings (maximum 25 times per class-loader, to prevent flooding
the log). It's certain that starting from FreeMarker 2.4 these
will count as errors.</para>
</listitem>
<listitem>
<para>Bug fixed <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=3047201&group_id=794">[3047201]</link>:
Using regular expressions (like with <literal>?match</literal>)
could cause lockup in multi-threaded environment, also memory
leakage when using dynamically generated regular
expressions.</para>
</listitem>
<listitem>
<para>Bug fixed: <literal>?seq_contains</literal>,
<literal>?seq_index_of</literal> and
<literal>?seq_last_index_of</literal> has failed with
non-<literal>java.util.List</literal>
<literal>java.util.Collection</literal>-s that are wrapped with
pure <literal>BeansWrapper</literal> (not the
<literal>DefaultObjectWrapper</literal>) as
<literal>TemplateSequenceModel</literal>. (See also:
<literal>getSupportsIndexedAccess()</literal> below)</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para xml:id="v2317secfix"><emphasis>Security fix</emphasis>:
Using carefully crafted template names (template paths) that
contain code point 0 (<literal>'\u0000'</literal>), it was
possible to load files from outside the template root directory
like if they were FreeMarker templates. The root of the problem
is that the underlying native C/C++ part (which belongs to the
Java platform or to the OS) interprets the 0 as the end of the
string, while Java (and hence FreeMarker and the Servlet
container) doesn't. Thus a path that looked safe for FreeMarker
become unsafe on the lower level. The problem is present with
all ways of loading templates by name
(<literal>Configuration.getTemplate(<replaceable>...</replaceable>)</literal>,
<literal><#include
<replaceable>...</replaceable>></literal>,
<literal><#import
<replaceable>...</replaceable>></literal>).</para>
<para>You are not effected if you don't allow users to upload
templates and also at least one of these stands:</para>
<itemizedlist>
<listitem>
<para>In your system users can't provide arbitrary strings
as template names (template paths). For example, if users
are only allowed to visit the URL-s that belong to the MVC
Controller (like they can't visit <literal>*.ftl</literal>)
then they can't suggest arbitrary template names.</para>
</listitem>
<listitem>
<para>The template names are part of the path in the Web
page URL, and your webserver or Servlet container disallows
URL-s that contain <literal>%00</literal>, or terminate the
URL at it before passing it to the servlets.</para>
</listitem>
<listitem>
<para>You are using <literal>FileTemplateLoader</literal>
and linking is not allowed in it (by default it isn't
allowed).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>FreeMarker now can log its messages directly using SLF4J
or Apache Commons Logging. However, it will not use these logger
libraries automatically, until 2.4; <link
linkend="pgui_misc_logging">see more here...</link> But it's
recommended to switch to SLF4J now.</para>
</listitem>
<listitem>
<para>New setting: <literal>"auto_flush"</literal>,
<literal>Configurable.setAutoFlush(boolean)</literal>. Sets
whether the output <literal>Writer</literal> is automatically
flushed at the end of <literal>Template.process(Object,
Writer)</literal> (and its overloads). The default is
<literal>true</literal>, which corresponds to the earlier
behavior. Using <literal>false</literal> is needed for example
when a Web page is composed from several boxes (like portlets,
GUI panels, etc.) that aren't inserted with
<literal>#include</literal> (or with similar directives) into a
master FreeMarker template, rather they are all processed with a
separate
<literal>Template.process(<replaceable>...</replaceable>)</literal>
call. In a such scenario the automatic flushes would commit the
HTTP response after each box, hence interfering with full-page
buffering, and also possibly decreasing performance with too
frequent and too early response buffer flushes.</para>
</listitem>
<listitem>
<para>Added new setting:
<literal>Configuration.setNewBuiltinClassResolver(TemplateClassResolver)</literal>,
or <literal>new_builtin_class_resolver</literal> property. This
allows you to specify how the <link
linkend="ref_builtin_new"><literal>new</literal> built-in</link>
(like in <literal>"com.example.SomeClass"?new()</literal>)
resolves classes and which classes are accessible at all. If you
are allowing not-so-much-trusted users to upload templates, you
should be definitely interestered; see the Java API docs of
<literal>freemarker.core.Configurable.setSetting</literal> and
<literal>freemareker.template.Configuration.setNewBuiltinClassResolver</literal>.
Otherwise it's still recommended to set this to
<literal>TemplateClassResolver.SAFER_RESOLVER</literal> (or
<literal>safer</literal> if you are using properties), although
that's not 100% backward compatible (see Java API docs) .</para>
</listitem>
<listitem>
<para>Added
<literal>freemarker.cache.NullCacheStorage</literal>: Setting
this as the cache storage in <literal>Configuration</literal>
disables caching.</para>
</listitem>
<listitem>
<para>Added <literal>getSupportsIndexedAccess()</literal> to
<literal>freemarker.ext.beans.CollectionModel</literal>, so one
can check if <literal>TemplateSequenceModel.get(int)</literal>
will work with a particular <literal>CollectionModel</literal>
instance or not.</para>
</listitem>
<listitem>
<para>Bug fixed <link
xlink:href="http://sourceforge.net/tracker/?func=detail&aid=2992265&group_id=794&atid=100794">[2992265]</link>:
JSP <literal>FreeMarkerPageContext.include</literal> behaved
incorrectly.</para>
</listitem>
<listitem>
<para>Bug fixed: When using FreeMarker's JSP support with JSP
tags that use
<literal>javax.servlet.jsp.PageContext.pushBody</literal> (like
some Stripes tags), <literal>"ArrayIndexOutOfBoundsException:
-1"</literal> occurred inside
<literal>freemarker.ext.jsp.FreeMarkerPageContext.popWriter</literal>.</para>
</listitem>
<listitem>
<para>Bug fixed <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=3033015&group_id=794">[3033015]</link>:
<literal>AllHttpScopesHashModel</literal> used
<literal>WrappingTemplateModel.getDefaultObjectWrapper()</literal>
for wrapping variables in the page scope, while used the
user-specified <literal>ObjectWrapper</literal> for all other
scopes (request, session, etc.). Now it uses the user-specified
wrapper in the page scope as well.</para>
</listitem>
<listitem>
<para>Bug fixed <link
xlink:href="https://sourceforge.net/tracker/?func=detail&aid=3128073&group_id=794&atid=100794">[3128073]</link>:
<literal>HashAdapther.containsKey(...)</literal> returned
<literal>true</literal> for a key that doesn't exist when
unwrapping the key has failed. As a side effect of the fix,
<literal>BeansWrapper.CAN_NOT_UNWRAP</literal> is now private;
earlier it was public by mistake.</para>
</listitem>
<listitem>
<para>Big fixed <link
xlink:href="http://sourceforge.net/tracker/?func=detail&aid=3151085&group_id=794&atid=100794">[3151085]</link>:
<literal>freemarker.jsp.TaglibFactory</literal> didn't locate
tld files properly. This fix gives better compliance with JSP
specification for resolving and loading tld files.</para>
</listitem>
<listitem>
<para>Bug fixed: Unwrapping <literal>null</literal> with a
<literal>BeansWrapper</literal> that had a custom null-model
didn't result in <literal>null</literal>. Now both unwrapping
<literal>null</literal> and the custom null-model gives
<literal>null</literal>.</para>
</listitem>
<listitem>
<para>Log messages doesn't contain line-breaks (CR or LF)
anymore and quote paths and other arbitrary text with Java
string literal syntax that also escapes <literal><</literal>
characters as <literal>\u003C</literal>. These address security
concerns related to poor quality log appenders and buggy log
readers. This change is mostly noticeable on template processing
error entries, which will now quote the exception message. Note
that how stack traces (the <literal>Throwable</literal> objects)
are logged is still up to the logging framework you are
using.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>The DTD-s and XSD-s that are included in
<literal>freemarker.jar</literal> under
<literal>freemarker/ext/jsp</literal> are now under Apache
Software License, Version 2. This is also clarified in the
<literal>LICENSE.txt</literal>. Earlier these files had no clear
license terms.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_16">
<title>2.3.16</title>
<para>Date of release: 2009-12-07</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Fixed a bug that caused incorrect unwrapping of sequences
to Java arrays (<link
xlink:href="https://sourceforge.net/tracker/?func=detail&aid=2105310&group_id=794&atid=100794">See
bug report</link>)</para>
</listitem>
<listitem>
<para>Fixed a bug that caused rounding of float and double
values (<link
xlink:href="https://sourceforge.net/tracker/?func=detail&aid=2503124&group_id=794&atid=100794">See
bug report</link>)</para>
</listitem>
<listitem>
<para>Created a new
<literal>freemarker.runtime.attempt</literal> category and
exceptions caught in <literal><#attempt></literal> blocks
are logged into it at a DEBUG severity.</para>
</listitem>
<listitem>
<para>Fixing the (ages old) problem of
<literal>RhinoWrapper</literal> not working with all versions of
Rhino because of binary incompatible change of Rhino's
<literal>Undefined.instance</literal>.</para>
</listitem>
<listitem>
<para>Fixed bug where <literal>TextUtil.XMLEncNQG</literal>
didn't escape <literal>]]></literal> as
<literal>]]&gt;</literal>.</para>
</listitem>
<listitem>
<para>Fixed bug where the root directory couldn't be used as the
template base directory, as
<literal>FileTemplateLoader</literal> believed that the template
is outside the base directory.</para>
</listitem>
<listitem>
<para>Macro names can no longer be changed through the
API.</para>
</listitem>
<listitem>
<para>FreemarkerServlet now cooperates with Session Fixation
Attack Protection in Spring Security, see <link
xlink:href="https://sourceforge.net/projects/freemarker/forums/forum/2345/topic/3475868">
forum discussion</link> for details.</para>
</listitem>
<listitem>
<para>Substantially improved performance of the
<literal><#return></literal> directive.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Fixed bug where
<literal><replaceable>anXMLNode</replaceable>.@@markup</literal>
and <literal>@@nested_markup</literal> didn't escape
<literal>]]></literal> as
<literal>]]&gt;</literal>.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_15">
<title>2.3.15</title>
<para>Date of release: 2008-12-16</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: Hash concatenation (like <literal>hash1 +
hash2</literal>) shuffled the order of keys/values even if both
hashes were ordered.</para>
</listitem>
<listitem>
<para>In web pages that are based on the
<literal>FreemarkerServlet</literal>, you can now use
<literal><@include_page path="..."/></literal> to use
servlet includes. See more <link
linkend="pgui_misc_servlet_include">here...</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>The <literal>BeansWrapper</literal> can automatically
detect that classes were reloaded by JavaRebel.</para>
</listitem>
<listitem>
<para>Fixed a bug that caused <literal>null</literal> to be
returned from
<literal>Environment.getCurrentEnvironment()</literal> while
processing autoincludes and autoimports. (<link
xlink:href="https://sourceforge.net/forum/message.php?msg_id=5531621">See
bug report</link>)</para>
</listitem>
<listitem>
<para>Fixed a bug that caused
<literal>getObject(Object)</literal> method on POJOs to not be
recognized as a general get method.</para>
</listitem>
<listitem>
<para>Substantially improved performance of the
<literal><#break></literal> directive.</para>
</listitem>
<listitem>
<para><literal>DeepUnwrap</literal> now unwraps custom null
model of the current object wrapper into a Java
<literal>null</literal>.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_14">
<title>2.3.14</title>
<para>Date of release: 2008-09-01</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New built-in: <literal>xhtml</literal>. See more <link
linkend="ref_builtin_xhtml">here...</link></para>
</listitem>
<listitem>
<para>New special variable: <literal>template_name</literal>.
See more <link linkend="ref_specvar">here...</link></para>
</listitem>
<listitem>
<para>Now you can use the values of parameters as the defaults
of other parameters, for example <literal><#macro section
title label=title></literal>. In earlier versions it worked
unreliably. There are no restriction regarding the order of
parameters, like <literal><#macro section label=title
title></literal> works too.</para>
</listitem>
<listitem>
<para>Added a new <link
linkend="ref_builtin_string_for_number">number format
specifier</link>, <literal>computer</literal>. This uses the
same formatting as
<literal><replaceable>exp</replaceable>?c</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>The constructor to
<literal>freemarker.ext.servlet.AllHttpScopesHashModel</literal>
is now public, allowing it to be reused in 3rd party web
frameworks.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.ext.beans.SimpleMapModel</literal> (unlike
either <literal>freemarker.ext.beans.MapModel</literal> or
<literal>freemarker.template.SimpleHash</literal>) didn't allow
lookup by <literal>java.lang.Character</literal> key when passed
a single-character string as a key.</para>
</listitem>
<listitem>
<para>Bugfix: permissive unwrapping in
<literal>freemarker.template.utility.DeepUnwrap</literal> class
was not recursively permissive with elements of sequences and
hashes.</para>
</listitem>
<listitem>
<para>Bugfix: <literal>freemarker.ext.beans.MapModel</literal>
returns <literal>BeansWrapper.wrap(null)</literal> instead of
<literal>null</literal> for <literal>null</literal> values
explicitly bound into the map.</para>
</listitem>
<listitem>
<para>Bugfix: Fixed a subtle bug with property getters of
classes implementing a type-parametrized interface.</para>
</listitem>
<listitem>
<para>Bug fixed: A further corner case of <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1939742&group_id=794&atid=100794">[1939742]</link>.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_13">
<title>2.3.13</title>
<para>Date of release: 2008-05-05</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New built-ins for rounding numbers:
<literal>round</literal>, <literal>floor</literal>,
<literal>ceiling</literal>. See more <link
linkend="ref_builtin_rounding">here...</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1898300&group_id=794&atid=350794">[1898300]</link>,
<link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1818742&group_id=794&atid=350794">[1818742]</link>,
<link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1780882&group_id=794&atid=350794">[1780882]</link>:
Reworked template caching mechanism for radically improved
concurrent performance, with help from Azul Systems engineers.
(Achieved 20x speedup with Struts2 webapps on a 128-CPU Azul
device compared to 2.3.12.) Also, template loading (including
parsing) errors are now cached, improving performance in
applications that often try to get missing templates.</para>
</listitem>
<listitem>
<para><link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1892546&group_id=794&atid=100794">[1892546]</link>
Allow for custom <literal>TemplateLoader</literal> in
<literal>FreemarkerServlet</literal>.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1725107&group_id=794&atid=100794">[1725107]</link>
Using the FreeMarker JSP taglib support with Servlet 2.4 may
generates XML validation warnings.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1939742&group_id=794&atid=100794">[1939742]</link>
<literal>ConcurrentModificationException</literal> on accessing
nonexistent <literal>SimpleHash</literal> entries in a
loop</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1902012&group_id=794&atid=100794">[1902012]</link>
<literal>IteratorModel</literal> eats exception causes</para>
</listitem>
<listitem>
<para>Bug fixed: <literal><#assign
x></#assign></literal> (empty nested content) has
caused <literal>NullPointerException</literal></para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1926150&group_id=794&atid=100794">[1926150]</link>
<literal>CachedTemplate</literal> should be serializable</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_12">
<title>2.3.12</title>
<para>Date of release: 2008-02-03</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1857161&group_id=794&atid=100794">[1857161]</link>
JSP <literal>SimpleTag</literal> support was broken in
2.3.11.</para>
</listitem>
<listitem>
<para>In the templates, now you can conveniently call Java
methods that use the Java 5 varargs feature (variable-length
argument lists). Also the overloaded-method chooser logic now
considers vararg methods more intelligently.</para>
</listitem>
<listitem>
<para>Enum constants are now identified by their
<literal>name()</literal> instead of by their
<literal>toString()</literal> (because the latter can be
overridden in subclasses). This doesn't affect the way enum
constants are printed; of course that still uses
<literal>toString()</literal>.</para>
</listitem>
<listitem>
<para>Messages in parser exceptions now display the name of the
template.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_11">
<title>2.3.11</title>
<para>Date of release: 2007-12-04</para>
<para>This release contains several performance and usability
improvements.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1687248&group_id=794&atid=100794">[1687248]</link>
<emphasis role="bold">Warning! This bugfix may breaks some
templates!</emphasis> Fixed the bugs of the <link
linkend="ref_builtin_c"><literal>c</literal> built-in</link>
(<literal>?c</literal>) that sometimes caused whole numbers to
be formatted with ``.0'' at the end (like: 1.0), and caused
numbers sometimes formatted to exponential form (like 4E-20).
From now whole numbers will never use decimal dot (not even if
the wrapped number is a <literal>double</literal>; remember, the
template language knows only a single numerical type), and
exponential form will never be used either. Also, the maximum
number of digits after the decimal dot was limited to 16, so
numbers smaller than 1E-16 will be shown as 0.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>FreeMarker now has much better JSP 2.0 and JSP 2.1
compliance. Most notably, the JSP 2.0
<literal>SimpleTag</literal> interface is now supported.
Additionally, even when run in an environment that doesn't have
its own JSP implementation, the FreeMarker JSP runtime will make
available its own implementation of
<literal>JspFactory</literal> and
<literal>JspEngineInfo</literal> to tags when JSP 2.0 API JAR is
available in classpath, as well as an implementation of
<literal>JspApplicationContext</literal> when JSP 2.1 API JAR is
available in classpath.</para>
</listitem>
<listitem>
<para>A new model interface,
<literal>TemplateDirectiveModel</literal> provides an easier
paradigm for implementing user-defined directives than
<literal>TemplateTransformModel</literal> did previously.
<literal>TemplateTransformModel</literal> will be
deprecated.</para>
</listitem>
<listitem>
<para>FreeMarker now finds the Xalan-based XPath support
included in Sun JRE/JDK 5 and 6, so no separate Xalan jar is
required for the XPath support to work. (However, we recommend
Jaxen over Xalan, as the FreeMarker XPath support is more
complete with that. Of course for that the Jaxen jar is still
needed.)</para>
</listitem>
<listitem>
<para>Wrapping performance of <literal>BeansWrapper</literal>
has been significantly improved by eliminating repetitive
execution of various class tests.</para>
<para><emphasis role="bold">Note for
<literal>BeansWrapper</literal> customizers:</emphasis>
subclasses of <literal>BeansWrapper</literal> that previously
overrode <literal>getInstance(Object, ModelFactory)</literal>
method should now instead override
<literal>getModelFactory(Class)</literal> to take advantage of
this improvement. Overriding the old method still works, but it
will not take advantage of the performance improvement.</para>
</listitem>
<listitem>
<para>Memory footprint of a wrapper created by
<literal>BeansWrapper</literal> has been reduced (by a size of
one default-sized <literal>HashMap</literal>) until methods or
indexed properties are accessed on it (simple properties can be
accessed without increasing memory footprint).</para>
</listitem>
<listitem>
<para>Rhino objects can be used in templates as scalars,
numbers, and booleans, following the JavaScript conversion
semantics for these types.</para>
</listitem>
<listitem>
<para><literal>.data_model</literal> is now a
<literal>TemplatHashModelEx</literal> when possible. This means
that the list of the data-model variable names usually can be
get with <literal>.data_model?keys</literal>.</para>
</listitem>
<listitem>
<para><literal>FileTemplateLoader</literal> can now optionally
allow following symlinks that point out of the base directory.
It is disabled by default for backward compatibility.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1670887&group_id=794&atid=100794">[1670887]</link>
<literal>TaglibFactory</literal> taglib matching did not follow
JSP 1.2 FCS.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1754320&group_id=794&atid=100794">[1754320]</link>
Bug in <literal>setXPathSupportClass</literal> prevented
plugging in a user-supplied <literal>XPathSupport</literal>
implementation.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1803298&group_id=794&atid=100794">[1803298]</link>
Parser error while parsing macro with loop variables</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1824122&group_id=794&atid=100794">[1824122]</link>
Loading templates from JAR files could lead to leaking of file
handles (due to a bug in the Java API implementation of
Sun).</para>
</listitem>
<listitem>
<para>Bug fixed: Cached template is now removed from the cache
if the re-loading of the modified template file fails, so no
staled template is served.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Documentation changes</title>
<itemizedlist>
<listitem>
<para>Substantial reworkings in the Template Authors's Guide
(which was previously called Designer's Guide), especially in
the Getting Started section.</para>
</listitem>
<listitem>
<para><literal>#{...}</literal> is documented as deprected
construct from now.</para>
</listitem>
<listitem>
<para>The "transform" term is now removed from the
documentation. Instead the more general "user-defined directive"
term is used, which encompasses macros,
<literal>TemplateTransformModel</literal>-s and the new
<literal>TemplateDirectiveModel</literal>-s, which are just
different ways of implementing user-defined directives.</para>
</listitem>
<listitem>
<para>Some more minor improvements in the Manual.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_10">
<title>2.3.10</title>
<para>Date of release: 2007-04-20</para>
<para>This release contains several important bugfixes.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>[1589245] <literal>MultiTemplateLoader</literal> clears
its internal cached data (used for optimizing subsequent lookups
of the same template) when
<literal>Configuration.clearTemplateCache()</literal> is
invoked.</para>
</listitem>
<listitem>
<para>[1619257] A bug that caused an exception when
<literal>strict_bean_model</literal> was used in a FreeMarker
configuration <literal>Properties</literal> object or in the
<literal><#setting .../></literal> directive has been
fixed.</para>
</listitem>
<listitem>
<para>[1685176] A bug that caused
<literal>StackOverflowError</literal> in certain interactions of
garbage collector with MRU cache under Sun's Java 6 JVM has been
fixed.</para>
</listitem>
<listitem>
<para>[1686955] When <literal>ResourceBundleModel</literal>
constructs <literal>MessageFormat</literal> objects, it passes
them its own locale. <link linkend="beanswrapper_method">More
info...</link></para>
</listitem>
<listitem>
<para>[1691432] A bug that caused
<literal>BeansWrapper.EXPOSE_SAFE</literal> to be no safer than
<literal>BeansWrapper.EXPOSE_ALL</literal> has been
fixed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>[1628550] You can now use
<literal>dateExp?string.full</literal> for formatting dates
using Java built-in format
<literal>java.util.Date.FULL</literal> <link
linkend="ref_builtin_string_for_date">More info...</link></para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_9">
<title>2.3.9</title>
<para>Date of release: 2007-01-23</para>
<para>This release contains support for accessing JDK 1.5 enums and
public fields of classes from the templates through the
BeansWrapper.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para><literal>BeansWrapper</literal> can now expose public
fields of objects to the template if you call the
<literal>setExposeFields(true)</literal> on it. <link
linkend="beanswrapper_hash">More info...</link></para>
</listitem>
<listitem>
<para><literal>BeansWrapper</literal> can now pass any sequence
model to Java methods expecting a
<literal>java.util.Collection</literal> or a native Java array
(including primitive arrays). <link
linkend="beanswrapper_hash">More info...</link></para>
</listitem>
<listitem>
<para><literal>BeansWrapper</literal> can now pass any sequence
and collection model to Java methods expecting a
<literal>java.lang.Iterable</literal>. <link
linkend="beanswrapper_hash">More info...</link></para>
</listitem>
<listitem>
<para><literal>BeansWrapper</literal> can now unwrap numeric
models into correct target types when passing to Java methods
expecting a primitive or boxed number. Use of various <link
linkend="ref_builtins_expert">expert built-ins</link> to
manually coerce the types becomes mostly unnecessary.</para>
</listitem>
<listitem>
<para>Fixed a bug where <literal>BeansWrapper</literal> would
pass a <literal>java.util.Collection</literal> to a method
expecting a <literal>java.util.Set</literal> in certain rare
cases. <link linkend="beanswrapper_hash">More
info...</link></para>
</listitem>
<listitem>
<para>Support for JDK 1.5 enums in
<literal>BeansWrapper</literal> and
<literal>DefaultObjectWrapper</literal>. By calling the
<literal>getEnumModels()</literal> method, you can retrieve a
hash model that is keyed by class names and allows access to
enumerated values. I.e. if you bind this hash model under name
<literal>enums</literal> in the data-model, you can write
expressions like
<literal>enums["java.math.RoundingMode"].UP</literal> in the
template. The enum values can be used as scalars and support
equality and inequality comparisons. <link
linkend="jdk_15_enums">More info...</link></para>
</listitem>
<listitem>
<para><literal>freemarker.ext.rhino.RhinoWrapper</literal> now
correctly translates Rhino <literal>Undefined</literal>
instance, <literal>UniqueTag.NOT_FOUND</literal>, and
<literal>UniqueTag.NULL</literal> to FreeMarker undefined
value.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_8">
<title>2.3.8</title>
<para>Date of release: 2006-07-09</para>
<para>This release substantially improves the JSP 2.0 compatibility.
(For those who have seen the same points in 2.3.7: Sorry, the version
history was incorrect... those JSP 2.0 related changes were not in the
release yet.)</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>JSP support improvement: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1326058&group_id=794">[1326058]</link>
Added support for <literal>DynamicAttributes</literal> (new in
JSP 2.0)</para>
</listitem>
<listitem>
<para>JSP support improvement: Added support for
<literal>pushBody()</literal>/<literal>popBody()</literal> in
<literal>FreemarkerPageContext</literal></para>
</listitem>
<listitem>
<para>JSP support improvement: Added support for
<literal>getVariableResolver()</literal> (new in JSP
2.0).</para>
</listitem>
<listitem>
<para>JSP support improvement: Added support for
<literal>include(String, boolean)</literal> (new in JSP
2.0).</para>
</listitem>
<listitem>
<para>JSP support improvement: Added support for
<literal>getExpressionEvaluator()</literal> (new in JSP 2.0).
However, it will need Apache commons-el in the class path, or
else this method will not work (it's optional). Note that EL
support is not needed in principle, since FreeMarker has it's
own expression language. But some custom JSP 2 tags may still
want to use this method, after all it's in the JSP 2 API.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_7">
<title>2.3.7</title>
<para>Date of release: 2006-06-23</para>
<para>This release, compared to 2.3.7 RC1, contains new operators for
handling null/missing variables, , the <literal>substring</literal>
built-in, and some more bugfixes. Note that 2.3.7 RC1 has a long
change log, so you may want to <link linkend="versions_2_3_7rc1">read
that</link> too.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>The <literal>seq_contains</literal> built-in now handles
<literal>TemplateCollectionModel</literal>-s as well.</para>
</listitem>
<listitem>
<para>Bug fixed: In 2.3.7 RC1
<literal>FreemarkerServlet</literal> has always died with
<literal>NullPointerException</literal> during
initialization.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>3 new operators were added for terser missing variable
handling. These operators make the <literal>default</literal>,
<literal>exists</literal> and <literal>if_exists</literal>
built-ins deprecated. (The parser doesn't issue any warning
messages when you use deprecated built-ins, and they are still
working.):</para>
<itemizedlist>
<listitem>
<para><literal><replaceable>exp1</replaceable>!<replaceable>exp2</replaceable></literal>
is near equivalent with
<literal><replaceable>exp1</replaceable>?default(<replaceable>exp2</replaceable>)</literal>,
also
<literal>(<replaceable>exp1</replaceable>)!<replaceable>exp2</replaceable></literal>
is near equivalent with
<literal>(<replaceable>exp1</replaceable>)?default(<replaceable>exp2</replaceable>)</literal>.
The only difference is that this new operator doesn't
evaluate the
<literal><replaceable>exp2</replaceable></literal> when the
default value is not needed.</para>
</listitem>
<listitem>
<para><literal><replaceable>exp1</replaceable>!</literal> is
similar to
<literal><replaceable>exp1</replaceable>?if_exists</literal>,
also <literal>(<replaceable>exp1</replaceable>)!</literal>
is similar to
<literal>(<replaceable>exp1</replaceable>)?if_exists</literal>.
The difference is that with this new operator the default
value is an empty string and an empty list and empty hash at
the same time (multi-type variable), while with
<literal>if_exists</literal> the default value was an empty
string and an empty list and empty hash and boolean
<literal>false</literal> and a transform that does nothing
and ignores all parameters at the same time.</para>
</listitem>
<listitem>
<para><literal><replaceable>exp1</replaceable>??</literal>
is equivalent with
<literal><replaceable>exp1</replaceable>?exists</literal>,
also <literal>(<replaceable>exp1</replaceable>)??</literal>
is equivalent with with
<literal>(<replaceable>exp1</replaceable>)?exists</literal>.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>New built-in:
<literal><replaceable>exp</replaceable>?substring(<replaceable>from</replaceable>,
<replaceable>toExclusive</replaceable>)</literal>, also callable
as
<literal><replaceable>exp</replaceable>?substring(<replaceable>from</replaceable>)</literal>.
Getting substrings was possible for a long time like
<literal>myString[<replaceable>from</replaceable>..<replaceable>toInclusive</replaceable>]</literal>
and
<literal>myString[<replaceable>from</replaceable>..]</literal>.
This syntax is now deprecated for getting substrings (but it's
still working), and instead you should use
<literal>myString?substring(<replaceable>from</replaceable>,
<replaceable>toExclusive</replaceable>)</literal> and
<literal>myString?substring(<replaceable>from</replaceable>)</literal>.
Sequence (list) slices still has to be get with the old syntax,
since <literal>substring</literal> only applies to strings.
Please note that the ``to'' parameter is 1 greater with this new
builtin, as it is an exclusive index. Further difference is that
the <literal>substring</literal> built-in requires that the
``from'' index is less than or equal to the ``to'' index. So 0
length substrings are possible now, but not reversed
substrings.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1487694&group_id=794">[1487694]</link>
malfunction when the <literal>recover</literal> directive has no
nested content</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_7rc1">
<title>2.3.7 RC1</title>
<para>Date of release: 2006-04-27</para>
<para>This release contains many bugfixes and some
<literal>FreemarkerServlet</literal> related improvements. It's a
Release Candidate, which means that it shouldn't be used in production
environment yet. We recommend this release for development, however.
Please test it.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para><literal>FreemarkerServlet</literal> improvement:
<literal>AllHttpScopesHashModel</literal> is now public, so you
can add unlisted variables to the data-model.</para>
</listitem>
<listitem>
<para><literal>FreemarkerServlet</literal> improvement: When it
throws a <literal>ServletException</literal>, the J2SE 1.4 cause
exception is now set under J2SE 1.4.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1469275&group_id=794">[1469275]</link>
<literal>NullPointerException</literal> when using
<literal>BeansWrapper</literal> with reloaded classes</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1449467&group_id=794">[1449467]</link>
<literal>HttpSessionHashModel</literal> is not
<literal>Serializable</literal></para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1435113&group_id=794">[1435113]</link>
Error in <literal>BeanWrapper</literal> with indexed
properties</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1411705&group_id=794">[1411705]</link>
Acquisition bug in <literal>TemplateCache</literal></para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1459699&group_id=794&atid=100794">[1459699]</link>
Tag syntax can't set with
<literal>Configuration.setSetting(String,
String)</literal></para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1473403&group_id=794">[1473403]</link>
<literal>ReturnInstruction.Return</literal> should be
public</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1463664&group_id=794">[1463664]</link>kup
<literal>[/#noparse]</literal> is printed out</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_6">
<title>2.3.6</title>
<para>Date of release: 2006-03-15</para>
<para>Quick release that fixes a serious bug of 2.3.5, days after its
release. So for the recently added new features please <link
linkend="versions_2_3_5">see the section of 2.3.5.</link></para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: In FreeMarker 2.3.5 only, when you read a bean
property for the second time, FreeMarker will say that it's
missing (null).</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_5">
<title>2.3.5</title>
<para>Date of release: 2006-03-11</para>
<para><emphasis>This release was withdrawn because of a serious bug in
it. Please don't use it! Of course, all new features of it are
included in FreeMarker 2.3.6.</emphasis></para>
<para>A few new features and several bugfixes.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1435847&group_id=794">[1435847]</link>
Alternative syntax doesn't work for comments</para>
</listitem>
<listitem>
<para>Bug fixed: With the new square bracket syntax, the tag
could be closed with <literal>></literal>. Now it can be
closed with <literal>]</literal> only.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1324020&group_id=794">[1324020]</link>
<literal>ParseException</literal> with the
<literal>ftl</literal> directive if it wasn't in its own
line</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1404033&group_id=794">[1404033]</link>
<literal>eval</literal> built-in fails with hash
concatenation</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>A new <literal>Configuration</literal> level setting,
<literal>tagSyntax</literal> was added. This determines the
syntax of the templates (angle bracket syntax VS <link
linkend="dgui_misc_alternativesyntax">square bracket
syntax</link>) that has no <literal>ftl</literal> directive in
it. So now you can choose to use the new square bracket syntax
by default. However, the recommended is to use auto-detection
(<literal>yourConfig.setTagSyntax(Configuration.AUTO_DETECT_TAG_SYNTAX)</literal>),
because that will be the default starting from 2.4.
Auto-detection chooses syntax based on the syntax of the first
FreeMarker tag of the template (could be any FreeMarker tag, not
just <literal>ftl</literal>). Note that as with the previous
version, if a the template uses <literal>ftl</literal>
directive, then the syntax of the <literal>ftl</literal>
directive determines the syntax of the template, and the
<literal>tagSyntax</literal> setting is ignored.</para>
</listitem>
<listitem>
<para>Now <literal>BeansWrapper</literal>,
<literal>DefaultObjectWrapper</literal> and
<literal>SimpleObjectWrapper</literal> support lookup with 1
character long strings in <literal>Map</literal>-s (like
<literal>myHash["a"]</literal>) that use
<literal>Character</literal> keys. Simply, as a special case,
when a hash lookup fails on a string that is 1 character long,
it checks for the <literal>Character</literal> key in the
underlying map. (Bug tracker entry <link
xlink:href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1299045&group_id=794">[1299045]</link>
FreeMarker doesn't support map lookup with Character
keys.)</para>
</listitem>
<listitem>
<para>A new property, <literal>strict</literal> was added to
<literal>BeansWrapper</literal>,
<literal>DefaultObjectWrapper</literal> and
<literal>SimpleObjectWrapper</literal>. If this property is
<literal>true</literal> then an attempt to read a bean propertly
in the template (like <literal>myBean.aProperty</literal>) that
doesn't exist in the bean class (as opposed to just holding
<literal>null</literal> value) will cause
<literal>InvalidPropertyException</literal>, which can't be
suppressed in the template (not even with
<literal>myBean.noSuchProperty?default('something')</literal>).
This way <literal>?default('something')</literal> and
<literal>?exists</literal> and similar built-ins can be used to
handle existing properties whose value is
<literal>null</literal>, without the risk of hiding typos in the
property names. Typos will always cause error. But mind you, it
goes against the basic approach of FreeMarker, so use this
feature only if you really know what are you doing.</para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1426227&group_id=794&atid=100794">[1426227]</link>
<literal>NullPointerException</literal> in
<literal>printStackTrace(...)</literal></para>
</listitem>
<listitem>
<para>Bug fixed: <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1386193&group_id=794&atid=100794">[1386193]</link>
Division by zero in <literal>ArithmeticEngine</literal></para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_4">
<title>2.3.4</title>
<para>Date of release: 2005-10-10</para>
<para>Some new features and bugfixes.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Now you can use <literal>[</literal> and
<literal>]</literal> instead of <literal><</literal> and
<literal>></literal> for the FreeMarker tags. For example you
can write <literal>[#if
loggedIn]<replaceable>...</replaceable>[/#if]</literal> and
<literal>[@myMacro /]</literal>. <link
linkend="dgui_misc_alternativesyntax">More info...</link></para>
</listitem>
<listitem>
<para>Bugfix: the <literal>has_content</literal> built-in
returned <literal>false</literal> for number, date and boolean
values (if the value was not a multi-type value that is also a
sequence or collection or hash or string). Now it always returns
<literal>true</literal> for a number, date or boolean values
(except if the value is also a sequence or collection or hash or
string, because then it will be examined only like that).</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: the parameterless constructor of the
<literal>ClassTemplateLoader</literal> didn't worked.</para>
</listitem>
<listitem>
<para>Bugfix: The Jython wrapper didn't wrapped
<literal>java.util.Date</literal> objects well. Now it wraps
them with <literal>BeanWrapper</literal> to
<literal>TemplateDateModel</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: the <literal>include</literal> directive was
blamed when the included file had syntax error.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Minor Manual fixes.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_3">
<title>2.3.3</title>
<para>Date of release: 2005-06-23</para>
<para>Some new features and lot of bugfixes.</para>
<para>Attention:</para>
<itemizedlist>
<listitem>
<para>If you are using the Log4J logging, from now at least Log4J
1.2 is required. This is because of incompatible changes in the
Log4J API.</para>
</listitem>
<listitem>
<para>If you build FreeMarker yourself: from now at least JavaCC
3.2 (instead of JavaCC 2.1) and at least Ant 1.6.1 (instead of Ant
1.5.x) is required. This doesn't affect users who use the
<literal>freemarker.jar</literal> comes with the
distribution.</para>
</listitem>
</itemizedlist>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New built-in for formatting numbers for ``computer
audience'' as opposed to human audience: <link
linkend="ref_builtin_c"><literal>c</literal></link>. It should
be used for numbers that must use Java language formatting
regardless of the number format and locale settings, like for a
database record ID used as the part of an URL or as invisible
field value in a HTML form, or for printing CSS/JavaScript
numerical literals.</para>
</listitem>
<listitem>
<para>New built-in for the columnar/tabular displaying of
sequences: <link
linkend="ref_builtin_chunk"><literal>chunk</literal></link>.</para>
</listitem>
<listitem>
<para>The <link
linkend="dgui_template_exp_seqenceop_slice">sequence
slice</link> and substring operators now allow the omitting of
the last index, in which case it defaults to the index of the
last sequence item or character. Example:
<literal>products[2..]</literal>. (Also, <link
linkend="dgui_template_exp_direct_seuqence">numerical range
literals</link> now allow the omitting of the final number, in
which case it defaults to infinity. Example:
<literal>5..</literal>.)</para>
</listitem>
<listitem>
<para>Bugfix: <literal>?replace</literal> has worked forever if
the string to replace was <literal>""</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>New template loader:
<literal>freemarker.cache.StringTemplateLoader</literal>. It
uses a <literal>Map</literal> with <literal>Strings</literal> as
its source of templates. See more in the JavaDoc.</para>
</listitem>
<listitem>
<para>Experimental Rhino support: FreeMarker now comes with an
experimental object wrapper for Rhino (Java ECMAScript
implementation):
<literal>freemarker.ext.rhino.RhinoWrapper</literal></para>
</listitem>
<listitem>
<para>Some new utility methods for
<literal>Simple<replaceable>Xxx</replaceable></literal> classes:
<literal>SimpleHash.toMap()</literal>,
<literal>SimpleSequence.toList()</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: FTL literals and any other
<literal>SimpleSequnce</literal>-s, and
<literal>SimpleHash</literal>-es now can be used as parameters
to the FreeMarker-unaware Java methods that are exposed by
<literal>DefaultWrapper</literal> or
<literal>BeansWrapper</literal>. That is, the method parameters
are automatically converted from
<literal>Template<replaceable>Type</replaceable>Model</literal>-s
to <literal>java.util.Map</literal> and
<literal>java.util.List</literal> respectively.</para>
</listitem>
<listitem>
<para>Bugfix: The JSP support now works in JSP 2 compliant
containers as well. No, it doesn't support the new features of
JSP 2 yet, it's just that the JSP 1.2 taglib support has not
worked in JSP 2 containers.</para>
</listitem>
<listitem>
<para>Bugfix: The
<literal>Configuration.setOutputEncoding</literal> and
<literal>setURLEscapingCharset</literal> methods died with
<literal>NullPointerException</literal> when you tried to set
the setting value to <literal>null</literal>, which is legal for
these settings.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.template.utility.StringUtil.replace(...)</literal>
has worked forever if the string to replace was
<literal>""</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: The Log4J logging was updated to be compatible
with the upcoming Log4J 1.3. Note that now FreeMarker will need
at least Log4J 1.2.</para>
</listitem>
<listitem>
<para>Bugfix: FreeMarker didn't built from the source code on
J2SE 1.5, because of the introduction of the
<literal>enum</literal> keyword.</para>
</listitem>
<listitem>
<para>Bugfix: The return value of
<literal>SimpleSequence.synchronizedWrapper()</literal> was not
properly synchronized. Same with
<literal>SimpleHash.synchronizedWrapper()</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: Problem with <literal>BeansWrapper</literal> and
overridden bean methods/properties. (Details: bug-tracker entry
<link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1217661&group_id=794&atid=100794">#1217661</link>
and <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1166533&group_id=794&atid=100794">#1166533</link>)</para>
</listitem>
<listitem>
<para>Bugfix: Can't access JSP taglibs if
<literal>Request</literal> attribute is defined in the
data-model (Details: bug-tracker entry <link
xlink:href="http://sourceforge.net/tracker/index.php?func=detail&aid=1202918&group_id=794&atid=100794">#1202918</link>).</para>
</listitem>
<listitem>
<para>Bugfix: Various minor parser glitches were fixed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Manual improvements, especially in the FAQ.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_2">
<title>2.3.2</title>
<para>Date of release: 2005-01-22</para>
<para>Bugfix release.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: If you use JSP taglibs in FreeMarker templates,
FreeMarker possibly tried to get DTD-s from the Sun Web site
because of a bug introduced with FreeMarker 2.3.1. This was a
serious problem since if your server is offline or the Sun Web
site becomes temporarily inaccessible the templates that are
using JSP taglibs will possibly die with error.</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>DefaultObjectWrapper</literal> has
ignored the value of the <literal>nullModel</literal> property.
(Note that it's discouraged to use a ``null model''.)</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_3_1">
<title>2.3.1</title>
<para>Date of release: 2005-01-04</para>
<para>Maintenance (with some important new features) and bugfix
release.</para>
<section>
<title>Possible backward compatibility issue</title>
<para>There is a bugfix that may affect the behavior of you Web
application if you use JSP tags in FreeMarker templates:
FreeMarker's implementation of
<literal>javax.servlet.jsp.PageContext.getSession()</literal> was
incorrect. The <literal>getSession()</literal> method is a
convenience method by which the custom tag can get the current
<literal>HttpSession</literal> object (possibly
<literal>null</literal> if there is no session). Till now, if the
session didn't existed then it has created it automatically, so it
never returned <literal>null</literal>. This was a bug, so starting
from 2.3.1 it never creates the session, just returns
<literal>null</literal> if it doesn't exist. The old incorrect
behavior could cause page rendering to fail if the method is called
after the page is partially flushed. But beware, the old behavior
has possibly hidden some bugs of the Web application, where it
forgot to create the session, so with the new correct behavior you
may face malfunction caused by previously cloaked bugs of the Web
application. (It's the task of the MVC Controller to create the
session, except if the JSP tag that needs a session is written so it
creates it automatically, but then it doesn't expects that
<literal>getSession()</literal> will do it.)</para>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New built-in: <link
linkend="ref_builtin_url"><literal>url</literal></link>. This
built-in can be used for URL escaping. Note, however, that to
use this built-in conveniently, the software that encapsulates
FreeMarker has to be 2.3.1 aware (programmers will find more
info bellow...).</para>
</listitem>
<listitem>
<para>New <link linkend="ref_specvar">special variables</link>:
<literal>output_encoding</literal> and
<literal>url_escaping_charset</literal>. Note, however, that to
use these, the software that encapsulates FreeMarker has to be
2.3.1 aware (programmers will find more info bellow...).</para>
</listitem>
<listitem>
<para>New built-ins for sequences: <link
linkend="ref_builtin_seq_contains"><literal>seq_contains</literal></link>,
<link
linkend="ref_builtin_seq_index_of"><literal>seq_index_of</literal></link>,
<link
linkend="ref_builtin_seq_last_index_of"><literal>seq_last_index_of</literal></link>.</para>
</listitem>
<listitem>
<para>New built-ins for strings: <link
linkend="ref_builtin_left_pad"><literal>left_pad</literal></link>,
<link
linkend="ref_builtin_right_pad"><literal>right_pad</literal></link>
and <link
linkend="ref_builtin_contains"><literal>contains</literal></link>.</para>
</listitem>
<listitem>
<para>New directive: <link
linkend="ref.directive.attempt"><literal>attempt</literal>/<literal>recover</literal></link></para>
</listitem>
<listitem>
<para>The <link
linkend="ref_builtin_js_string"><literal>js_string</literal>
built-in</link> now escapes <literal>></literal> as
<literal>\></literal> (to avoid
<literal></script></literal>).</para>
</listitem>
<listitem>
<para>The <literal>sort</literal> and <literal>sort_by</literal>
built-ins now can sort by date values. Also,
<literal>sort_by</literal> built-in now can sort by the
subvarible of a subvariable of a subvariable... etc. for any
level depth. (<link
linkend="ref_builtin_sort_by">Details...</link>)</para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</literal>
now prints more HTML-context-proof messages.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>New setting: <literal>output_encoding</literal>. This
setting is used for informing FreeMarker about the charset that
the enclosing software (as a Web application framework) uses for
the output of FreeMarker. It's undefined by default, and
although it is not strictly required to set it, the enclosing
software should do so. This setting must be set if templates
want to use the new <literal>output_encoding</literal> special
variable, and possibly if they want to use the new
<literal>url</literal> built-in. Note that the FreeMarker API
allows you to set settings for each template execution
individually (look at
<literal>Template.createProcessingEnvironment(...)</literal>).</para>
</listitem>
<listitem>
<para>New setting: <literal>url_escaping_charset</literal>. This
is the charset used for calculating the escaped parts
(<literal>%<replaceable>XX</replaceable></literal>) when you do
URL escaping with the new <literal>url</literal> built-in. If it
is not set, then the <literal>url</literal> built-in uses the
value of the <literal>output_encoding</literal> setting, and if
that's not set either, then the parameterless version of
<literal>url</literal> built-in (<literal>${foo?url}</literal>)
can't be used.</para>
</listitem>
<listitem>
<para>Using the singleton (static)
<literal>Configuration</literal> instance is clearly a bad
practice, so related methods are now deprecated, and the Manual
was adjusted, and the <literal>FreemarkerXmlTask</literal> was
updated as well.</para>
</listitem>
<listitem>
<para>The
<literal>freemarker.template.utility.Constants</literal> class
was added that contains various static final fields that store
frequently used constant <literal>TemplateModel</literal>
values, as <literal>EMPTY_SEQUENCE</literal>,
<literal>ZERO</literal>, ...etc.</para>
</listitem>
<listitem>
<para>When using <literal>SecurityManager</literal> with
FreeMarker, accessing system properties may caused
AccessControlException. Now such exceptions are catched and
logged with warning level, and the default value of the property
is returned.</para>
</listitem>
<listitem>
<para>The needles <literal>InvocationTargetException</literal>
is now removed from the exception cause trace in certain
cases.</para>
</listitem>
<listitem>
<para>Added a dirty hack that prints
<literal>ServletException</literal> root cause in
<literal>TemplateException</literal>'s stack trace if that's the
direct cause exception of the
<literal>TemplateException</literal>, despite the poorly written
<literal>ServletException</literal> class.</para>
</listitem>
<listitem>
<para>Bugfix: FreeMarker's implementation of
<literal>javax.servlet.jsp.PageContext.getSession()</literal>
was incorrect. The <literal>getSession()</literal> method is a
convenience method by which the custom tag can get the current
<literal>HttpSession</literal> object (possibly
<literal>null</literal> if there is no session). Till now, if
the session didn't existed then it has created it automatically,
so it never returned <literal>null</literal>. This was a bug, so
starting from 2.3.1 it never creates the session, just returns
<literal>null</literal> if it doesn't exist. The old incorrect
behavior could cause page rendering to fail if the method is
called after the page is partially flushed. But beware, the old
behavior has possibly hidden some bugs of the Web application,
where it forgot to create the session, so with the new correct
behavior you may face malfunction caused by previously cloaked
bugs of the Web application. (It's the task of the MVC
Controller to create the session, except if the JSP tag that
needs a session is written so it creates it automatically, but
then it doesn't expects that <literal>getSession()</literal>
will do it.)</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>BeansWrapper</literal> didn't always
handled properly the case of a Java class having both a public
static field and a public static method with the same
name.</para>
</listitem>
<listitem>
<para>Bugfix: <literal>SimpleMethodModel</literal> had
incorrectly propagate exceptions sometimes, causing null pointer
exception.</para>
</listitem>
<listitem>
<para>Bugfix: The template execution may used outdated cached
values when you have processed the same
<literal>Environment</literal> for multiple times, and changed
settings between the two processings. Note that this could
happen only in single-thread environment, where such setting
modifications are allowed.</para>
</listitem>
<listitem>
<para>Bugfix: Some of the string built-ins has died with
<literal>IndexOutOfBounds</literal> exception if the template
author has forgotten to specify required parameters. Now they
die with more helpful error messages.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.ext.dom.NodeModel.equals(...)</literal> has
died with null pointer exception if its argument was
<literal>null</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: The cause exception of
<literal>TemplateException</literal>-s was sometimes printed
twice in stack traces with J2SE 1.4 or later.</para>
</listitem>
<listitem>
<para>Bugfix: The
<literal>StringUtil.FTLStringLiteralEnc(String)</literal> method
was finished.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Fixes and improvements in the Manual and in the API
JavaDoc.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>The history of the releases before the final version</title>
<section>
<title>Differences between the preview release and final
release</title>
<itemizedlist>
<listitem>
<para>Added a dirty hack that prints
<literal>ServletException</literal> root cause in
<literal>TemplateException</literal>'s stack trace if that's
the direct cause exception of the
<literal>TemplateException</literal>, despite the poorly
written <literal>ServletException</literal> class.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.ext.dom.NodeModel.equals(...)</literal>
has died with null pointer exception if its argument was
<literal>null</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: The cause exception of
<literal>TemplateException</literal>-s was sometimes printed
twice in stack traces with J2SE 1.4 or later.</para>
</listitem>
<listitem>
<para>More minor improvements in the Manual.</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
<section xml:id="versions_2_3">
<title>2.3</title>
<para>Date of release: 2004-June-15</para>
<para>FreeMarker 2.3 introduces numerous little new features and
quality improvements compared to the 2.2.x series. The most notable
improvements are the ability to define functions (methods) in
templates, the ability to interpolate variables in string literals,
the support for a variable number of macro parameters, and the more
intelligent default object wrapper. Although none of the improvements
is a drastic change, the 2.3.x series is not backward compatible with
the 2.2.x series (see the list below), so you may choose to use it for
new projects only.</para>
<para>Probably the most ``loudly promoted'' new feature is the totally
redesigned XML wrapper. With the new XML wrapper FreeMarker targets a
new application domain, which is similar to the application domain of
XSLT: transforming complex XML to whatever textual output. Although
this subproject is young, it is definitely usable in practice. See the
<link linkend="xgui">XML Processing Guide</link> for more
details.</para>
<section>
<title>Non backward-compatible changes!</title>
<itemizedlist>
<listitem>
<para>Since interpolations (<literal>${...}</literal> and
<literal>#{...}</literal>) now work inside string literals, the
character sequence <literal>${</literal> and
<literal>#{</literal> in string literals are reserved for that.
So if you have something like <literal><#set x =
"${foo}"></literal>, then you have to replace it with
<literal><#set x = r"${foo}"></literal> -- beware, escapes
such as <literal>\n</literal> will not work in raw
(<literal>r</literal>) strings.</para>
</listitem>
<listitem>
<para>The default (initial) value of the
<literal>strict_syntax</literal> setting has been changed from
<literal>false</literal> to <literal>true</literal>. When
<literal>strict_syntax</literal> is <literal>true</literal>,
tags with old syntax as <literal><include
"foo.ftl"></literal> will be considered as static text (so
they go to the output as-is, like HTML tags do), and not as FTL
tags. Such tags have to be rewritten to <literal><#include
"foo.ftl"></literal>, since only parts that starts with
<literal><#</literal>, <literal></#</literal>,
<literal><@</literal>, or <literal></@</literal> count as
FTL tags. Or, to recover the old transitional behavior, where
both legacy and new tag syntax was recognized, you have to
explicitly set <literal>strict_syntax</literal> to
<literal>false</literal>:
<literal>cfg.setStrictSyntaxMode(false)</literal>. Also, for
individual templates you can force the old behavior by starting
the template with <literal><#ftl
strict_syntax=false></literal>. (For more information about
why strict syntax is better than old syntax <link
linkend="ref_depr_oldsyntax">read this...</link>)</para>
</listitem>
<listitem>
<para>Several classes were moved from the
<literal>freemarker.template</literal> package, to the new
<literal>freemarker.core</literal> package:</para>
<itemizedlist spacing="compact">
<listitem>
<para>"Normal" classes: <literal>ArithmeticEngine</literal>,
<literal>Configurable</literal>,
<emphasis><literal>Environment</literal></emphasis></para>
</listitem>
<listitem>
<para>Exceptions:
<literal>InvalidReferenceException</literal>,
<literal>NonBooleanException</literal>,
<literal>NonNumericalException</literal>,
<literal>NonStringException</literal>,
<literal>ParseException</literal>,
<literal>StopException</literal></para>
</listitem>
<listitem>
<para>Errors: <literal>TokenMgrError</literal></para>
</listitem>
</itemizedlist>
<para>The main reason of the splitting of
<literal>freemarker.template</literal> package was that the
amount of "expert" public classes and interfaces grows too much,
as we introduce API-s for third-party tools, such as debugging
API.</para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplateMethodModel.exec</literal>
now returns <literal>Object</literal> instead of
<literal>TemplateModel</literal>.</para>
</listitem>
<listitem>
<para>White-space stripping is now more aggressive as before: it
always removes leading and trailing white-space if the line only
contains FTL tags. (Earlier the white-space was not removed if
the tag was <literal><#include
<replaceable>...</replaceable>></literal> or user-defined
directive tag with empty directive syntax as
<literal><@myMacro/></literal> (or its equivalents:
<literal><@myMacro></@myMacro></literal> and
<literal><@myMacro></@></literal>). Now white-space
is removed in these cases as well.) Also, white-space sandwiched
between two non-outputting elements, such as macro definitions,
assignments, imports, or property settings, is now ignored. More
information: <xref
linkend="dgui_misc_whitespace_stripping" /></para>
</listitem>
<listitem>
<para>The <literal>function</literal> directive is now used for
defining methods. You should replace <literal>function</literal>
with <literal>macro</literal> in your old templates. Note,
however, that old <literal>function</literal>-s will still work
if you don't use the <literal>return</literal> directive in
them, and you invoke them with the deprecated the
<literal>call</literal> directive.</para>
</listitem>
<listitem>
<para>The expressions <literal>as</literal>,
<literal>in</literal>, and <literal>using</literal> are now
keywords in the template language and cannot be used as
top-level variable names without square-bracket syntax. If, by
some chance, you have top-level variables that use one of these
names, you will have to rename them, or use the square-bracket
syntax with the <literal>.vars</literal> special variable:
<literal>.vars["in"]</literal>.</para>
</listitem>
<listitem>
<para>The <literal>?new</literal> built-in, as it was
implemented, was a security hole. Now, it only allows you to
instantiate a java object that implements the
<literal>freemarker.template.TemplateModel</literal> interface.
If you want the functionality of the <literal>?new</literal>
built-in as it existed in prior versions, make available an
instance of the
<literal>freemarker.template.utility.ObjectConstructor</literal>
class to your template. (For example:
<literal>myDataModel.put("objConstructor", new
ObjectConstructor());</literal>, and then in the template you
can do this: <literal><#assign aList =
objConstructor("java.util.ArrayList", 100)></literal>)</para>
</listitem>
<listitem>
<para>Changes to the
<literal>FreemarkerServlet</literal>:</para>
<itemizedlist>
<listitem>
<para>The <literal>FreemarkerServlet</literal> uses
<literal>ObjectWrapper.DEFAULT_WRAPPER</literal> by default
instead of <literal>ObjectWrapper.BEANS_WRAPPER</literal>.
What this means is that, by default, objects of type
<literal>java.lang.String</literal>,
<literal>java.lang.Number</literal>,
<literal>java.util.List</literal>, and
<literal>java.util.Map</literal> will be wrapped as
<literal>TemplateModels</literal> via the classes
<literal>SimpleScalar</literal>,
<literal>SimpleNumber</literal>,
<literal>SimpleSequence</literal>, and
<literal>SimpleHash</literal> respectively. Thus, the java
methods on those objects will not be available. The default
wrapper implementation in FreeMarker 2.3 automatically knows
how to wrap Jython objects, and also wraps
<literal>org.w3c.dom.Node</literal> objects into instances
of <literal>freemarker.ext.dom.NodeModel</literal>.</para>
</listitem>
<listitem>
<para>The <literal>FreemarkerServlet</literal> base
implementation no longer deduces the locale used for
templates with <literal>HttpRequest.getLocale()</literal>.
Rather, it simply delegates to the new protected method,
<literal>deduceLocale</literal>. The default implementation
of this method simply returns the value of configuration the
<literal>locale</literal> setting.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Interpolation in string literals. For convenience,
interpolations are now supported in string literals. For
example: <literal><@message "Hello ${user}!" /></literal>
is the same as <literal><@message "Hello " + user + "!"
/></literal></para>
</listitem>
<listitem>
<para>Raw string literals: In string literals prefixed with
<literal>r</literal>, interpolations and escape sequences will
not be interpreted as special tokens. For example:
<literal>r"\n${x}"</literal> will be simply interpreted as the
character sequence <literal>'\'</literal>,
<literal>'n'</literal>, <literal>'$'</literal>,
<literal>'{'</literal>, <literal>'x'</literal>,
<literal>'}'</literal>, and not as line-feed and the value of
the <literal>x</literal> variable.</para>
</listitem>
<listitem>
<para>Method variables can be defined in FTL, with the <link
linkend="ref.directive.function"><literal>function</literal></link>
directive.</para>
</listitem>
<listitem>
<para>Support for a variable number of macro parameters. If the
last parameter in a macro declaration ends with
<literal>...</literal>, all extra parameters passed to the macro
will be available via that parameter. For macros called with
positional parameters, the parameter will be a sequence. For
named parameters, the parameter will be a hash. Note that it all
works with the new <literal>function</literal> directive as
well.</para>
</listitem>
<listitem>
<para>A new header parameter, <literal>strip_text</literal>,
that removes all top-level text from a template. This is useful
for ``include files'' to suppress newlines that separate the
macro definitions. See <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link></para>
</listitem>
<listitem>
<para>New <link linkend="ref_specvar">special variable</link>:
<literal>.vars</literal>. This is useful to read top-level
variables with square bracket syntax, for example
<literal>.vars["name-with-hyphens"]</literal> and
<literal>.vars[dynamicName]</literal>.</para>
</listitem>
<listitem>
<para><literal>macro</literal> and assignment directives now
accept arbitrary destination variable name with quoted syntax.
For example: <literal><#macro
"name-with-hyphens"><replaceable>...</replaceable></literal>
or <literal><#assign "foo bar" = 123></literal>.</para>
</listitem>
<listitem>
<para>The <literal>?keys</literal> and
<literal>?values</literal> hash built-ins now return sequences.
In practical terms this means you can access their sizes or
retrieve their subvariables by index, and use all of the <link
linkend="ref_builtins_sequence">sequence built-ins</link>. (Note
for the programmers: The <literal>TemplateHashModelEx</literal>
interface has not been changed. Your old code will work. See the
API documentation to see why.)</para>
</listitem>
<listitem>
<para>Existence built-ins (<literal>?default</literal>,
<literal>?exists</literal>, etc.) are now working with sequence
subvariables as well. Read the documentation of the
<literal>default</literal> built-in for more information.</para>
</listitem>
<listitem>
<para>White-space stripping is now more aggressive as before: it
always removes leading and trailing white-space if the line only
contains FTL tags. (Earlier the white-space was not removed if
the tag was <literal><#include
<replaceable>...</replaceable>></literal> or user-defined
directive tag with empty directive syntax as
<literal><@myMacro/></literal> (or its equivalents:
<literal><@myMacro></@myMacro></literal> and
<literal><@myMacro></@></literal>). Now white-space
is removed in these cases as well.) Also, top-level white-space
that separates macro definitions and/or assignments is now
ignored. More information: <xref
linkend="dgui_misc_whitespace_stripping" /></para>
</listitem>
<listitem>
<para>White-space stripping can be disabled for a single line
with the <link
linkend="ref.directive.nt"><literal>nt</literal></link>
directive (for No Trim).</para>
</listitem>
<listitem>
<para>Hashes can be concatenated using the <literal>+</literal>
operator. The keys in the hash on the right-hand side take
precedence.</para>
</listitem>
<listitem>
<para>New built-ins for Java and JavaScript string escaping:
<link linkend="ref_builtin_j_string">j_string</link> and <link
linkend="ref_builtin_js_string">js_string</link></para>
</listitem>
<listitem>
<para>The <literal>replace</literal> and
<literal>split</literal> built-ins now support case-insensitive
comparsion and regular expressions (J2SE 1.4+ only), and some
other new options. More information can be found <link
linkend="ref_builtin_string_flags">here</link>.</para>
</listitem>
<listitem>
<para>New built-in for regular expression matching (J2SE 1.4+
only): <link
linkend="ref_builtin_matches"><literal>matches</literal></link></para>
</listitem>
<listitem>
<para>New built-in, <literal>eval</literal>, to evaluate a
string as FTL expression. For example
<literal>"1+2"?eval</literal> returns the number 3.</para>
</listitem>
<listitem>
<para>New built-ins for Java and JavaScript string escaping:
<link linkend="ref_builtin_j_string">j_string</link> and <link
linkend="ref_builtin_js_string">js_string</link></para>
</listitem>
<listitem>
<para>New special variables to read the value of the locale
setting: <literal>locale</literal>, <literal>lang</literal>. See
more <link linkend="ref_specvar">in the
reference...</link></para>
</listitem>
<listitem>
<para>New special variable to read the FreeMarker version
number: <literal>version</literal>. See more <link
linkend="ref_specvar">in the reference...</link></para>
</listitem>
<listitem>
<para>Tree new directives, <literal>recurse</literal>,
<literal>visit</literal> and <literal>fallback</literal>, were
introduced to support declarative node-tree processing. These
are meant to be used typically (though not exclusively) for
processing XML input. Together with this, a new variable type
has been introduced, the node type. See the <link
linkend="xgui_declarative">chapter on declarative XML
processing</link> for more details.</para>
</listitem>
<listitem>
<para>The <literal>?new</literal> built-in, as it was
implemented, was a security hole. Now, it only allows you to
instantiate a java object that implements the
<literal>freemarker.template.TemplateModel</literal> interface.
<phrase role="forProgrammers">If you want the functionality of
the <literal>?new</literal> built-in as it existed in prior
versions, make available an instance of the
<literal>freemarker.template.utility.ObjectConstructor</literal>
class to your template. (For example:
<literal>myDataModel.put("objConstructor", new
ObjectConstructor());</literal>, and then in the template you
can do this: <literal><#assign aList =
objConstructor("java.util.ArrayList",
100)></literal>)</phrase></para>
</listitem>
<listitem>
<para>Variable names can contain <literal>@</literal> anywhere
(without using quote-bracket syntax). For example:
<literal><#assign x@@@ = 123></literal> is valid.</para>
</listitem>
<listitem>
<para>The expressions <literal>as</literal>,
<literal>in</literal>, and <literal>using</literal> are now
keywords in the template language and cannot be used as
top-level variable names without square-bracket syntax (as
<literal>.vars["in"]</literal>).</para>
</listitem>
<listitem>
<para>New parameter to the <link
linkend="ref_directive_ftl"><literal>ftl</literal>
directive</link>: <literal>attributes</literal>. The value of
this attribute is a hash that associates arbitrary attributes
(name-value pairs) to the template. The values of the attributes
can be of any type (string, number, sequence... etc.).
FreeMarker doesn't try to understand the meaning of the
attributes. It's up to the application that encapsulates
FreeMarker (as a Web application framework). Thus, the set of
allowed attributes and their semantic is application (Web
application framework) dependent.</para>
</listitem>
<listitem>
<para>Other minor quality improvements...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Smarter default object wrapping: The default object
wrapper is now
<literal>freemarker.template.DefaultObjectWrapper</literal>,
which falls back on wrapping arbitrary objects as beans using
the <literal>freemarker.ext.beans.BeansWrapper</literal>. Also,
it will wrap <literal>org.w3c.dom.Node</literal> objects with
the new DOM wrapper. Also, it is aware of Jython objects, and
will use <literal>freemarker.ext.jython.JythonWrapper</literal>
if the object passed in is a Jython object. (We count it as a
backward compatible change, since this new object wrapper wraps
differently only those objects that the old wrapper was not able
to wrap, so it has thrown exception.)</para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplateMethodModel.exec</literal>
now returns <literal>Object</literal> instead of
<literal>TemplateModel</literal>.</para>
</listitem>
<listitem>
<para>The default (initial) value of the
<literal>strict_syntax</literal> setting has been changed from
<literal>false</literal> to <literal>true</literal>. When
<literal>strict_syntax</literal> is <literal>true</literal>,
tags with old syntax as <literal><include
"foo.ftl"></literal> will be considered as static text (so
they go to the output as-is, like HTML tags do), and not as FTL
tags. Such tags have to be rewritten to <literal><#include
"foo.ftl"></literal>, since only parts that starts with
<literal><#</literal>, <literal></#</literal>,
<literal><@</literal>, or <literal></@</literal> count as
FTL tags. Or, to recover the old transitional behavior, where
both legacy and new tag syntax was recognized, you have to
explicitly set <literal>strict_syntax</literal> to
<literal>false</literal>:
<literal>cfg.setStrictSyntaxMode(false)</literal>. Also, for
individual templates you can force the old behavior by starting
the template with <literal><#ftl
strict_syntax=false></literal>. (For more information about
why strict syntax is better than old syntax <link
linkend="ref_depr_oldsyntax">read this...</link>)</para>
</listitem>
<listitem>
<para>New <literal>CacheStorage</literal> implementation:
<literal>freemarker.cache.MruCacheStorage</literal>. This cache
storage implements a two-level Most Recently Used cache. In the
first level, items are strongly referenced up to the specified
maximum. When the maximum is exceeded, the least recently used
item is moved into the second level cache, where they are softly
referenced, up to another specified maximum.
<literal>freemarker.cache.SoftCachseStorage</literal> and
<literal>StrongCachseStorage</literal> are deprected,
<literal>MruCachseStorage</literal> is used everywhere instead.
The default cache storage is now an
<literal>MruCachseStorage</literal> object with 0 strong size,
and infinite soft size.
<literal>Configuration.setSetting</literal> for
<literal>cache_storage</literal> now understands string values
as <literal>"strong:200, soft:2000"</literal>.</para>
</listitem>
<listitem>
<para>For <literal>BeansWrapper</literal> generated models, you
can now use the <literal>${obj.method(args)}</literal> syntax to
invoke methods whose return type is <literal>void</literal>.
<literal>void</literal> methods now return
<literal>TemplateModel.NOTHING</literal> as their return
value.</para>
</listitem>
<listitem>
<para><literal>freemarker.template.SimpleHash</literal> now can
wrap read-only <literal>Map</literal>-s, such as the map of HTTP
request parameters in Servlet API.</para>
</listitem>
<listitem>
<para>The <literal>TemplateNodeModel</literal> interface was
introduced to support recursive processing of trees of nodes.
Typically, this will be used in relation to XML.</para>
</listitem>
<listitem>
<para>New package: <literal>freemarker.ext.dom</literal>. This
contains the new XML wrapper, that supports the processing of
XML documents using the visitor pattern (i.e. with
<literal><#visit <replaceable>...</replaceable>></literal>
and similar directives), and to provide more convenient XML
traversing as the legacy wrapper. See the <link
linkend="xgui">XML processing guide</link> for more
details.</para>
</listitem>
<listitem>
<para>New package: <literal>freemarker.core</literal>. Classes
used by mostly power-users was moved here from the
<literal>freemarker.template</literal> package. The main reason
of the splitting of <literal>freemarker.template</literal>
package was that the amount of "expert" public classes and
interfaces grows too much, as we introduce API-s for third-party
tools, such as debugging API.</para>
</listitem>
<listitem>
<para>New package: <literal>freemarker.debug</literal>. This
provides a debugging API, by which you can debug executing
templates through network (RMI). You have to write the front-end
(client), as the API is just the server side. For more
information please read the JavaDoc of the
<literal>freemarker.debug</literal> package.</para>
</listitem>
<listitem>
<para>You can query the FreeMarker version number with static
method <literal>Configuration.getVersionNumber()</literal>.
Also, the <literal>Manifest.mf</literal> included in
<literal>freemarker.jar</literal> now contains the FreeMarker
version number, furthermore, executing it with <literal>java
-jar freemarker.jar</literal> will print the version number to
the stdout.</para>
</listitem>
<listitem>
<para>Added a new protected <literal>FreemarkerServlet</literal>
method: <literal>Configuration
getConfiguration()</literal>.</para>
</listitem>
<listitem>
<para>Date support is now labeled as final. (It was experimental
earlier.)</para>
</listitem>
<listitem>
<para>The <literal>BeansWrapper</literal> has been improved to
prevent some security exceptions when introspecting.</para>
</listitem>
<listitem>
<para>Other minor quality improvements and extensions...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Fixes and improvements in the Manual and in the API
JavaDoc.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>The history of the releases before the final version</title>
<section>
<title>Differences between the final release and Release Candidate
4</title>
<itemizedlist>
<listitem>
<para>Added a new special variable to print the FreeMarker
version number: <literal>version</literal>. See more <link
linkend="ref_specvar">in the reference...</link></para>
</listitem>
<listitem>
<para>Minor documentation fixes and improvements.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Release Candidate 4 and Release
Candidate 3</title>
<itemizedlist>
<listitem>
<para>The <literal>BeansWrapper</literal> has been improved to
prevent some security exceptions when introspecting.</para>
</listitem>
<listitem>
<para>The <literal>FreemarkerXmlTask</literal> has two new
sub-tasks that can be used to prepare template execution with
Jython scripts: <literal>prepareModel</literal> and
<literal>prepareEnvironment</literal>. The
<literal>jython</literal> sub-task is now deprecated, and does
the same as <literal>prepareEnvironment</literal>. See the
Java API documentation for more details.</para>
</listitem>
<listitem>
<para>New special variable to read the FreeMarker version
number: <literal>version</literal>. See more <link
linkend="ref_specvar">in the reference...</link></para>
</listitem>
<listitem>
<para>Bugfix: Greater-than sign doesn't confuse the
<literal>eval</literal> built-in anymore.</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>BeansWrapper</literal> now wrapps
the <literal>null</literal> return values of methods
appropriately.</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>FreemarkerXmlTask</literal> doesn't
need Jython classes anymore, unless you really use Jython
scripts. Several other bugfixes in the Jython related
features.</para>
</listitem>
<listitem>
<para>Bugfix: If the template exception handler has ignored
the exception, errors occurring in interpolations inside FTL
tags (e.g. <literal><#if "foo${badVar}" !=
"foobar"></literal>) were handled in the same way as errors
occuring in interpolations outside FTL tags. Thus, the
directive call was not skipped, and the problematic
interpolation was replaced with an empty string. (This was
inconsistent with the behavior of <literal><#if
"foo"+badVar != "foobar"></literal>, which should be 100%
equivalent with the previous example.)</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>FileTemplateLoader</literal> is now
more robust when it receives paths that are malformed
according the native file system. In the earlier version such
paths sometimes caused unexpected
<literal>IOException</literal> that aborted the searching for
the template in further
<literal>FileTemplateLoader</literal>-s when you use the
<literal>MultiTemplateLoader</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Release Candidate 3 and Release
Candidate 2</title>
<itemizedlist>
<listitem>
<para>Bugfix: Fixing a fatal bug in the template cache that
was introduced with the latest cache ``bugfix''. The template
cache has always reloaded the unchanged template when the
update delay has been elapsed, until the template has been
actually changed, in which case it has never reloaded the
template anymore.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Release Candidate 2 and Release
Candidate 1</title>
<itemizedlist>
<listitem>
<para>Bugfix: The template cache didn't reload the template
when it was replaced with an older version.</para>
</listitem>
<listitem>
<para>API JavaDoc fix: date/time related classes/interfaces
were marked as experimental. They are not experimental.</para>
</listitem>
<listitem>
<para>Minor site improvements.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Release Candidate 1 and Preview 16
releases</title>
<itemizedlist>
<listitem>
<para><emphasis>Warning! Non-backward-compatible
change!</emphasis> The default (initial) value of the
<literal>strict_syntax</literal> setting has been changed from
<literal>false</literal> to <literal>true</literal>. When
<literal>strict_syntax</literal> is <literal>true</literal>,
tags with old syntax as <literal><include
"foo.ftl"></literal> will be considered as static text (so
they go to the output as-is, like HTML tags do), and not as
FTL tags. Such tags have to be rewritten to
<literal><#include "foo.ftl"></literal>, since only
parts that starts with <literal><#</literal>,
<literal></#</literal>, <literal><@</literal>, or
<literal></@</literal> count as FTL tags. Or, to recover
the old transitional behavior, where both legacy and new tag
syntax was recognized, you have to explicitly set
<literal>strict_syntax</literal> to <literal>false</literal>:
<literal>cfg.setStrictSyntaxMode(false)</literal>. Also, for
individual templates you can force the old behavior by
starting the template with <literal><#ftl
strict_syntax=false></literal>. (For more information about
why strict syntax is better than old syntax <link
linkend="ref_depr_oldsyntax">read this...</link>)</para>
</listitem>
<listitem>
<para>New parameter to the <link
linkend="ref_directive_ftl"><literal>ftl</literal>
directive</link>: <literal>attributes</literal>. The value of
this attribute is a hash that associates arbitrary attributes
(name-value pairs) to the template. The values of the
attributes can be of any type (string, number, sequence...
etc.). FreeMarker doesn't try to understand the meaning of the
attributes. It's up to the application that encapsulates
FreeMarker (as a Web application framework). Thus, the set of
allowed attributes and their semantic is application (Web
application framework) dependent.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.template.utility.DeepUnwrap</literal>
unwrapped sequences to empty
<literal>ArrayList</literal>-s.</para>
</listitem>
<listitem>
<para>Bugfix: If you included/imported a template with
<literal>*/</literal> in path (acquisition), and that template
in turn itself included/imported another template with
<literal>*/</literal> in path, it may failed.</para>
</listitem>
<listitem>
<para>New methods to the
<literal>freemarker.core.Environment</literal>:
<literal>importLib(Template loadedTemplate, java.lang.String
namespace)</literal>,
<literal>getTemplateForImporting(...)</literal>,
<literal>getTemplateForInclusion(...)</literal>.</para>
</listitem>
<listitem>
<para>Improvements in the
<literal>java.io.IOException</literal> related error messages
of the <literal>include</literal> and
<literal>import</literal> directives.</para>
</listitem>
<listitem>
<para>Minor improvements in the documentation.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 16 and Preview 15
releases</title>
<itemizedlist>
<listitem>
<para>New package: <literal>freemarker.debug</literal>. This
provides a debugging API, by which you can debug executing
templates through network (RMI). You have to write the
front-end (client), as the API is just the server side. For
more information please read the JavaDoc of the
<literal>freemarker.debug</literal> package. (The debugging
API is present for a while, just I forgot to announce it in
the version history. Sorry for that.)</para>
</listitem>
<listitem>
<para>Bugfix: With the new XML wrapper,
<literal>@@markup</literal> and similar special keys:</para>
<itemizedlist>
<listitem>
<para>have returned
<literal><foo></foo></literal> for empty
elements instead of <literal><foo /></literal>.
Other than it was needlessly verbose, it has confused
browsers if you generate HTML.</para>
</listitem>
<listitem>
<para>have showed the attributes that have no explicitly
given value in the original document, just a default value
coming form the DTD.</para>
</listitem>
<listitem>
<para>have forgot to put space before the system
identifier in the <literal><!DOCTYPE
<replaceable>...</replaceable>></literal>.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Bugfix: XPath with Jaxen has died with
<literal>NullPointerException</literal> if the context was an
empty node set.</para>
</listitem>
<listitem>
<para>A bit more intelligent Xalan XPath error
messages.</para>
</listitem>
<listitem>
<para>Revoked fallback-to-classloader logic from the template
cache.</para>
</listitem>
<listitem>
<para>From now, if no XPath engine is available, and the hash
key in an ``XML query'' can't be interpreted without XPath, an
error will tell this clearly, rather than silently returning
undefined variable (null).</para>
</listitem>
<listitem>
<para>Bugfix: Some templates have caused the parser to
die.</para>
</listitem>
<listitem>
<para>Some other minor improvements here and there...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 15 and Preview 14
releases</title>
<itemizedlist>
<listitem>
<para>Bugfix: The new default template cache storage
(<literal>MruCacheStorage</literal>) has started to
continually fail with <literal>NullPointerException</literal>
from a random point of time, usually when the memory usage was
high in the JVM.</para>
</listitem>
<listitem>
<para>Bugfix: In error messages, when the quoted FTL directive
had nested content, that was quoted as well, so the quotation
could be very long and expose nested lines needlessly.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 14 and Preview 13
releases</title>
<itemizedlist>
<listitem>
<para><literal>freemarker.template.TemplateMethodModel.exec</literal>
now returns <literal>Object</literal> instead of
<literal>TemplateModel</literal>.</para>
</listitem>
<listitem>
<para>Fixes and improvements for XPath with Jaxen (not Xalan).
Non-node-set XPath expressions are now working. FreeMarker
variables are accessible in XPath expressions with XPath
variable references (e.g.
<literal>doc["book/chapter[title=$currentTitle]"]</literal>).</para>
</listitem>
<listitem>
<para><literal>freemarker.cache.SoftCachseStorage</literal>
and <literal>StrongCachseStorage</literal> is deprected. The
more flexible <literal>MruCachseStorage</literal> is used
instead everywhere. The default cache storage is now an
<literal>MruCachseStorage</literal> object with 0 strong size,
and infinite soft size.
<literal>Configuration.setSetting</literal> for
<literal>cache_storage</literal> now understands string values
as <literal>"strong:200, soft:2000"</literal>.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.cache.MruCachseStorage</literal> has died
with <literal>ClassCastException</literal> sometimes.</para>
</listitem>
<listitem>
<para>New built-ins for Java and JavaScript string escaping:
<link linkend="ref_builtin_j_string">j_string</link> and <link
linkend="ref_builtin_js_string">js_string</link></para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</literal>
now prints more HTML-context-proof messages.</para>
</listitem>
<listitem>
<para>You can query the FreeMarker version number with static
method <literal>Configuration.getVersionNumber()</literal>.
Also, the <literal>Manifest.mf</literal> included in
<literal>freemarker.jar</literal> now contains the FreeMarker
version number, furthermore, executing it with <literal>java
-jar freemarker.jar</literal> will print the version number to
the stdout.</para>
</listitem>
<listitem>
<para>Added a new protected
<literal>FreemarkerServlet</literal> method:
<literal>Configuration getConfiguration()</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: FreeMarker has frozen on empty conditional
blocks in certain contexts.</para>
</listitem>
<listitem>
<para>Bugfix: Methods called twice on an object using the
<literal>list</literal> directive, as
<literal>parent.getChildren()</literal> with
<literal><#list parent.children as child>
...</#list></literal></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 13 and Preview 12
releases</title>
<itemizedlist>
<listitem>
<para>White-space stripping is now more aggressive as before:
it always removes leading and trailing white-space if the line
only contains FTL tags. (Earlier the white-space was not
removed if the tag was <literal><#include
<replaceable>...</replaceable>></literal> or user-defined
directive tag with empty directive syntax as
<literal><@myMacro/></literal> (or its equivalents:
<literal><@myMacro></@myMacro></literal> and
<literal><@myMacro></@></literal>). Now
white-space is removed in these cases as well.) Also,
top-level white-space that separates macro definitions and/or
assignments is now ignored. More information: <xref
linkend="dgui_misc_whitespace_stripping" /></para>
</listitem>
<listitem>
<para>White-space stripping can be disabled for a single line
with the <link
linkend="ref.directive.nt"><literal>nt</literal></link>
directive (for No Trim).</para>
</listitem>
<listitem>
<para>A new directive for the declarative XML processing:
<link
linkend="ref.directive.fallback"><literal>fallback</literal></link></para>
</listitem>
<listitem>
<para><literal>freemarker.template.SimpleHash</literal> now
can wrap read-only <literal>Map</literal>-s, such as the map
of HTTP request parameters in Servlet API.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 12 and Preview 11
releases</title>
<para>The only change between this and the previous preview
release is that Preview 11 had a bug where DOM trees would
<emphasis>never</emphasis> be garbage-collected.</para>
</section>
<section>
<title>Differences between the Preview 11 and Preview 10
releases</title>
<itemizedlist>
<listitem>
<para>Many XML related changes. Some of them are incompatible
with the previous preview releases! For a more detailed
explanation of how XML related features now work, see: <xref
linkend="xgui" /></para>
<itemizedlist>
<listitem>
<para>Attention! Attribute queries such as
<literal>foo.@bar</literal> now return sequences
(similarly to child element queries and XPath queries),
not single nodes. Because of the rule with node sequences
of size 1, it is still good to write
<literal>${foo.@bar}</literal>, but built-ins such as
<literal>?exists</literal>, <literal>?if_exists</literal>
or <literal>?default</literal> don't work as before. For
example, instead of
<literal>foo.@bar?default('black')</literal>, you now have
to write <literal>foo.@bar[0]?default('black')</literal>.
So if you have used existence built-ins with attributes,
you have to find those occurrences in the templates and
add that <literal>[0]</literal>.</para>
</listitem>
<listitem>
<para>Attention! XML name-space handling has been totally
reworked and is absolutely incompatible with pre 10. Don't
worry about this if none of your XML input documents use
you use <literal>xmlns</literal> attributes. Worry,
though, if you have utilized the ``loose mode'', where
only the local name of elements were compared, because
that's now gone. Sorry...</para>
</listitem>
<listitem>
<para>Attention! Special-keys <literal>@@</literal> and
<literal>@*</literal> now return a sequence of attribute
nodes instead of the hash of them.</para>
</listitem>
<listitem>
<para>Several hash keys are now working for node sequences
that store multiple nodes. For example, to get the list of
all <literal>para</literal> elements of all
<literal>chapter</literal>-s, just write
<literal>doc.book.chapter.para</literal>. Or, to get list
of title attributes of all <literal>chapter</literal>-s
write <literal>doc.book.chapter.@title</literal>.</para>
</listitem>
<listitem>
<para>New special hash keys: <literal>**</literal>,
<literal>@@start_tag</literal>,
<literal>@@end_tag</literal>,
<literal>@@attribute_markup</literal>,
<literal>@@text</literal>,
<literal>@@qname</literal>.</para>
</listitem>
<listitem>
<para><literal>?parent</literal> for attribute nodes now
returns the element node the attribute node belongs
to.</para>
</listitem>
<listitem>
<para>You can use Jaxen instead of Xalan for XPath
expressions, if you call the static
<literal>freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</literal>
method once. We plan to use Jaxen automatically instead of
Xalan if it is available, just the Jaxen support is not
fully functional yet.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>New special variable: <literal>.vars</literal>. This is
useful to read top-level variables with square bracket syntax,
for example <literal>.vars["name-with-hyphens"]</literal> and
<literal>.vars[dynamicName]</literal>.</para>
</listitem>
<listitem>
<para>New built-in, <literal>eval</literal>, to evaluate a
string as FTL expression. For example
<literal>"1+2"?eval</literal> returns the number 3.</para>
</listitem>
<listitem>
<para><literal>FreemarkerServlet</literal> now uses the
configuration's <literal>locale</literal> setting, rather than
<literal>Locale.getDefault()</literal>, to set the locale of
the templates. Also, the signature of the
<literal>deduceLocale</literal> method has been
changed.</para>
</listitem>
<listitem>
<para>We have a new (beta status)
<literal>CacheStorage</literal> implementation:
<literal>freemarker.cache.MruCacheStorage</literal>. This
cache storage implements a two-level Most Recently Used cache.
In the first level, items are strongly referenced up to the
specified maximum. When the maximum is exceeded, the least
recently used item is moved into the second level cache, where
they are softly referenced, up to another specified maximum.
You can plug to try it with <literal>cfg.setCacheStorage(new
freemarker.cache.MruCacheStorage(maxStrongSize,
maxSoftSize))</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 10 and Preview 9
releases</title>
<itemizedlist>
<listitem>
<para>The special key <literal>@@xmlns</literal> was removed
in favor of a new FTL directive for the same purpose,
<literal><#xmlns...></literal>.</para>
</listitem>
<listitem>
<para>By default, the system is stricter about the use of
namespace prefixes. In general, you must use a prefix to
qualify subelements that are associated with an XML
nampespace. You can do this with the new
<literal><#xmlns...></literal> directive, but prefixes
declared in the input XML doc will actually work with no
declaration.</para>
</listitem>
<listitem>
<para>Introduced a new special key called
<literal>@@text</literal> that returns all the text nodes
contained (recursively) in an element all concatenated
together.</para>
</listitem>
<listitem>
<para>Either Jaxen or Xalan can be used to provide XPath
functionality. Prior versions only worked with Xalan.</para>
</listitem>
<listitem>
<para>The <literal>FreemarkerServlet</literal> uses
<literal>ObjectWrapper.DEFAULT_WRAPPER</literal> by default
instead of <literal>ObjectWrapper.BEANS_WRAPPER</literal>.
What this means is that, by default, objects of type
<literal>java.lang.String</literal>,
<literal>java.lang.Number</literal>,
<literal>java.util.List</literal>, and
<literal>java.util.Map</literal> will be wrapped as
<literal>TemplateModels</literal> via the classes
<literal>SimpleScalar</literal>,
<literal>SimpleNumber</literal>,
<literal>SimpleSequence</literal>, and
<literal>SimpleHash</literal> respectively. Thus, the java
methods on those objects will not be available. The default
wrapper implementation in FreeMarker 2.3 automatically knows
how to wrap Jython objects, and also wraps
<literal>org.w3c.dom.Node</literal> objects into instances of
<literal>freemarker.ext.dom.NodeModel</literal>.</para>
</listitem>
<listitem>
<para>The <literal>FreemarkerServlet</literal> base
implementation no longer deduces the locale to use from the
HttpRequest.getLocale() hook. Rather, it simply delegates to a
<literal>deduceLocale()</literal> hook that is overridable in
subclasses. The base implementation simply uses
<literal>Locale.getDefault()</literal></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 9 and Preview 8
releases</title>
<itemizedlist>
<listitem>
<para>Fixed bugs introduced with Preview 8: XPath,
<literal>@@markup</literal> and
<literal>@@nested_markup</literal> now works with the document
node.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 8 and Preview 7
releases</title>
<itemizedlist>
<listitem>
<para><literal>macro</literal> and assignment directives now
accept arbitrary destination variable name with quoted syntax.
For example: <literal><#macro
"foo-bar"><replaceable>...</replaceable></literal> or
<literal><#assign "this+that" = 123></literal>. This is
important, because XML element names can contain hyphen, and
it was not possible to define a handler macro for those
elements, till now.</para>
</listitem>
<listitem>
<para>Special key <literal>@@content</literal> was renamed to
<literal>@@nested_markup</literal>.</para>
</listitem>
<listitem>
<para>Fixed outdated XML related Manual parts (that were
outdated even in Preview 7).</para>
</listitem>
<listitem>
<para>Better parse-error messages.</para>
</listitem>
<listitem>
<para>Minor bugfixes here and there...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 7 and Preview 6
releases</title>
<itemizedlist>
<listitem>
<para>Caching of XPath queries should lead to significant
performance improvements for XML processing, at least when
XPath is heavily used.</para>
</listitem>
<listitem>
<para>Refinements in handling of XML namespaces in the XML
processing functionality. The new
<literal>strict_namespace_handling</literal> setting
introduced in 2.3pre6 was removed. A general-purpose solution
was arrived at that should make that configuration setting
unnecessary.</para>
</listitem>
<listitem>
<para>Special key <literal>@xmlns</literal> was renamed to
@@xmlns. Reserved namespace prefix <literal>default</literal>
was renamed to <literal>@@default</literal>.</para>
</listitem>
<listitem>
<para>The <literal>ftl</literal> directive now accepts
non-string types.</para>
</listitem>
<listitem>
<para>New special keys were introduced for XML node wrappers
in the freemarker.ext.dom package. The
<literal>@@markup</literal> key returns the literal markup
that make up that element and the <literal>@@content</literal>
key returns all the element's markup excluding the opening and
closing tags.</para>
</listitem>
<listitem>
<para>Minor bugfixes here and there...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 6 and Preview 5
releases</title>
<itemizedlist>
<listitem>
<para>Existence built-ins (<literal>?default</literal>,
<literal>?exists</literal>, etc.) now work with sequence
subvariables as well. Read the <link
linkend="ref.directive.default">documentation of the
<literal>default</literal> built-in</link> for more
information.</para>
</listitem>
<listitem>
<para>The <literal>matches</literal> built-in now returns a
sequence instead of a collection.</para>
</listitem>
<listitem>
<para>Refinements in handling of XML namespaces in the XML
processing functionality. A new setting,
<literal>strict_namespace_handling</literal> was introduced.
If this is set (it is off by default) any node-handling macro
used in with the visit/recurse machinery must be from a macro
library that declares in its ftl header that it handles the
namespace in question.</para>
</listitem>
<listitem>
<para>Minor bugfixes here and there...</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 5 and Preview 4
releases</title>
<itemizedlist>
<listitem>
<para>The <literal>replace</literal> and
<literal>split</literal> built-ins now support
case-insensitive comparison and regular expressions (J2SE 1.4+
only), and some other new options. More information can be
found <link
linkend="ref_builtin_string_flags">here</link>.</para>
</listitem>
<listitem>
<para>New butilt-in for regular expression matching (J2SE 1.4+
only): <link
linkend="ref_builtin_matches"><literal>matches</literal></link></para>
</listitem>
<listitem>
<para>Minor bugfixes here and there...</para>
</listitem>
<listitem>
<para>Manual: More browser-safe HTML-s. More updated
content.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 4 and Preview 3
releases</title>
<itemizedlist>
<listitem>
<para>Bugfix: with multi-type variables, <literal>+</literal>
operator overload for hash type had higher precedence than the
precedence of some older overloads.</para>
</listitem>
<listitem>
<para>The API documentation was missing from the distribution
<literal>tar.gz</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 3 and Preview 2
releases</title>
<itemizedlist>
<listitem>
<para>XML processing: Many various bugfixes, especially with
the declarative processing.</para>
</listitem>
<listitem>
<para>XML processing: the <literal>namespace_uri</literal>
built-in, the <literal>xmlnsuri</literal> header parameter,
and the <literal>TemplateNodeModel.getNodeNamespace</literal>
method were renamed to <literal>node_namespace</literal> and
<literal>getNodeNamespace</literal> respectively.</para>
</listitem>
<listitem>
<para>XML processing: Better documentation. Especially, note:
<xref linkend="xgui" /></para>
</listitem>
<listitem>
<para>A new header parameter, <literal>strip_text</literal>,
that removes all top-level text from a template. See <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link></para>
</listitem>
<listitem>
<para>Support for a variable number of macro parameters. If
the last parameter in a macro declaration ends with
<literal>...</literal>, all extra parameters passed to the
macro will be available via that parameter. For macros called
with positional parameters, the parameter will be a sequence.
For named parameters, the parameter will be a hash.</para>
</listitem>
<listitem>
<para>For <literal>BeansWrapper</literal> generated models,
you can now use the <literal>${obj.method(args)}</literal>
syntax to invoke methods whose return type is
<literal>void</literal>. <literal>void</literal> methods now
return <literal>TemplateModel.NOTHING</literal> as their
return value.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 2 and Preview 1
releases</title>
<itemizedlist>
<listitem>
<para>The <literal>freemarker.ext.dom.NodeModel</literal> API
changed slightly. The <literal>setDocumentBuilder()</literal>
method was changed to
<literal>setDocumentBuilderFactory()</literal> because the
older scheme was not thread-safe. The
<literal>stripComments</literal> and
<literal>stripPIs</literal> methods are renamed to The
<literal>removeComments</literal> and
<literal>removePIs</literal>, and are fixed now. A new method,
<literal>simplify</literal> has been added.</para>
</listitem>
<listitem>
<para>The expressions <literal>as</literal>,
<literal>in</literal>, and <literal>using</literal> are now
keywords in the template language and cannot be used as
top-level variable names without square-bracket syntax (as
<literal>.vars["in"]</literal>). If, by some chance, you have
top-level variables that use one of these names, you will have
to rename them (or use the square-bracket syntax). Sorry for
the inconvenience.</para>
</listitem>
<listitem>
<para>The <literal>?new</literal> built-in, as it was
implemented, was a security hole. Now, it only allows you to
instantiate a java object that implements the
<literal>freemarker.template.TemplateModel</literal>
interface. If you want the functionality of the
<literal>?new</literal> built-in as it existed in prior
versions, make available an instance of the new
<literal>freemarker.template.utility.ObjectConstructor</literal>
class to your template.</para>
</listitem>
<listitem>
<para>The <literal><#recurse></literal> directive was
broken. It did not work with a <literal>using</literal>
clause. This is now fixed.</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
<section xml:id="versions_2_2_8">
<title>2.2.8</title>
<para>Date of release: 2004-June-15</para>
<para>Bugfix and maintenance release.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Added a new special variable to print the FreeMarker
version number: <literal>version</literal>. See more <link
linkend="ref_specvar">in the reference...</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>The <literal>BeansWrapper</literal> has been improved to
prevent some security exceptions when introspecting.</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>FileTemplateLoader</literal> is now
more robust when it receives paths that are malformed according
the native file system. In the earlier version such paths
sometimes caused unexpected <literal>IOException</literal> that
aborted the searching for the template in further
<literal>FileTemplateLoader</literal>-s when you use the
<literal>MultiTemplateLoader</literal>.</para>
</listitem>
<listitem>
<para>Some parts of the FreeMarker code has been marked as
privileged code section, so you can grant extra privileges to
FreeMarker when you use a security manager (this is a
backporting from 2.3). See more <link
linkend="pgui_misc_secureenv">here...</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Minor documentation fixes and improvements.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_7">
<title>2.2.7</title>
<para>Date of release: 2004-March-17</para>
<para>Important bugfix release.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: Fixing a fatal bug in the template cache that was
introduced with the latest cache ``bugfix''. The template cache
has always reloaded the unchanged template when the update delay
has been elapsed, until the template has been actually changed,
in which case it has never reloaded the template anymore.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_6">
<title>2.2.6</title>
<para>Date of release: 2004-March-13</para>
<para>Maintenance and bugfix release. Some of improvements are
back-portings from FreeMarker 2.3rc1.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New <link linkend="ref_specvar">special variable</link>:
<literal>.vars</literal>. This is useful to read top-level
variables with square bracket syntax, for example
<literal>.vars["name-with-hyphens"]</literal> and
<literal>.vars[dynamicName]</literal>.</para>
</listitem>
<listitem>
<para>New built-ins for Java and JavaScript string escaping:
<link linkend="ref_builtin_j_string">j_string</link> and <link
linkend="ref_builtin_js_string">js_string</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: The template cache didn't reload the template when
it was replaced with an older version.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>freemarker.template.utility.DeepUnwrap</literal>
unwrapped sequences to empty
<literal>ArrayList</literal>-s.</para>
</listitem>
<listitem>
<para>Bugfix: In error messages, when the quoted FTL directive
had nested content, that was quoted as well, so the quotation
could be very long and expose nested lines needlessly.</para>
</listitem>
<listitem>
<para><literal>freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</literal>
now prints more HTML-context-proof messages.</para>
</listitem>
<listitem>
<para>You can query the FreeMarker version number with static
method <literal>Configuration.getVersionNumber()</literal>.
Also, the <literal>Manifest.mf</literal> included in
<literal>freemarker.jar</literal> now contains the FreeMarker
version number, furthermore, executing it with <literal>java
-jar freemarker.jar</literal> will print the version number to
the stdout.</para>
</listitem>
<listitem>
<para>Date support is now labeled as final. (It was experimental
earlier.) There was no change since FreeMarker 2.2.1.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Fixes and improvements in the Manual and in the API
JavaDoc. The documentation now works with the Eclipse help
plugin (accessible in the ``Editor/IDE plugins'' section of the
FreeMarker Web page).</para>
</listitem>
<listitem>
<para>Minor site improvements.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_5">
<title>2.2.5</title>
<para>Date of release: 2003-09-19</para>
<para>Maintenance and bugfix release.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Creating a <literal>Configuration</literal> instance using
the default constructor no longer fails if the current directory
is unreadable due to I/O problems, lack of security permissions,
or any other exception.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_4">
<title>2.2.4</title>
<para>Date of release: 2003-09-03</para>
<para>Maintenance and bugfix release.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Improvements to JSP taglib support. If some third party
taglib didn't work for you with FreeMarker, maybe now it
will.</para>
<itemizedlist>
<listitem>
<para>The JSP <literal>PageContext</literal> now implements
<literal>forward</literal> and <literal>include</literal>
methods.</para>
</listitem>
<listitem>
<para>Accepting <literal>EVAL_PAGE</literal> as an alias to
<literal>SKIP_BODY</literal> in return values from
<literal>doStartTag</literal>. It's a common bug in some
widespread tag libraries, and now FreeMarker is less strict
and accepts it.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Fixes for some rare problems regarding namespaces of
macros.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Minor improvements to the documentation.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_3">
<title>2.2.3</title>
<para>Date of release: 2003-07-19</para>
<para>Bugfix release.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Added the <literal>is_date</literal> built-in.</para>
</listitem>
<listitem>
<para>Bugfix: Various <literal>is_xxx</literal> built-ins were
returning <literal>false</literal> when applied to undefined
expressions. Now they correctly fail on them.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: The JSP taglib support can now read JSP 1.2
compliant TLD XML files.</para>
</listitem>
<listitem>
<para>Bugfix: The JSP taglib support now emits more helpful
exception messages when the specified TLD XML file is not found
(previously it threw a
<literal>NullPointerException</literal>).</para>
</listitem>
<listitem>
<para>Bugfix: The JSP taglib support now initializes a custom
tag after its parent and page context is set as some tags expect
them to be set when attribute setters are called.</para>
</listitem>
<listitem>
<para>Bugfix: The <literal>BeansWrapper</literal> could fail to
analyze classes under very rare circumstances due to a premature
storage optimization.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_2">
<title>2.2.2</title>
<para>Date of release: 2003-05-02</para>
<para>Bugfix release.</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: The <literal>_text</literal> key of the
<literal>freemarker.ext.xml.NodeListModel</literal> was not
returning the text of the element when used with W3C DOM
trees.</para>
</listitem>
<listitem>
<para>The classes are now built against JDK 1.2.2 classes,
ensuring the binary compatibility of FreeMarker distribution
with JDK 1.2.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2_1">
<title>2.2.1</title>
<para>Date of release: 2003-04-11</para>
<para>This version introduces important new features, such as the
native FTL date/time type, and the auto-include and auto-import
settings.</para>
<para>The date/time support is experimental, but we hope it will not
substantially change. We would like to label it as final ASAP, so we
urge everybody to send feedback on this topic to the mailing
lists.</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>New scalar type: date. For more information read: <xref
linkend="dgui_datamodel_scalar" />, <xref
linkend="dgui_datamodel_scalar" />, <link
linkend="dgui_template_valueinserion_universal_date">interpolation</link>,
<link linkend="ref_builtin_string_for_date">?string built-in for
dates</link></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>New <literal>TemplateModel</literal> subinterface:
<literal>TemplateDateModel</literal>. For more information read
<xref linkend="pgui_datamodel_scalar" /></para>
</listitem>
<listitem>
<para>auto-include and auto-import: With these new configuration
level settings, you can include and import commonly used
templates (usually collection of macro definitions) at the top
of all templates, without actually typing <literal><#include
<replaceable>...</replaceable>></literal> or
<literal><#import
<replaceable>...</replaceable>></literal> into the templates
again and again. For more information please read the Java API
documentation of <literal>Configuration</literal></para>
</listitem>
<listitem>
<para>New template method:
<literal>createProcessingEnvironment</literal>. This method
makes it possible for you to do some special initialization on
the <link
linkend="gloss.environment"><literal>Environment</literal></link>
before template processing, or to read the environment after
template processing. For more information please read the Java
API documentation.</para>
</listitem>
<listitem>
<para>Changes to <literal>freemarker.ext.beans</literal>
package: <literal>BeanModel</literal>,
<literal>MapModel</literal>, and
<literal>ResourceModel</literal> now implement
<literal>TemplateHashModelEx</literal>.</para>
</listitem>
<listitem>
<para>Bugfix:
<literal>Configurable.setSettings(Properties)</literal> didn't
removed redundant spaces/tabs at the end of property
values.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_2">
<title>2.2</title>
<para>Date of release: 2003-03-27</para>
<para>This release introduces some really important new features.
Unfortunately, evolution was painful again; we have a few non-backward
compatible changes (see below). Also, for those of you awaiting
desired native date/time type, sorry, it is still not here (because of
some internal chaos in the team... stand by, it's coming).</para>
<section>
<title>Non backward-compatible changes!</title>
<itemizedlist>
<listitem>
<para>Macros are now plain variables. This means that if you are
unlucky and you have both a macro and another variable with the
same name, now the variable will overwrite the macro, so your
old template will malfunction. If you have a collection of
common macros, you should use the new <link
linkend="dgui_misc_namespace">namespace feature</link> to
prevent accidental clashes with the variables used in the
templates.</para>
</listitem>
<listitem>
<para>With the introduction of the new <link
linkend="dgui_misc_namespace">namespace support</link>,
<literal>global</literal> and <literal>assign</literal>
directives are no longer synonyms. <literal>assign</literal>
creates a variable in the current <literal>namespace</literal>,
while <literal>global</literal> creates variable that is visible
from all namespaces (as if the variable would be in the
data-model). Thus, the variable created with
<literal>assign</literal> is more specific, and hides the
variable of the same name created with
<literal>global</literal>. As a result, if you use both
<literal>global</literal> and <literal>assign</literal> mixed
for the same variable in your templates, now they will
malfunction. The solution is to search-and-replace all
<literal>global</literal>s in your old templates with
<literal>assign</literal>.</para>
</listitem>
<listitem>
<para>The reserved hash <literal>root</literal> no longer exists
as a predefined variable (we no longer have reserved variables).
Use <link linkend="dgui_template_exp_var_special">special
variable expressions</link> to achieve similar effects. However,
we have no equivalent replacement for <literal>root</literal>
because of the changes in the variable scopes caused by the
introduction of namespaces. You may should use
<literal>.globals</literal> or
<literal>.namespace</literal>.</para>
</listitem>
<listitem>
<para>The <literal>BeansWrapper</literal> no longer exposes
native Java arrays, booleans, numbers, enumerations, iterators,
and resource bundles as <literal>TemplateScalarModel</literal>.
This way, number objects wrapped through
<literal>BeansWrapper</literal> are subject to FreeMarker's
number formatting machinery. Also, booleans can be formatted
using the <literal>?string</literal> built-in.</para>
</listitem>
<listitem>
<para>The signature of
<literal>Configuration.setServletContextForTemplateLoading</literal>
has been changed: the first parameter is now
<literal>Object</literal> instead of
<literal>javax.servlet.ServletContext</literal>. Thus, you have
to recompile your classes that call this method. The change was
required to prevent class-loading failure when
<literal>javax.servlet</literal> classes are not available and
you would not call this method.</para>
</listitem>
<listitem>
<para>This release introduces a <link
linkend="dgui_misc_whitespace">parse-time white-space
remover</link> that strips some of the typical superfluous
white-space around FreeMarker tags and comments. <emphasis>This
feature is on by default!</emphasis> Most probably this will not
cause problems if you generate white-space neutral output like
HTML. But if it does cause undesirable reformatting in output
you generate, you can disable it with
<literal>config.setWhitespaceStripping(false)</literal>. Also,
you can enable/disable it on a per-template basis with the new
<link linkend="ref.directive.ftl"><literal>ftl</literal></link>
directive.</para>
</listitem>
<listitem>
<para>Some new directives were introduced:
<literal>nested</literal>, <literal>import</literal>,
<literal>escape</literal>, <literal>noescape</literal>,
<literal>t</literal>, <literal>rt</literal>,
<literal>lt</literal>. This means that if you are unlucky and
the text of your template contains something like
<literal><nested></literal>, then that will be
misinterpreted as a directive. To prevent this kind of problem
in the future, we recommend everybody to switch from the old
syntax to the new syntax (``strict syntax''). The strict syntax
will be the the default syntax starting from some of the later
releases anyway. We plan to release a conversion tool for
converting old templates. For more information please read:
<xref linkend="ref_depr_oldsyntax" /></para>
</listitem>
<listitem>
<para>The data-model created by the
<literal>FreemarkerServlet</literal> now uses automatic scope
discovery, so writing
<literal>Application.<replaceable>attrName</replaceable></literal>,
<literal>Session.<replaceable>attrName</replaceable></literal>,
<literal>Request.<replaceable>attrName</replaceable></literal>
is no longer mandatory; it's enough to write
<literal><replaceable>attrName</replaceable></literal> (for more
information <link linkend="topic.servlet.scopeAttr">read
this</link>). This may break an old template if that rely on the
non-existence of certain top-level variables.</para>
</listitem>
<listitem>
<para><literal>FreemarkerServlet</literal> now uses the encoding
of the template file for the output, unless you specify the
encoding in the <literal>ContentType</literal> init-param, such
as <literal>text/html; charset=UTF-8</literal>.</para>
</listitem>
<listitem>
<para>The format of template paths is now more restricted than
before. The path must not use <literal>/</literal>,
<literal>./</literal> and <literal>../</literal> and
<literal>://</literal> with other meaning as they have in URL
paths (or in UN*X paths). The characters <literal>*</literal>
and <literal>?</literal> are reserved. Also, the template loader
must not want paths starting with <literal>/</literal>. For more
information please read: <xref
linkend="pgui_config_templateloading" /></para>
</listitem>
<listitem>
<para>Till now
<literal>TemplateTransformModel.getWriter</literal> has received
null as parameter map if the transform was called without
parameters. From now, it will receive an empty Map instead. Note
that the previous API documentation didn't state that it always
receives null if there are no parameters, so hopelessly only
very few classes exploit this design mistake.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes in FTL (FreeMarker Template Language)</title>
<itemizedlist>
<listitem>
<para>User-defined directives: Transform and macro call syntax
has been unified; they can be called in the same way, as
user-defined directives. This also means that macros support
named parameters and nested content (like the -- now deprecated
-- <literal>transform</literal> directive did). For example, if
you have a macro called <literal>sect</literal>, you may call it
via <literal><@sect title="Blah" style="modern">Blah
blah...</@sect></literal>. For more information read:
<xref linkend="dgui_misc_userdefdir" /></para>
</listitem>
<listitem>
<para>Macros are now plain variables. This significantly
simplifies FreeMarker semantics, while providing more
flexibility; for example you can pass macros as parameters to
other macros and transforms. As for the problem of clashing
commonly-used-macro and variable names, we provide a more
powerful solution: namespaces.</para>
</listitem>
<listitem>
<para>Namespaces: Names-spaces are invaluable if you want to
assemble collections (``libraries'') of macros and transforms
(and other variables), and then use them in any template without
worrying about accidental name clashes with the application
specific and temporary variables, or with the variables of other
collections you want to use in the same template. This is
extremely important if FreeMarker users want to share their
macro/transform collections. For more information read: <xref
linkend="dgui_misc_namespace" /></para>
</listitem>
<listitem>
<para>With the introduction of namespaces our variable related
terminology changed. As a result, <literal>assign</literal> is
no longer synonymous with <literal>global</literal>. The
<literal>assign</literal> directive has been undeprecated, and
should be used instead of <literal>global</literal> almost
everywhere. In the new approach <literal>assign</literal>
creates variables in the current namespace, while
<literal>global</literal> creates a variable that is visible
from all namespaces (as if the variable were in the root of the
data-model). A variable created with <literal>assign</literal>
in the current namespace hides the variable of the same name
that was created with <literal>global</literal>.</para>
</listitem>
<listitem>
<para><literal>ftl</literal> directive: With this directive you
can give information about the template for FreeMarker, like the
encoding (charset) of the template, the used FTL syntax variant,
etc. Also, this directive helps you to write templates that are
less dependent on FreeMarker configuration settings, also it
helps third-party tools to identify and correctly parse
FreeMarker templates. For more information see: <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link></para>
</listitem>
<listitem>
<para>White-space stripping: FreeMarker now automatically
removes some of the typical superfluous white-spaces around
FreeMarker tags and comments, like the indentation spaces
before- and line-break after <literal><#if ...></literal>
tags. For more information read: <xref
linkend="dgui_misc_whitespace_stripping" /></para>
</listitem>
<listitem>
<para>New directive to apply a common ("escaping") expression to
all interpolations in a block: <link
linkend="ref.directive.escape"><literal>escape</literal></link>.
The name comes from the common usage of this directive for
automatic HTML-escaping of interpolations.</para>
</listitem>
<listitem>
<para>The new and preferred way of number formatting with
<literal>string</literal> built-in is
<literal>foo?string(format)</literal>, instead of the less
natural <literal>foo?string[format]</literal>.</para>
</listitem>
<listitem>
<para>The <literal>string</literal> built-in works for boolean
values. For example: <literal>${spamFilter?string("enabled",
"disabled")}</literal>. For more information <link
linkend="ref_builtin_string_for_boolean">read the
reference</link>.</para>
</listitem>
<listitem>
<para>The default strings for outputting boolean value using the
<literal>string</literal> built-in can be set using the
<literal>boolean_format</literal> setting.</para>
</listitem>
<listitem>
<para>Comments can be placed inside FTL tags and interpolations.
For example: <literal><#assign <#-- a comment --> x =
3></literal></para>
</listitem>
<listitem>
<para>All letters and numbers are enabled in variable names,
also <literal>$</literal> is allowed (as in Java programming
language). Thus you can use accents, Arabic letters, Chinese
letters, etc.</para>
</listitem>
<listitem>
<para>String literals can be quoted with apostrophe-quote.
<literal>"foo"</literal> and <literal>'foo'</literal> are
equivalent.</para>
</listitem>
<listitem>
<para>New <link linkend="ref_builtins_string">string
built-ins</link>: <literal>index_of</literal>,
<literal>last_index_of</literal>,
<literal>starts_with</literal>, <literal>ends_with</literal>,
<literal>replace</literal>, <literal>split</literal>,
<literal>chop_linebreak</literal>,
<literal>uncap_first</literal>.</para>
</listitem>
<listitem>
<para>New <link linkend="ref_builtins_sequence">sequence
built-ins</link>: <literal>sort</literal>,
<literal>sort_by</literal>.</para>
</listitem>
<listitem>
<para>New built-ins for experts to check the type of a variable.
See: <link
linkend="ref_builtin_isType"><literal>is_<replaceable>...</replaceable></literal>
built-ins</link></para>
</listitem>
<listitem>
<para>New built-in for experts to create a variable of certain
Java <literal>TemplateModel</literal> implementation. See: <link
linkend="ref_builtin_new"><literal>new</literal>
built-in</link></para>
</listitem>
<listitem>
<para>New built-in, <link
linkend="ref_builtin_namespace"><literal>namespace</literal></link>,
to get the namespace of a macro.</para>
</listitem>
<listitem>
<para>New expression type: special variable expression. To
prevent backward compatibility problems when we introduce new
predefined variables, from now <link
linkend="dgui_template_exp_var_special">special variable
expressions</link> are used to access them.</para>
</listitem>
<listitem>
<para>New directives: <literal>t</literal>,
<literal>rt</literal> and <literal>lt</literal> directives allow
you to do explicit white-space removal in extreme FTL
applications. For more information read <link
linkend="ref.directive.t">the reference</link>.</para>
</listitem>
<listitem>
<para><literal>assign</literal>, <literal>local</literal> and
<literal>global</literal> now can capture the output generated
be the nested template fragment into the variable. This
deprecates <literal>capture_output</literal> transform. More
information: <link linkend="ref.directive.assign">assign
directive reference</link></para>
</listitem>
<listitem>
<para>Bulk assignments (as <literal><#assign x=1, y=2,
z=3></literal>) no longer need colon to separate the
assignments (as <literal><#assign x=1 y=2 z=3></literal>),
although it is still allowed to preserve backward
compatibility.</para>
</listitem>
<listitem>
<para>Path that contains <literal>//:</literal> is considered as
absolute path.</para>
</listitem>
<listitem>
<para><literal>include</literal> and
<literal>transform</literal> directives no longer need a
semicolon to separate the template or transform name from the
parameter list, although it is still allowed to preserve
backward compatibility.</para>
</listitem>
<listitem>
<para><literal>#</literal>-less tag syntax is deprecated (but
still working). That is, you should write
<literal><#<replaceable>directive
...</replaceable>></literal> instead of
<literal><<replaceable>directive
...</replaceable>></literal>, and
<literal></#<replaceable>directive
...</replaceable>></literal> instead of
<literal></<replaceable>directive
...</replaceable>></literal>. For more info read: <xref
linkend="ref_depr_oldsyntax" /></para>
</listitem>
<listitem>
<para><literal>foreach</literal> is depreciated (but still
working). Use <link
linkend="ref.directive.list"><literal>list</literal></link>
instead.</para>
</listitem>
<listitem>
<para>Bugfix: Undefined variables in hash and sequence
constructors (as <literal>[a, b, c]</literal>) didn't caused
errors.</para>
</listitem>
<listitem>
<para>Bugfix: String concatenation had performance problem if
there was multiple concatenations chained, as:
<literal>"a"+x+"a"+x+"a"+x+"a"+x+"a"+x</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Arbitrary JSP custom tags can be used as FreeMarker
transforms in <literal>FreemarkerServlet</literal>-driven
templates. More information: <xref
linkend="pgui_misc_servlet" /></para>
</listitem>
<listitem>
<para>Various improvements for
<literal>BeansWrapper</literal>:</para>
<itemizedlist>
<listitem>
<para>The <literal>BeansWrapper</literal> no longer exposes
arbitrary objects as
<literal>TemplateScalarModel</literal>s, only
<literal>java.lang.String</literal> and
<literal>Character</literal> objects. This way, number
objects wrapped through <literal>BeansWrapper</literal> are
subject to FreeMarker's number formatting machinery. As a
side effect, non-string and non-number objects that were
previously accepted in equality and inequality operations
(because they had a string representation) will now cause
the engine to throw exception on comparison attempt.</para>
</listitem>
<listitem>
<para><literal>java.lang.Character</literal> objects are
exposed as scalars through
<literal>BeansWrapper</literal>.</para>
</listitem>
<listitem>
<para>Experimental feature: With the
<literal>setSimpleMapWrapper</literal> method of
<literal>BeansWrapper</literal> you can configure it to wrap
<literal>java.util.Map</literal>-s as
<literal>TemplateHashModelEx</literal>-s, and do not expose
the methods of the object.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>TransformControl</literal> interface (was
experimental earlier): If the <literal>Writer</literal> returned
by <literal>TemplateTransformModel.getWriter</literal>
implements this interface, it can instruct the engine to skip or
to repeat evaluation of the nested content, and gets notified
about exceptions that are thrown during the nested content
evaluation. Note that the <literal>onStart</literal> and
<literal>afterBody</literal> methods now are allowed to throw
<literal>IOException</literal>. For more information please read
the API documentation.</para>
</listitem>
<listitem>
<para>Localized lookup can be disabled with the new
<literal>Configuration</literal> methods:
<literal>set/getLocalizedLookup</literal>,
<literal>clearTemplateCache</literal></para>
</listitem>
<listitem>
<para>The new interface
<literal>freemarker.cache.CacheStorage</literal> allows users to
plug custom template caching strategies with the
<literal>cache_storage</literal> setting. The core package now
ships with two implementations:
<literal>SoftCacheStorage</literal> and
<literal>StrongCacheStorage</literal>. For more information
read: <xref linkend="pgui_config_templateloading" /></para>
</listitem>
<listitem>
<para>You can set settings with string name and string value
with the new <literal>setSetting(String key, String
value)</literal> method of <literal>Configurable</literal>
super-classes (as <literal>Configuration</literal>). Also you
can load settings from <literal>.properties</literal> file with
the <literal>setSettings</literal> method.</para>
</listitem>
<listitem>
<para>Other new <literal>Configuration</literal> methods:
<literal>clearTemplateCache</literal>,
<literal>clearSharedVariables</literal>,
<literal>getTemplateLoader</literal>, and
<literal>clone</literal>.</para>
</listitem>
<listitem>
<para>Changes to <literal>TemplateTransformModel</literal>
interface: <literal>getWriter</literal> can throw
<literal>IOException</literal>, and can return
<literal>null</literal> if the transform does not support body
content.</para>
</listitem>
<listitem>
<para>Till now
<literal>TemplateTransformModel.getWriter</literal> has received
null as parameter map if the transform was called without
parameters. From now, it will receive an empty Map instead. Note
that the previous API documentation didn't state that it always
receives null if there are no parameters, so hopelessly only
very few classes exploit this design mistake.</para>
</listitem>
<listitem>
<para>Various improvements for
<literal>FreemarkerServlet</literal>:</para>
<itemizedlist>
<listitem>
<para>The data-model now uses automatic scope discovery, so
writing
<literal>Application.<replaceable>attrName</replaceable></literal>,
<literal>Session.<replaceable>attrName</replaceable></literal>,
<literal>Request.<replaceable>attrName</replaceable></literal>
is no longer mandatory; it's enough to write
<literal><replaceable>attrName</replaceable></literal>. For
more information <link
linkend="topic.servlet.scopeAttr">read this</link>.</para>
</listitem>
<listitem>
<para><literal>FreemarkerServlet</literal> now uses the
encoding of the template file for the output, unless you
specify the encoding in the <literal>ContentType</literal>
init-param, such as <literal>text/html;
charset=UTF-8</literal>.</para>
</listitem>
<listitem>
<para>All <literal>Configuration</literal> level settings
can by set with Servlet init-params
(<literal>template_exception_handler</literal>,
<literal>locale</literal>, <literal>number_format</literal>,
etc.).</para>
</listitem>
<listitem>
<para>The object wrapper the servlet internally uses is now
set as the default object wrapper for its
<literal>Configuration</literal> instance.</para>
</listitem>
<listitem>
<para>It no longer forces session creation for requests that
don't belong to an existing session, improving
scalability.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>JDOM independent XML-wrapping:
<literal>freemarker.ext.xml.NodeListModel</literal> is a
re-implementation of
<literal>freemarker.ext.jdom.NodeListModel</literal> that does
not rely on JDOM; you don't need JDOM .jar anymore. The new
<literal>NodeListModel</literal> automatically uses W3C DOM,
dom4j, or JDOM, depending on which library is available (that
is, depending on what object do you pass to its
constructor).</para>
</listitem>
<listitem>
<para>Bugfix: <literal>WebappTemplateLoader</literal>: Template
updating didn't worked correctly with Tomcat due the caching of
resources. Now <literal>WebappTemplateLoader</literal> tries to
access the resources directly as <literal>File</literal>, if it
is possible, thus bypasses the caching.</para>
</listitem>
<listitem>
<para>Various bug-fixes for
<literal>FreemarkerServlet</literal>:</para>
<itemizedlist>
<listitem>
<para>The servlet now loads the correct template if it was
called through
<literal>RequestDispatcher.include</literal>.</para>
</listitem>
<listitem>
<para>The caching of <literal>HttpServletRequest</literal>
objects is now compliant with the servlet
specification.</para>
</listitem>
<listitem>
<para><literal>TemplateException</literal>s was suppressed
in certain situations resulting in half-rendered pages
without error message.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Bugfix: FreeMarker didn't work if the
<literal>javax.servlet</literal> classes was not available,
because <literal>Configuration</literal> explicitly referred to
<literal>javax.servlet.ServletContext</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: classes may were not found if they was available
only in the <literal>WEB-INF</literal>, and FreeMarker tried to
load the class dynamically.</para>
</listitem>
<listitem>
<para>Bugfix: the <literal>Template</literal> constructor (and
thus <literal>Configuration.getTemplate</literal>) sometimes
threw <literal>TokenMgrError</literal> (a non-checked exception)
instead of <literal>ParseException</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>The Web application related examples has been
replaced.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>The history of the releases before the final version</title>
<section>
<title>Differences between the final and RC2 releases</title>
<itemizedlist>
<listitem>
<para>You can load settings from
<literal>.properties</literal> file with the
<literal>setSettings</literal> method of
<literal>Configuration</literal> and other
<literal>Configurable</literal> subclasses.</para>
</listitem>
<listitem>
<para>New string built-in:
<literal>uncap_first</literal></para>
</listitem>
<listitem>
<para>Bugfix: When exposing an XML document to a template and
accessing it with XPath using Jaxen a
<literal>ClassCastException</literal> has occurred.</para>
</listitem>
<listitem>
<para>Bugfix: The template cache has loaded templates with bad
<literal>Configuration</literal> instance in certain
situations if you use not the static default
<literal>Configuration</literal> instance.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the RC2 and RC1 releases</title>
<itemizedlist>
<listitem>
<para>Non backward compatible change!:
<literal>FreemarkerServlet</literal> now uses the encoding of
the template file for the output, unless you specify the
encoding in the <literal>ContentType</literal> init-param,
such as <literal>text/html; charset=UTF-8</literal>.</para>
</listitem>
<listitem>
<para>Non backward compatible change compared to RC1!: The
<literal>capture_output</literal> transform creates variable
in the current namespace (as <literal>assign</literal>
directive) with the <literal>var</literal> parameter, not a
global variable.</para>
</listitem>
<listitem>
<para>The new and preferred way of number formatting with
<literal>string</literal> built-in is
<literal>foo?string(format)</literal>, instead of the less
natural <literal>foo?string[format]</literal>.</para>
</listitem>
<listitem>
<para>The <literal>string</literal> built-in works for boolean
values. For example: <literal>${spamFilter?string("enabled",
"disabled")}</literal>. For more information <link
linkend="ref_builtin_string_for_boolean">read the
reference</link>.</para>
</listitem>
<listitem>
<para>The default strings for outputting boolean value using
the <literal>string</literal> built-in can be set using the
<literal>boolean_format</literal> setting.</para>
</listitem>
<listitem>
<para>String literals can be quoted with apostrophe-quote.
<literal>"foo"</literal> and <literal>'foo'</literal> are
equivalent.</para>
</listitem>
<listitem>
<para>The new interface
<literal>freemarker.cache.CacheStorage</literal> allows users
to plug custom template caching strategies with the
<literal>cache_storage</literal> setting. The core package now
ships with two implementations:
<literal>SoftCacheStorage</literal> and
<literal>StrongCacheStorage</literal>. For more information
read: <xref linkend="pgui_config_templateloading" /></para>
</listitem>
<listitem>
<para>You can set settings with string name and string value
with the new <literal>setSetting(String key, String
value)</literal> method of <literal>Configurable</literal>
super-classes (as <literal>Configuration</literal>).</para>
</listitem>
<listitem>
<para>Other new <literal>Configuration</literal> methods:
<literal>getTemplateLoader</literal>,
<literal>clone</literal>.</para>
</listitem>
<listitem>
<para><literal>assign</literal>, <literal>local</literal> and
<literal>global</literal> now can capture the output generated
be the nested template fragment into the variable. This
deprecates <literal>capture_output</literal> transform. More
information: <link linkend="ref.directive.assign">assign
directive reference</link></para>
</listitem>
<listitem>
<para>Other new <literal>Configuration</literal> methods:
<literal>getTemplateLoader</literal>,
<literal>clone</literal>.</para>
</listitem>
<listitem>
<para>Changes to <literal>TemplateTransformModel</literal>
interface: <literal>getWriter</literal> can throw
<literal>IOException</literal>, and can return
<literal>null</literal> if the transform does not support body
content.</para>
</listitem>
<listitem>
<para>Till now
<literal>TemplateTransformModel.getWriter</literal> has
received null as parameter map if the transform was called
without parameters. From now, it will receive an empty Map
instead. Note that the previous API documentation didn't state
that it always receives null if there are no parameters, so
hopelessly only very few classes exploit this design
mistake.</para>
</listitem>
<listitem>
<para>Changes to <literal>TemplateControl</literal> interface:
<literal>onStart</literal> and <literal>afterBody</literal>
methods are now allowed to throw
<literal>IOException</literal>.</para>
</listitem>
<listitem>
<para>Path that contains <literal>//:</literal> is considered
as absolute path.</para>
</listitem>
<listitem>
<para>New <link linkend="ref_builtins_string">string
built-ins</link>: <literal>index_of</literal>,
<literal>last_index_of</literal>,
<literal>starts_with</literal>, <literal>ends_with</literal>,
<literal>replace</literal>, <literal>split</literal>,
<literal>chop_linebreak</literal>.</para>
</listitem>
<listitem>
<para>New <link linkend="ref_builtins_sequence">sequence
built-ins</link>: <literal>sort</literal>,
<literal>sort_by</literal>.</para>
</listitem>
<listitem>
<para>All <literal>Configuration</literal> level settings can
by set with Servlet init-params
(<literal>template_exception_handler</literal>,
<literal>locale</literal>, <literal>number_format</literal>,
etc.).</para>
</listitem>
<listitem>
<para>Bugfix: classes may were not found if they was available
only in the <literal>WEB-INF</literal>, and FreeMarker tried
to load the class dynamically.</para>
</listitem>
<listitem>
<para>Bugfix: <literal>setLocalizedLookup(false)</literal> of
<literal>Configuration</literal> was overridden when you have
called <literal>setTemplateLoader</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: String concatenation had performance problem if
there was multiple concatenations chained, as:
<literal>"a"+x+"a"+x+"a"+x+"a"+x+"a"+x</literal>.</para>
</listitem>
<listitem>
<para>Bugfix: white-space stripping was not worked with tags
spanning over multiple lines.</para>
</listitem>
<listitem>
<para>Bugfix: Removing several dependencies on JDK 1.3, so
FreeMarker can be build for JDK 1.2.2.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 2 and RC1 releases</title>
<itemizedlist>
<listitem>
<para><literal>ftl</literal> is now stricter, and does not
allow custom parameters. To associate custom attributes to
templates, we may add a new directive later, if there is a
demand for it.</para>
</listitem>
<listitem>
<para><literal>escape</literal> directive does not affect
numerical interpolations
(<literal>#{<replaceable>...</replaceable>}</literal>)
anymore, as it has caused errors with string escapes as
<literal>?html</literal>.</para>
</listitem>
<listitem>
<para>The <literal>normalizeName</literal> method of
<literal>freemarker.cache.TemplateLoader</literal> has been
removed, because it has caused too many complications.
Instead, normalization happens on a single point in the
<literal>TempateCache</literal>. In consequence, FreeMarker is
now stricter about the format of template paths, as things
like <literal>/../</literal> are interpreted by the
core.</para>
</listitem>
<listitem>
<para>Experimental feature: With the
<literal>setSimpleMapWrapper</literal> method of
<literal>BeansWrapper</literal> you can configure it to wrap
<literal>java.util.Map</literal>-s as
<literal>TemplateHashModelEx</literal>-s, and do not expose
the methods of the object.</para>
</listitem>
<listitem>
<para>New <literal>Configuration</literal> methods:
<literal>set/getLocalizedLookup</literal>,
<literal>clearTemplateCache</literal>,
<literal>clearSharedVariables</literal>.</para>
</listitem>
<listitem>
<para>More cleanups in the <literal>Environment</literal>
API.</para>
</listitem>
<listitem>
<para>Better JSP standard compliance: JSP page-scope variables
are the global variables that were created in the template
(not the variables of the data-model).</para>
</listitem>
<listitem>
<para>JDOM independent XML-wrapping:
<literal>freemarker.ext.xml.NodeListModel</literal> is a
re-implementation of
<literal>freemarker.ext.jdom.NodeListModel</literal> that does
not rely on JDOM; you don't need JDOM .jar anymore. The new
<literal>NodeListModel</literal> automatically uses W3C DOM,
dom4j, or JDOM, depending on which library is available (that
is, depending on what object do you pass to its
constructor).</para>
</listitem>
<listitem>
<para>Bugfix: <literal>WebappTemplateLoader</literal>:
Template updating didn't worked correctly with Tomcat due the
caching of resources. Now
<literal>WebappTemplateLoader</literal> tries to access the
resources directly as <literal>File</literal>, if it is
possible, thus bypasses the caching.</para>
</listitem>
<listitem>
<para>Bugfix: Templates loaded with
<literal>MultiTemplateLoader</literal> subclasses was removed
from the template cache after the template update delay has
elapsed (5 seconds by default) even if the template file was
unchanged. This can cause lot of extra load for a high-traffic
server if you have many templates or if the template update
delay was set to 0 second.</para>
</listitem>
<listitem>
<para>Bugfix: Undefined variables in hash and sequence
constructors (as <literal>[a, b, c]</literal>) didn't caused
errors.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the Preview 1 and Preview 2
releases</title>
<itemizedlist>
<listitem>
<para>All 16-bit Unicode letters and numbers are allowed in
identifiers, as well as the <literal>$</literal> character (as
in Java programming language). Thus you can use accented
letters, Arabic letters, Chinese letters, etc. as identifiers
in templates</para>
</listitem>
<listitem>
<para>Macros now can create loop variables for the nested
content. For more information <link
linkend="dgui_misc_userdefdir_loopvar">read
this</link>.</para>
</listitem>
<listitem>
<para>New directives: <literal>t</literal>,
<literal>rt</literal> and <literal>lt</literal> directives
allow you to do explicit white-space removal in extreme FTL
applications. For more information read <link
linkend="ref.directive.t">the reference</link>.</para>
</listitem>
<listitem>
<para>The syntax of assignment-with-namespace has changed from
<literal><#assign foo=123 namespace=myLib></literal>) to
<literal><#assign foo=123 in myLib></literal>, since the
previous syntax was confusing because its similarity to a
bulk-assignment.</para>
</listitem>
<listitem>
<para>Bulk assignments (as <literal><#assign x=1, y=2,
z=3></literal>) no longer need colon to separate the
assignments (as <literal><#assign x=1 y=2
z=3></literal>), although it is still allowed to preserve
backward compatibility.</para>
</listitem>
<listitem>
<para>Positional parameter passing is supported for macro
calls as shorthand form of normal named parameter passing. For
more details read <link
linkend="ref_directive_userDefined_positionalParam">read the
reference</link>.</para>
</listitem>
<listitem>
<para>New built-in, <literal>namespace</literal>, to get the
namespace of the currently executing macro.</para>
</listitem>
<listitem>
<para><literal>TransformControl</literal> interface (was
experimental earlier): If the <literal>Writer</literal>
returned by
<literal>TemplateTransformModel.getWriter</literal> implements
this interface, it can instruct the engine to skip or to
repeat evaluation of the nested content, and gets notified
about exceptions that are thrown during the nested content
evaluation. For more information please read the API
documentation.</para>
</listitem>
<listitem>
<para>Jython wrapper can now wrap arbitrary Java objects, not
only <literal>PyObject</literal>-s. If an object is passed to
the wrapper that is neither a
<literal>TemplateModel</literal>, nor a
<literal>PyObject</literal>, it is first coerced into a
<literal>PyObject</literal> using Jython's own wrapping
machinery, and then wrapped into a
<literal>TemplateModel</literal> as any other
<literal>PyObject</literal>.</para>
</listitem>
<listitem>
<para>Some cleanups in the <literal>Environment</literal>
API.</para>
</listitem>
<listitem>
<para>The Web application related examples has been
replaced.</para>
</listitem>
<listitem>
<para>Bugfix: Templates loaded with
<literal>URLTemplateLoader</literal> subclasses was removed
from the template cache after the template update delay has
elapsed (5 seconds by default) even if the template file was
unchanged. This can cause lot of extra load for a high-traffic
server if you have many templates or if the template update
delay was set to 0 second.</para>
</listitem>
<listitem>
<para>Bugfix: <literal>FreeMarkerServlet</literal> has thrown
<literal>ServletException</literal> even if a debug
<literal>TemplateException</literal> handler was in use (so
you may got Error 500 page instead of debug
information).</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
<section xml:id="versions_2_1_5">
<title>2.1.5</title>
<para>Date of release: 2003-02-08</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: Fixed a bug that forced the cache to frequently
reload templates accessed through URL and multi template
loaders: Templates loaded with
<literal>URLTemplateLoader</literal> subclasses and
<literal>MultiTemplateLoader</literal> was removed from the
template cache after the template update delay has elapsed (5
seconds by default) even if the template file was unchanged.
This can cause lot of extra load for a high-traffic server if
you have many templates or if the template update delay was set
to 0 second.)</para>
</listitem>
<listitem>
<para>Bugfix: Many anomalies in the
<literal>JythonWrapper</literal> were resolved, making the
integration with Jython much smoother: Jython wrapper can now
wrap arbitrary Java objects, not only
<literal>PyObject</literal>-s. If an object is passed to the
wrapper that is neither a <literal>TemplateModel</literal>, nor
a <literal>PyObject</literal>, it is first coerced into a
<literal>PyObject</literal> using Jython's own wrapping
machinery, and then wrapped into a
<literal>TemplateModel</literal> as any other
<literal>PyObject</literal>.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_1_4">
<title>2.1.4</title>
<para>Date of release: 2002-12-26</para>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: Log4J is now found when automatically discovering
the logging library to use.</para>
</listitem>
<listitem>
<para>Bugfix: An exception is no longer thrown in the static
initializer of the <literal>Configuration</literal> if the
directory specified in the <literal>"user.dir"</literal> system
property is not readable.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_1_3">
<title>2.1.3</title>
<para>Date of release: 2002-12-09</para>
<section>
<title>Changes on the FTL side</title>
<itemizedlist>
<listitem>
<para>Bugfix: <literal>cap_first</literal> built-in did what
<literal>double</literal> built-in does.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>The official extension of FreeMarker template files is
<literal>ftl</literal> from now, not <literal>fm</literal>.
(This is the name of the template language; FTL, for FreeMarker
Template Language.) Of course you can use any extensions, since
FreeMarker does not deal with the file extension. But we
recommend <literal>ftl</literal> extension as default.</para>
</listitem>
<listitem>
<para>Web application examples got tweaked again, as under JDK
1.4 a class in an explicit (named) package can no longer import
classes from the default (unnamed) package. Our webapp example
was using classes in the default package, they are now moved
into named packages.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_1_2">
<title>2.1.2</title>
<para>Date of release: 2002-11-28</para>
<section>
<title>Changes in FTL (FreeMarker Template Language)</title>
<itemizedlist>
<listitem>
<para><literal>FreeMarkerServlet</literal> now has a setting for
the <literal>Content-Type</literal> header of the response,
defaulting to <literal>text/html</literal>. Previously it set no
content type, which made it not play nicely when integrated with
software that expected it (i.e. OpenSymphony SiteMesh).</para>
</listitem>
<listitem>
<para><literal>FreeMarkerServlet</literal> now works correctly
when mapped to an URL extension instead of URL path
prefix.</para>
</listitem>
<listitem>
<para>You can emulate <literal>include</literal> directive call
within Java code by calling
<literal>Environment.include(<replaceable>templateName</replaceable>,
<replaceable>charset</replaceable>,
<replaceable>parse</replaceable>)</literal>.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>Bugfix: When <literal>Template.process()</literal> was
called from another template processing, it set
<literal>currentEnvironment</literal> to null when it returned,
thus crashed the parent template processing.</para>
</listitem>
<listitem>
<para>Bugfix: the <literal>_descendant</literal> key in JDOM
support incorrectly left the document root element out of the
result when applied to a Document node.</para>
</listitem>
<listitem>
<para>Bugfix: because we incorrectly assumed certain behavior of
JDK 1.4 Beans introspector, calls to public interface methods on
non-public classes that implement the interface were causing
exceptions on JDK 1.4</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Various minor supplements to the manual.</para>
</listitem>
<listitem>
<para>Documentation HTML pages don't try to load the SourceForge
logo from the Internet anymore.</para>
</listitem>
<listitem>
<para>The default ant target is <literal>jar</literal>, not
<literal>dist</literal>.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_1_1">
<title>2.1.1</title>
<para>Date of release: 2002-11-04</para>
<section>
<title>Changes in FTL (FreeMarker Template Language)</title>
<itemizedlist>
<listitem>
<para>Multi-type variables that are both string and number or
string and date are now output using their number or date value
instead of the string value when used in the
<literal>${...}</literal> interpolation. This practically makes
the string part of a string/number or a string/date variables
useless.</para>
</listitem>
<listitem>
<para>Bugfix: operator ``or'' (<literal>||</literal>) worked
wrongly when its left operand was a composite expression (e.g.
the second <literal>||</literal> in <literal>false || true ||
false</literal>; this was evaluated to <literal>false</literal>,
but it should be <literal>true</literal>)</para>
</listitem>
<listitem>
<para>Bugfix: Less-than sign inside comments confused the FTL
parser (e.g. <literal><#-- blah < blah --></literal>);
it commented out everything after the problematic
comment.</para>
</listitem>
<listitem>
<para>Bugfix: Comparing two numerical constants (e.g. <literal>3
== 3</literal>) caused internal error in the FTL parser, and
aborted template processing with error.</para>
</listitem>
<listitem>
<para>Experimental date/time type support was removed, since it
seems that this initial implementation was misguided. FreeMarker
2.2 will certainly support data/time.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para>Bugfix: <literal>Number</literal>s wrapped with
<literal>BEANS_WRAPPER</literal> was displayed with the
<literal>toString()</literal> method of wrapped object. Now they
are rendered according to the <literal>number_format</literal>
setting, because multi-type variables that are both string and
number are now output using their number value instead of the
string value.</para>
</listitem>
<listitem>
<para>Experimental date/time type support was removed, since it
seems that this initial implementation was misguided. FreeMarker
2.2 will certainly support data/time.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_1">
<title>2.1</title>
<para>Date of release: 2002-10-17</para>
<para>Templates and the Java API are <emphasis>not</emphasis> fully
compatible with 2.0 releases. You will need to revisit existing code
and templates, or use 2.1 for new projects only. Sorry for this
inconvenience; FreeMarker has undergone some revolutionary changes
since the 1.x series. We hope things will soon be sufficiently mature
for us to offer (almost) backward-compatible releases. Note that there
is a backward-compatibility flag that can be set via
<literal>Configuration.setClassicCompatible(true)</literal> that
causes the new FreeMarker to emulate most of FreeMarker 1.x's
quirks.</para>
<section>
<title>Changes in FTL (FreeMarker Template Language)</title>
<itemizedlist>
<listitem>
<para>More strict, reveals accidental mistakes in the templates,
prevents showing incorrect information when something went
wrong:</para>
<itemizedlist>
<listitem>
<para>An attempt to access an undefined variable causes an
error and aborts template processing (by default at least;
see later). In earlier versions undefined variables were
silently treated as empty (zero-length) strings. However,
you can handle undefined variables in the template with some
new built-ins. For example,
<literal>${foo?if_exists}</literal> is equivalent with the
<literal>${foo}</literal> of earlier versions. Another way
of looking at this is that null values no longer exist from
the viewpoint of a template designer. Anything referenced
must be a defined variable.</para>
<para>Note however that the programmer can configure
FreeMarker so that it ignores certain errors (say, undefined
variables), and continues template processing by skipping
the problematic part. This ``loose'' policy should be used
only for sites that don't show critical information.</para>
</listitem>
<listitem>
<para>New variable type: <link
linkend="gloss.boolean">boolean</link>. Conditions in
<literal>if</literal>/<literal>elseif</literal> and operands
of logical operators (<literal>&&</literal>,
<literal>||</literal>, <literal>!</literal>) must be
booleans. Empty strings are no longer treated as a logical
false.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Local and global variables. More info: <xref
linkend="dgui_misc_var" /></para>
<itemizedlist>
<listitem>
<para>Local variables for macros. You can create/replace
local variables in macro definition bodies with the <link
linkend="ref.directive.local"><literal>local</literal>
directive</link></para>
</listitem>
<listitem>
<para>You can create/replace global (non-local) variables
with the <link
linkend="ref.directive.global"><literal>global</literal>
directive</link></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>The <link
linkend="ref.directive.include"><literal>include</literal></link>
directive now by default treats the passed filename as being
relative to the including template's path. To specify absolute
template paths, you now have to prepend them with a
slash.</para>
</listitem>
<listitem>
<para>The <link
linkend="ref.directive.include"><literal>include</literal></link>
directive can now use the <emphasis>acquisition
algorithm</emphasis> (familiar from the Zope system) to look up
the template to include. Basically, if a template is not found
where it is looked up first, it is looked up in parent
directories. This is however not a default behavior, rather it
is triggered by a new syntactic element.</para>
</listitem>
<listitem>
<para>Strict syntax mode: Allows you to generate arbitrary SGML
(XML) without worrying about clashes with FreeMarker directives.
For more information read: <xref
linkend="ref_depr_oldsyntax" /></para>
</listitem>
<listitem>
<para>Terse comments: you can use <literal><#--
<replaceable>...</replaceable> --></literal> instead of
<literal><comment><replaceable>...</replaceable></comment></literal></para>
</listitem>
<listitem>
<para>Directive that you can use to change the locale (and other
settings) inside the template: <link
linkend="ref.directive.setting"><literal>setting</literal></link></para>
</listitem>
<listitem>
<para>Directive to explicitly flush the output buffer: <link
linkend="ref.directive.flush"><literal>flush</literal></link></para>
</listitem>
<listitem>
<para>The top-level (root) hash is available via the variable
<literal>root</literal>, which is now a reserved name.</para>
</listitem>
<listitem>
<para>The misnamed <literal>function</literal> directive has
been renamed to <literal>macro</literal>.</para>
</listitem>
<listitem>
<para>String literals support various new <link
linkend="topic.escapeSequence">escape sequences</link>,
including UNICODE escapes
(<literal>\x<replaceable>CODE</replaceable></literal>)</para>
</listitem>
<listitem>
<para>The <link
linkend="ref.directive.compress"><literal>compress</literal></link>
directive is now more conservative in removing line
breaks.</para>
</listitem>
<listitem>
<para>Built-in to capitalize the first word: <link
linkend="ref_builtin_cap_first"><literal>cap_first</literal></link></para>
</listitem>
<listitem>
<para>Built-in to generate on-the-fly templates: <link
linkend="ref_builtin_interpret"><literal>interpret</literal></link></para>
</listitem>
<listitem>
<para><link
linkend="ref.directive.stop"><literal>stop</literal></link>
directive has an optional parameter to describe the reason of
termination</para>
</listitem>
<listitem>
<para>Better error messages.</para>
</listitem>
<listitem>
<para>New variable type: date. <emphasis>Date support is
experimental. It can change substantially in the future. Keep
this in mind if you use it.</emphasis></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes on the Java side</title>
<itemizedlist>
<listitem>
<para><literal>ObjectWrapper</literal>: You can put
non-<literal>TemplateModel</literal> objects directly into
hashes, sequences and collections, and they will be
automatically wrapped with the appropriate
<literal>TemplateModel</literal> implementation. The API of
objects that are exposed to templates
(<literal>Simple<replaceable>XXX</replaceable></literal>) has
been changed according to this, for example in
<literal>SimpleHash</literal> the old <literal>put(String key,
TemplateModel value)</literal> is now <literal>put(String key,
Object object)</literal>. Also, you can pass any kind of object
as data-model to <literal>Template.process</literal>. The
alternative reflection based <literal>ObjectWrapper</literal>
can expose the members of any Java object automatically for the
designer. More information: <link
linkend="pgui_datamodel_objectWrapper">Object wrapping</link>,
<link linkend="pgui_misc_beanwrapper">Bean wrapper</link>, <link
linkend="pgui_misc_jythonwrapper">Jython wrapper</link>.</para>
</listitem>
<listitem>
<para>The <literal>Configuration</literal> object was introduced
as a central point to hold all your FreeMarker-related global
settings, as well as commonly used variables that you want to
have available from any template. Also it encapsulates the
template cache and can be used to load templates. For more
information read <xref linkend="pgui_config" />.</para>
</listitem>
<listitem>
<para><literal>TemplateLoader</literal>: pluggable template
loader, separates caching from template loading</para>
</listitem>
<listitem>
<para><literal>TemplateNumberModel</literal>-s do not control
their formatting anymore. They just store the data (i.e. a
number). Number formatting is done by the FreeMarker core based
on the <literal>locale</literal> and
<literal>number_format</literal> settings. This logic applies to
the new experimental date type as well.</para>
</listitem>
<listitem>
<para><literal>TemplateBooleanModel</literal> introduced: Only
objects that implements this interface can be used as a boolean
in true/false conditions. More info: <xref
linkend="pgui_datamodel_scalar" /></para>
</listitem>
<listitem>
<para><literal>TemplateDateModel</literal> introduced: objects
that implements this interface are recognized as dates and can
be locale-sensitively formatted. <emphasis>Date support is
experimental in FreeMarker 2.1. It can change substantially in
the future. Keep this in mind if you use it.</emphasis></para>
</listitem>
<listitem>
<para>The <literal>TemplateModelRoot</literal> interface was
deprecated. As of FreeMarker 2.1, you can simply use any
instance of <literal>TemplateHashModel</literal> instead. This
actually is due to a significant architectural change. Variables
set or defined in a template are stored in a separate
<literal>Environment</literal> object that only exists while the
template is being rendered. Thus, the template doesn't modify
the root hash.</para>
</listitem>
<listitem>
<para>Changes to transformations</para>
<itemizedlist>
<listitem>
<para>Completely rewritten
<literal>TemplateTransformModel</literal> interface. More
flexible, and does not impose output holding. More
information: <xref
linkend="pgui_datamodel_directive" /></para>
</listitem>
<listitem>
<para>The <literal>transform</literal> directive now takes
an optional set of key/value pairs. <literal><transform
myTransform;
<replaceable>key1</replaceable>=<replaceable>value1</replaceable>,
<replaceable>key2</replaceable>=<replaceable>value2</replaceable>
<replaceable>...</replaceable>></literal>. More
information: <link
linkend="ref.directive.transform"><literal>transform</literal>
directive</link></para>
</listitem>
<listitem>
<para>The transforms that ship with the FreeMarker core are
now available by default to all templates - i.e.
<literal><transform html_escape></literal> will invoke
the
<literal>freemarker.template.utility.HtmlEscape</literal>
transform. More information: <xref
linkend="pgui_config_sharedvariables" /></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>User-defined <literal>TemplateModel</literal> objects now
can access the runtime environment (read and set variables, get
the current locale, etc.) using an
<literal>Environment</literal> instance, which can be obtained
by the static
<literal>Environment.getCurrentEnvironment()</literal> method.
As a result, <literal>TemplateScalarModel.getAsString</literal>
has been changed: it has no locale parameter.</para>
</listitem>
<listitem>
<para><literal>TemplateExceptionHandler</literal>-s make it
possible to define your own rules on what to do when a runtime
error occurs (e.g. accessing a non existing variable) during
template processing. For example, you can abort template
processing (recommended for most sites), or skip the problematic
statement and continue template processing (similar to old
behavior). DebugMode has been removed, use
<literal>TemplateExceptionHandler.DEBUG_HANDLER</literal> or
<literal>HTML_DEBUG_HANDLER</literal> instead.</para>
</listitem>
<listitem>
<para>Logging: FreeMarker logs certain events (runtime errors
for example). For more information read <xref
linkend="pgui_misc_logging" />.</para>
</listitem>
<listitem>
<para><literal>SimpleIterator</literal> was removed, but we
provide a <literal>TemplateCollectionModel</literal>
implementation: <literal>SimpleCollection</literal>.</para>
</listitem>
<listitem>
<para>Arithmetic engine is pluggable
(<literal>Configuration.setArithmeticEngine</literal>). The core
distribution comes with two engines:
<literal>ArithmeticEngine.BIGDECIMAL_ENGINE</literal> (the
default) that converts all numbers to
<literal>BigDecimal</literal> and then operates on them, and
<literal>ArithmeticEngine.CONSERVATIVE_ENGINE</literal> that
uses (more-or-less) the widening conversions of Java language,
instead of converting everything to
<literal>BigDecimal</literal>.</para>
</listitem>
<listitem>
<para>Changes to <literal>freemarker.ext.beans</literal>
package: The JavaBeans adapter layer has suffered several major
changes. First, <literal>BeansWrapper</literal> is no longer a
static utility class - you can now create instances of it, and
every instance can have its own instance caching policy and
security settings. These security settings are also new - you
can now create JavaBeans wrappers that hide methods that are
considered unsafe or inappropriate in a templating environment.
By default, you can no longer call methods like
<literal>System.exit()</literal> from the template (although you
can manually turn off these safeguards). The
<literal>StaticModel</literal> and
<literal>StaticModels</literal> classes are gone; their
functionality is now replaced with the
<literal>BeansWrapper.getStaticModels()</literal> method.</para>
</listitem>
<listitem>
<para><literal>freemarker.ext.jython</literal> package:
FreeMarker can now directly use Jython objects as data-models
using the <link linkend="pgui_misc_jythonwrapper">Jython
wrapper</link>.</para>
</listitem>
<listitem>
<para>Changes to <literal>freemarker.ext.jdom</literal> package:
The package now uses the <emphasis>Jaxen</emphasis> package
instead of its predecessor, the
<emphasis>werken.xpath</emphasis> package to evaluate XPath
expressions. Since <emphasis>Jaxen</emphasis> is a successor to
<emphasis>werken.xpath</emphasis>, this can be considered to be
an upgrade. As a consequence, namespace prefixes are now
recognized in XPath expressions and the overall XPath
conformance is better.</para>
</listitem>
<listitem>
<para>Better error reporting: If the processing of a template is
aborted by a <literal>TemplateException</literal> being thrown,
or using a <literal><#stop></literal> directive,
FreeMarker will now output an execution trace with line and
column numbers relative to the template source.</para>
</listitem>
<listitem>
<para>The output is written to a simple
<literal>Writer</literal>; no more
<literal>PrintWriter</literal>. This redesign causes FreeMarker
to no longer swallow <literal>IOException</literal>s during
template processing.</para>
</listitem>
<listitem>
<para>Various API cleanups, primarily the removing of
superfluous constructor and method overloads.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Other changes</title>
<itemizedlist>
<listitem>
<para>Documentation has been rewritten from scratch</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Differences between the RC1 and final release</title>
<itemizedlist>
<listitem>
<para>Added the support for date models and locale-sensitive
date formatting. <emphasis>Date support is experimental in
FreeMarker 2.1. It can change substantially in the future. Keep
this in mind if you use it.</emphasis></para>
</listitem>
<listitem>
<para>Added the <literal>default</literal> built-in which makes
it possible to specify default values for undefined
expressions.</para>
</listitem>
<listitem>
<para><literal>SimpleIterator</literal> has been removed,
<literal>SimpleCollection</literal> has been introduced</para>
</listitem>
<listitem>
<para>Arithmetic engine is pluggable. The core now contains two
arithmetic engines:
<literal>ArithmeticEngine.BIGDECIMAL_ENGINE</literal> and
<literal>ArithmeticEngine.CONSERVATIVE_ENGINE</literal>.</para>
</listitem>
<listitem>
<para><literal>BeansWrapper</literal> supports a new exposure
level: <literal>EXPOSE_NOTHING</literal></para>
</listitem>
<listitem>
<para><literal>Constants</literal> interface was removed.
<literal><replaceable>...</replaceable>_WRAPPER</literal>
constants have been moved from <literal>Constants</literal> to
<literal>ObjectWrapper</literal>,
<literal>EMPTY_STRING</literal> constant was moved to
<literal>TemplateScalarModel</literal>,
<literal>NOTHING</literal> constant was moved to
<literal>TemplateModel</literal>, <literal>TRUE</literal> and
<literal>FALSE</literal> constants were moved to
<literal>TemplateBooleanModel</literal>.</para>
</listitem>
<listitem>
<para><literal>JAVABEANS_WRAPPER</literal> was renamed to
<literal>BEANS_WRAPPER</literal></para>
</listitem>
<listitem>
<para><literal>Configuration.get</literal> and
<literal>put</literal>, <literal>putAll</literal> were renamed
to <literal>getSharedVariable</literal> and
<literal>setSharedVariable</literal>,
<literal>setAllSharedVariables</literal></para>
</listitem>
<listitem>
<para><literal>Configuration.getClassicCompatibility</literal>,
<literal>setClassicCompatibility</literal> were renamed to
<literal>isClassicCompatible</literal>,
<literal>setClassicCompatible</literal></para>
</listitem>
<listitem>
<para><literal>Template.process</literal> method overloads with
<literal>useReflection</literal> parameter was removed. But now
we have <literal>setObjectWrapper</literal> method in the
<literal>Configuration</literal>, so you can set the preferred
root-object wrapper there.</para>
</listitem>
<listitem>
<para>Some superfluous method overloads were removed; these
changes are backward compatible with RC1</para>
</listitem>
<listitem>
<para>Various minor JavaDoc and Manual improvements</para>
</listitem>
<listitem>
<para>Bugfix: <literal>include</literal> directive has
calculated the base path of relative paths wrongly</para>
</listitem>
<listitem>
<para>Bugfix: We have accidentally used a J2SE 1.3 class, but
FreeMarker 2.1 must able to run on J2SE 1.2</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_01">
<title>2.01</title>
<para>The main improvement is in error reporting. Now exceptions are
much more informative since they come with complete line number and
column information.</para>
<para>The only API change between 2.0 and 2.01 was the elimination of
the CacheListener/CacheEvent API. Now, if the updating of a template
file fails, the exception is thrown back to the caller to handle. If
you want logging to occur when a template file is updated
successfully, you can override the logFileUpdate() method in
FileTemplateCache.</para>
</section>
<section xml:id="versions_2_0">
<title>2.0</title>
<para>FreeMarker 2.0 final was released on 18 April 2002. The changes
with respect to the previous release, 2.0 RC3 are fairly minor.</para>
<section>
<title>Bugfixes</title>
<itemizedlist>
<listitem>
<para>There were a couple of bugs in handling null values, where
Lazarus did not do the same thing as FreeMarker Classic.
Traditionally, in FreeMarker, nulls were treated as being
equivalent to an empty string in the appropriate context. At
this point, to the best of our knowledge, there is backward
compatibility with FreeMarker Classic in this respect.</para>
</listitem>
<listitem>
<para>Literal strings can now include line breaks. This was a
backward compatibility issue with FreeMarker Classic that has
been fixed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes to the Template language</title>
<itemizedlist>
<listitem>
<para>You can use the extra built-in of
<literal>myString?web_safe</literal> to convert a string to its
"web-safe" equivalent, where problematic characters such as
'<' are converted to &lt;.</para>
</listitem>
<listitem>
<para>In displaying numbers with a fractional part, the
rendering apparatus now respects the decimal separator of the
template's locale, so that, for example, in continental Europe,
you would see 1,1 and in the U.S. locale, 1.1.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes to the API</title>
<itemizedlist>
<listitem>
<para>The <literal>getAsString()</literal> method in the
<literal>TemplateScalarModel</literal> interface now takes a
<literal>java.util.Locale</literal> as a parameter. For the most
part, this is a hook for later use. In the default
implementation, <literal>SimpleScalar</literal>, this parameter
is unused. If you are implementing this interface yourself, your
implementation may ignore the parameter. However, it will be
appealing for certain implementations.</para>
</listitem>
<listitem>
<para>The constructors of <literal>FileTemplateCache</literal>
have changed. If you are using an absolute directory on the file
system as the location of your templates, you need to pass in an
instance of <literal>java.io.File</literal> to indicate the
location. If you use the constructors that take a string, this
is taken to mean relative to the classloader classpath.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Miscellany</title>
<para>The ant build script build.xml now contains a target that
builds a .war file containing the Hello, World and Guestbook
examples. It builds a fmexamples.war. For example, if you are using
Tomcat in its out-of-the-box configuration, you would place this
under <TOMCAT_HOME>/webapps and then you would use
http://localhost:8080/fmexamples/servlet/hello and
http://localhost:8080/fmexamples/servlet/guestbook for the Hello,
World and Guestbook examples respectively.</para>
</section>
</section>
<section xml:id="versions_2_0RC3">
<title>2.0 RC3</title>
<para>FreeMarker 2.0 RC3 was released on 11 April 2002. This release
was primarily devoted to fixing bugs that were reported in RC2.</para>
<section>
<title>Bug Fixes</title>
<itemizedlist>
<listitem>
<para>Variables defined in an <include...> were not
available in the enclosing page. This has been fixed.</para>
</listitem>
<listitem>
<para>The JavaCC parser was not configured to handle Unicode
input correctly. Now, Unicode support is working.</para>
</listitem>
<listitem>
<para>There was a bug when comparing a number with null. It
should have returned false, but threw an exception instead. This
has been fixed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Changes to the Template Language</title>
<itemizedlist>
<listitem>
<para>The syntax of the include directive has changed. To
indicate an unparsed include file, you do as follows:</para>
<programlisting role="template"><include "included.html" ; parsed="n" ></programlisting>
<para>You can also indicate the encoding of the included file
this way:</para>
<programlisting role="template"> <include "included.html" ; encoding="ISO-8859-5"></programlisting>
</listitem>
<listitem>
<para>The built-in myString?trim was added for trimming the
leading and trailing white-space from strings.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>API changes</title>
<itemizedlist>
<listitem>
<para>The TemplateEventAdapter machinery was taken out. This was
never set up in a very useful manner and we anticipate that
version 2.1 will have more complete support for logging
events.</para>
</listitem>
<listitem>
<para>The template caching mechanism was streamlined and
simplified.</para>
</listitem>
<listitem>
<para>The FileTemplateCache can now be configured to load files
relative to a class loader, using the Class.getResource() call.
This allows templates to be bundled up in .jar files or in a
.war file for easy deployment of web-based apps.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_0RC2">
<title>2.0 RC2</title>
<para>FreeMarker 2.0 RC 2 was released on 4 April 2002. Here is a
summary of changes wrt to the first release.</para>
<section>
<title>Changes to Template Language</title>
<itemizedlist>
<listitem>
<para>Certain built-in functionality is provided via a new
operator, '?'. Thus, <literal>myList?size</literal> provides the
number of elements in a list. Similarly,
<literal>myString?length</literal> provides the length of a
string, <literal>myString?upper_case</literal> puts the string
all in capital letters, and <literal>myHash?keys</literal>
provides a sequence containing the keys in the hash. See <xref
linkend="ref_builtins" /> for list of all available
built-ins.</para>
</listitem>
<listitem>
<para>Numerical comparisons can now be made using the "natural"
operators < and > but there are also "web-safe"
alternatives, such as <emphasis>\lt</emphasis> and
<emphasis>\gt</emphasis>, since the use of these characters may
confuse HTML editors and parsers. Note that these changed
between rc1 and rc2, they now start with a backslash. A little
asymmetry is the fact that if you use the natural greater-than
or greater-than-or-equals operators (i.e. > or >=) the
expression must be in parentheses. With any other operator, the
parentheses are optional.</para>
</listitem>
<listitem>
<para>Within an iteration loop -- i.e. a
<literal>foreach</literal> or a <literal>list</literal> block --
the current count in the loop is available as the special
variable
<literal><replaceable>index</replaceable>_count</literal>. where
<replaceable>index</replaceable> is the name of the variable in
the iteration. A boolean variable called
<literal><replaceable>index</replaceable>_has_next</literal> is
also defined that indicates whether there are any more items in
the iteration after this one. Note that the index starts at
zero, so you will often be adding one to it in practice.</para>
</listitem>
<listitem>
<para>The <literal><#break></literal> directive can now be
used to break out of a <literal><#foreach...></literal> or
a <literal><list...></literal> loop. (Prior to this
version, it only worked within a switch-case block.) There is a
new directive called <literal><#stop></literal> that, when
encountered, simply halts processing of the template. This can
be useful for debugging purposes.</para>
</listitem>
<listitem>
<para>When invoking java methods that have been exposed to the
page, using the code in freemarker.ext.*, there are built-ins
that allow you to indicate the numerical type that you wish to
pass as the value. For instance, if you had two methods, one
that takes an int and another that takes a long, and you wanted
to pass in a value, you would have to specify which method.
<literal>myMethod(1?int)</literal> or
<literal>myMethod(1?long)</literal>. This is unnecessary if
there is only one method of the given name.</para>
</listitem>
<listitem>
<para>Ranges can be used to get the sublist from a list or the
substring of a string. For example:
<literal>myList[0..3]</literal> will return items 0 through 3 of
the list in question. Or, for example, you could get all the
elements of the list except for the first and last ones via:
<literal>myList[1..(myList?size-2)]</literal></para>
</listitem>
<listitem>
<para>Or we could get the first 6 characters of a string via
<literal>myString[0..5]</literal></para>
</listitem>
<listitem>
<para>Lists can be concatenated using the '+' operator.
Previously, this overloading of '+' only applied to
strings.</para>
</listitem>
<listitem>
<para>An attempt to compare a number to a string now throws an
exception, since it is indicative of a coding error. Note that
there is a backward compatibility mode that can be set (see
below) that loosens this up in order to be able to process
legacy templates.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>API Changes</title>
<itemizedlist>
<listitem>
<para>The <literal>TemplateSequenceModel</literal> interface now
has a <literal>size()</literal> method for getting the number of
elements in the sequence in question.</para>
</listitem>
<listitem>
<para>The <literal>TemplateModelIterator</literal> interface now
has a <literal>hasNext()</literal> method.</para>
</listitem>
<listitem>
<para>The default sequence and hash implementations,
<literal>freemarker.template.SimpleSequence</literal> and
<literal>freemarker.template.SimpleHash</literal> are now
unsynchronized. If you need the methods to be synchronized, you
can get a synchronized wrapper via the
<literal>synchronizedWrapper()</literal> in either class.</para>
</listitem>
<listitem>
<para>The <literal>freemarker.utility.ExtendedList</literal> and
<literal>freemarker.utility.ExtendedHash</literal> classes were
removed, since all of the extra keys that it defined are now
available using the appropriate '?' built-in operation, i.e.
<literal>myHash?keys</literal> or <literal>myList?size</literal>
or <literal>myList?last</literal>.</para>
</listitem>
<listitem>
<para>There is a method in
<literal>java.freemarker.Configuration</literal> named
<literal>setDebugMode()</literal> which allows you to decide
whether stack traces are simply output to the web client (the
best situation in development) or thrown back to the caller to
be handled more gracefully (the best situation in
production).</para>
</listitem>
<listitem>
<para>There is a flag that can be set to turn on a processing
mode that is more backward-compatible with FreeMarker Classic.
This is off by default, but you can set it via
<literal>Template.setClassicCompatibility(true)</literal>. What
this does is that it allows scalars to be treated as a
single-item list in a list directive. Also, it allows somewhat
more looseness about types. In FreeMarker 1.x, <literal><#if
x=="1"></literal> and <literal><#if x==1></literal>
were in fact equivalent. This meant that legacy templates might
tend to be slack about this. If classic compatibility is not
set, an attempt to compare the string "1" with the number 1 will
result in an exception being thrown. (Note that it is preferable
to get your templates working without the backward compatibility
flag, since it usually will require only minor changes. However,
for people with a lot of templates and no time to check over
them, this flag may be of use.)</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="versions_2_0RC1">
<title>2.0 RC1</title>
<para>The first public release of FreeMarker 2.0 was on 18 March 2002.
Here is a summary of the changes in the Lazarus release, with respect
to the last stable release of FreeMarker Classic.</para>
<para><emphasis>NOTA BENE</emphasis>:</para>
<para>Despite the changes delineated above, the Lazarus release is
almost entirely backward-compatible with FreeMarker Classic. We
believe that <emphasis>most</emphasis> existing code and templates
that work under FreeMarker Classic will continue working under
Lazarus, with at most minimal changes. In practice, the most common
cases where legacy template code is broken will be where assumptions
were made about numbers and strings being equivalent. Note that in
FreeMarker 2, 2 + 2 does not result in "22". The String "1" and the
number 1 are entirely different animals and thus, any code will be
broken if it relies on the boolean expression ("1"==1) being true.
There is a "classic compatibility mode" that can be set via:
<literal>Template.setClassCompatibility()</literal> that can be set so
that Lazarus emulates some of the quirky behavior of FreeMarker
Classic. However, any code that relied on the above "features" of
FreeMarker classic really should be reworked. You are less likely to
run into the other incompatibilities that are listed above. If you
come across any other anomalies, please do tell us about them.</para>
<section>
<title>Support for Numerical operations, both arithmetic and
boolean, as well as numerical ranges.</title>
<itemizedlist>
<listitem>
<para>Scalars can now be either strings or numbers. (In
FreeMarker Classic all scalars were strings.) The basic
operations allowed are addition, subtraction, multiplication,
division, and modulus using the <literal>+</literal>,
<literal>-</literal>, <literal>*</literal>,
<literal>/</literal>, and <literal>%</literal> operators
respectively. Arbitrary-precision arithmetic with integers and
floating point numbers are provided. Though our goal is
definitely to follow the principle of least surprise, for
backward compatibility, the <literal>+</literal> operator still
is used for string concatenation. If either the left hand side
or the right hand side of <literal>lhs + rhs</literal> is
non-numerical, we revert to interpreting this as string
concatenation. Thus, in FreeMarker 2, 2+2 evaluates to the
number 4, while any of "2"+2 or 2+"2" or "2"+"2" evaluate to the
string "22". In FreeMarker Classic, rather embarrassingly, all
of the above, including 2+2, evaluated to the string "22". An
attempt to use any other arithmetic operator besides the
<literal>+</literal> with non-numerical operands will cause an
exception to be thrown.</para>
</listitem>
<listitem>
<para>Output of a numerical expression can be made explicit via
the alternative <literal>#{....}</literal> syntax. If the
expression within the curly parentheses does not evaluate to a
numerical value, an exception is thrown. The older ${....}
syntax can evaluate to either a number or a string. In general,
if, for logical reasons, the output <emphasis>must</emphasis> be
numerical, it is preferable to use the #{...} syntax, since it
adds an extra sanity check. Note that if, by some miracle, the
character sequence "#{" occurs in your template, you will have
to use a workaround to prevent problems. (The <noparse>
directive is one possibility.)</para>
</listitem>
<listitem>
<para>In this release, there is a facility for specifying the
number of digits to show after the decimal point. The following
code specifies to show at least 3 digits after the decimal point
but not more than 6. This is optional. This option is only
available if you use the #{...} syntax.</para>
<programlisting role="template">#{foo + bar ; m3M6} </programlisting>
<para>(Note that the above is something of a stopgap measure.
Future releases will move toward supporting fully
internationalization and localization of number and currency
formatting.</para>
</listitem>
<listitem>
<para>Numerical expressions can be used in boolean expressions
via the comparison operators: <literal>lt</literal>,
<literal>gt</literal>, <literal>lte</literal>, and
<literal>gte</literal>. In the web space, where FreeMarker is
most used in practice, using the more natural operators such as
< and > would tend to confuse HTML-oriented editors. An
attempt to compare non-numerical expressions using these
operators leads to a <literal>TemplateException</literal> being
thrown. If, by some coincidence, you have variables named "lt",
"gt", "lte", or "gte", you will have to change their names,
since they are now keywords in the language.</para>
</listitem>
<listitem>
<para>Numerical ranges are supported.</para>
<programlisting role="template"><#list 1990..2001 as year>
blah blah in the year ${year} blah
</#list> </programlisting>
<para>The left hand and right hand sides of the
<literal>..</literal> operator must be numerical, or an
exception is thrown. They also need not be literal numbers, but
can be more complex expressions that evaluate to a numerical
scalar value. Note that it is also possible to write a range
that descends in value:</para>
<programlisting role="template"><#list 2001..1990 as year>
blah blah in the year ${year} blah blah
</#list> </programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>API Changes</title>
<itemizedlist>
<listitem>
<para>The <literal>TemplateNumberModel</literal> interface and
the <literal>SimpleNumber</literal> implementation were added to
support exposing numerical values.</para>
</listitem>
<listitem>
<para>The <literal>TemplateListModel</literal> API in FreeMarker
Classic had some design problems -- particularly in terms of
supporting thread-safe code. It has been deprecated in favor of
the following API's: <literal>TemplateCollectionModel</literal>
and <literal>TemplateSequenceModel</literal>. The
<literal>SimpleList</literal> class was refactored to implement
the above interfaces (and paradoxically, does not implement the
TemplateListModel interface.) Code that uses the deprecated
<literal>TemplateListModel</literal> should be
refactored.</para>
</listitem>
<listitem>
<para>The Expose Package by Attila Szegedi has been made an
integral part of the FreeMarker distribution and is now under
the freemarker.ext.* hierarchy. This package provides advanced
models for representing arbitrary Java objects as template
models, for representing XML documents as template models, as
well as classes to facilitate the integration of FreeMarker with
servlets and Ant.</para>
</listitem>
<listitem>
<para>In FreeMarker Classic, there were some utility classes
such as <literal>freemarker.template.utility.Addition</literal>
etcetera that existed as workarounds for the lack of numerical
operations in FreeMarker. Those have been removed and will
probably not be missed.</para>
</listitem>
<listitem>
<para>In FreeMarker Classic, the <literal>SimpleScalar</literal>
object was mutable, it had a <literal>setValue</literal> method.
This was fairly obviously a design mistake. Any code that relied
on this must be refactored. Note that in this release, both
<literal>SimpleScalar</literal> and the newly introduced
<literal>SimpleNumber</literal> are both immutable and
final.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Syntactical Miscellany</title>
<itemizedlist>
<listitem>
<para>The if-elseif-else syntax was introduced. FreeMarker
classic only had if-else. This construct should probably (in the
opinion of the author of this document -- Revusky) be used in
preference to switch-case since the switch-case with
fall-through is a notoriously error-prone construct for most
mortal men.</para>
</listitem>
<listitem>
<para>You can now do a multiple assignment in one
<assign...> directive. For example: <literal><assign x
= 1, y = price*items, message="foo"></literal></para>
</listitem>
<listitem>
<para>A scalar will no longer be interpreted as a one-item list
in a <list...> or <#foreach...> block. If you have
code that relied on this feature, there is an easy workaround,
since you can simply define a list literal with exactly one
item.</para>
<programlisting role="template"> <assign y=[x]>
<emphasis>and then...</emphasis>
<list y as item>...</list> </programlisting>
</listitem>
</itemizedlist>
</section>
</section>
</appendix>
<appendix xml:id="app_license">
<title>License</title>
<indexterm>
<primary>license</primary>
</indexterm>
<programlisting role="unspecified">FreeMarker 1.x was released under the LGPL license. Later, by community
consensus, we have switched over to a BSD-style license. As of FreeMarker
2.2pre1, the original author, Benjamin Geer, has relinquished the copyright in
behalf of Visigoth Software Society. The current copyright holder is the
Visigoth Software Society.
------------------------------------------------------------------------------
Copyright (c) 2003 The Visigoth Software Society. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. The end-user documentation included with the redistribution, if any, must
include the following acknowlegement:
"This product includes software developed by the
Visigoth Software Society (http://www.visigoths.org/)."
Alternately, this acknowlegement may appear in the software itself, if and
wherever such third-party acknowlegements normally appear.
3. Neither the name "FreeMarker", "Visigoth", nor any of the names of the
project contributors may be used to endorse or promote products derived
from this software without prior written permission. For written
permission, please contact [email protected].
4. Products derived from this software may not be called "FreeMarker" or
"Visigoth" nor may "FreeMarker" or "Visigoth" appear in their names
without prior written permission of the Visigoth Software Society.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
VISIGOTH SOFTWARE SOCIETY OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
------------------------------------------------------------------------------
This software consists of voluntary contributions made by many individuals on
behalf of the Visigoth Software Society. For more information on the Visigoth
Software Society, please see http://www.visigoths.org/
------------------------------------------------------------------------------
FREEMARKER SUBCOMPONENTS UNDER DIFFERENT LICENSE:
FreeMarker includes a number of subcomponents that are licensed by the Apache
Software Foundation under the Apache License, Version 2.0. Your use of these
subcomponents is subject to the terms and conditions of the Apache License,
Version 2.0. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
The subcomponents under this licence are the following files, which are
included both in freemarker.jar and in the source code:
freemarker/ext/jsp/web-app_2_2.dtd
freemarker/ext/jsp/web-app_2_3.dtd
freemarker/ext/jsp/web-app_2_4.xsd
freemarker/ext/jsp/web-app_2_5.xsd
freemarker/ext/jsp/web-jsptaglibrary_1_1.dtd
freemarker/ext/jsp/web-jsptaglibrary_1_2.dtd
freemarker/ext/jsp/web-jsptaglibrary_2_0.xsd
freemarker/ext/jsp/web-jsptaglibrary_2_1.xsd
</programlisting>
</appendix>
</part>
<glossary xml:id="gloss">
<glossentry xml:id="gloss.startTag">
<glossterm>Start-tag</glossterm>
<glossdef>
<para><link linkend="gloss.tag">Tag</link>, which indicates that the
following content is under the element, up to the <link
linkend="gloss.endTag">end-tag</link>. The start-tag may also
specifies <link linkend="gloss.attribute">attributes</link> for the
element. An example of a start-tag: <literal><body
bgcolor=black></literal></para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.boolean">
<glossterm>Boolean</glossterm>
<glossdef>
<para>This is a variable type. A boolean variable represents a logical
true or false (yes or no). For example, if the visitor has been logged
in or not. There are only two possible boolean values:
<literal>true</literal> and <literal>false</literal>. Typically, you
will use booleans with an <literal><#if
<replaceable>...</replaceable>></literal> directive when you want
to display text based on some condition, say, you show a certain part
of the page only for visitors who has logged in.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.character">
<glossterm>Character</glossterm>
<glossdef>
<para>A symbol that people use in writing. Examples of characters:
Latin capital letter A (``A''), Latin small letter A (``a''), digit
four (``4''), number sign (``#''), colon (``:'')</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.charset">
<glossterm>Charset</glossterm>
<glossdef>
<para>A charset is a rule (algorithm) for transforming a sequence of
<link linkend="gloss.character">characters</link> (text) to a sequence
of bits (or in practice, to a sequence of bytes). Whenever a character
sequence is stored on a digital media, or sent through a digital
channel (network), a charset must be applied. Examples of charsets are
ISO-8859-1, ISO-8859-6, Shift_JIS , UTF-8.</para>
<para>The capabilities of different charsers are different, that is,
not all charsets can be used for all languages. For example ISO-8859-1
can't represent Arabic letters, but ISO-8859-6 can, however it can't
represent the accented letters that that ISO-8859-1 can. Most charsets
are highly restrictive regarding the allowed characters. UTF-8 allows
virtually all possible characters, but most text editors can't handle
it yet (2004).</para>
<para>When different software components exchange text (as the HTTP
server and the browser, or the text editor you use for saving
templates and FreeMarker who loads them), it's very important that
they agree in the charset used for the binary encoding of the text. If
they don't, then the binary data will be misinterpreted by the
receiver (loader) component, which usually results in the distortion
of the non-English letters.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.outputEncoding">
<glossterm>Output encoding</glossterm>
<glossdef>
<para>Means output <link linkend="gloss.charset">charset</link>. In
the Java world the term ``encoding'' is commonly (mis)used as a
synonym to ``charset''.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.templateEncoding">
<glossterm>Template encoding</glossterm>
<glossdef>
<para>Means template <link linkend="gloss.charset">charset</link>. In
the Java world the term ``encoding'' is commonly (mis)used as a
synonym to ``charset''.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.collectionVariable">
<glossterm>Collection</glossterm>
<glossdef>
<para>A variable that (in conjunction with the <literal>list</literal>
directive) can spit out a series of variables.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.dataModel">
<glossterm>Data-model</glossterm>
<glossdef>
<para>Something that holds the information the template has to show
(or use in some other ways) when the template processor assembles the
output (e.g. a Web page). In FreeMarker this is best visualized as a
tree.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.directive">
<glossterm>Directive</glossterm>
<glossdef>
<para>Instructions to FreeMarker used in <link
linkend="gloss.FTL">FTL</link> <link
linkend="gloss.template">templates</link>. They are invoked by <link
linkend="gloss.FTLTag">FTL tags</link>.</para>
<glossseealso otherterm="gloss.predefinedDirective"></glossseealso>
<glossseealso otherterm="gloss.userDefinedDirective"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.element">
<glossterm>Element</glossterm>
<glossdef>
<para>Elements are the most fundamental building pieces of <link
linkend="gloss.SGML">SGML</link> documents; an SGML document is
basically a tree of elements. Example of elements used in HTML: body,
head, title, p, h1, h2.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.endTag">
<glossterm>End-tag</glossterm>
<glossdef>
<para><link linkend="gloss.tag">Tag</link>, which indicates that the
following content is not under the element. Example:
<literal></body></literal>.</para>
<glossseealso otherterm="gloss.startTag"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.environment">
<glossterm>Environment</glossterm>
<glossdef>
<para>An <literal>Environment</literal> object stores the runtime
state of a single template <link
linkend="gloss.templateProcessingJob">template processing job</link>.
That is, for each
<literal>Template.process(<replaceable>...</replaceable>)</literal>
call, an <literal>Environment</literal> instance will be created, and
then discarded when <literal>process</literal> returns. This object
stores the set of temporary variables created by the template, the
value of settings set by the template, the reference to the data-model
root, etc. Everything that is needed to fulfill the template
processing job.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.XML">
<glossterm>Extensible Markup Language</glossterm>
<glossdef>
<para>A subset (restricted version) of <link
linkend="gloss.SGML">SGML</link>. This is less powerful than SGML, but
it easier to learn and much easier to process with programs. If you
are an HTML author: XML documents are similar to HTML documents, but
the XML standard doesn't specify the usable elements. XML is a much
more general-purpose thing than HTML. For example you can use XML to
describe Web pages (like HTML) or to describe non-visual information
like a phone book database.</para>
<glossseealso otherterm="gloss.SGML">SGML</glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.FTL">
<glossterm>FreeMarker Template Language</glossterm>
<glossdef>
<para>Simple programming language designed to write text file
templates, especially HTML templates.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>FTL</glossterm>
<glosssee otherterm="gloss.FTL"></glosssee>
</glossentry>
<glossentry xml:id="gloss.FTLTag">
<glossterm>FTL tag</glossterm>
<glossdef>
<para><link linkend="gloss.tag">Tag</link>-like text fragment used to
invoke FreeMarker <link linkend="gloss.directive">directives</link> in
<link linkend="gloss.FTL">FTL</link> <link
linkend="gloss.template">templates</link>. These are similar to HTML
or XML tags at the first glance. The most prominent difference is that
the tag name is started with <literal>#</literal> or
<literal>@</literal>. Another important difference is that FTL tags do
not use <link linkend="gloss.attribute">attributes</link>, but a
substantially different syntax to specify parameters. Examples of FTL
tags: <literal><#if newUser></literal>,
<literal></#if></literal>, <literal><@menuitem
title="Projects" link="projects.html"/></literal></para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.hashVariable">
<glossterm>Hash</glossterm>
<glossdef>
<para>A variable that acts as a container that stores subvariables
that can be retrieved via a string that is a lookup name.</para>
<glossseealso otherterm="gloss.sequenceVariable"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.lineBreak">
<glossterm>Line break</glossterm>
<glossdef>
<para>Line break is a special character (or a sequence of special
characters) that causes a line breaking when you see the text as plain
text (say, when you read the text with Windows notepad). Typically you
type this character by hitting ENTER or RETURN key. The line break is
represented with different characters on different platforms (to cause
incompatibility and confusion...): ``line feed'' character on UNIX-es,
``carriage return'' character on Macintosh, ``carriage return''+``line
feed'' (two characters!) on Windows and DOS. Note that line breaks in
HTML do not have a visual effect when viewed in a browser; you must
use markup such as <literal><BR></literal> for that. This manual
never means <literal><BR></literal> when it says
``line-break''.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.macroDefinitionBody">
<glossterm>Macro definition body</glossterm>
<glossdef>
<para>The template fragment between the <literal><#macro
<replaceable>...</replaceable>></literal> and
<literal></#macro></literal>. This template fragment will be
executed when you call the macro (for example as
<literal><@myMacro/></literal>).</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.methodVariable">
<glossterm>Method</glossterm>
<glossdef>
<para>A variable that calculates something based on parameters you
give, and returns the result.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.MVC">
<glossterm>MVC pattern</glossterm>
<glossdef>
<para>MVC stands for Model View Controller. It's a design pattern
started his life in the 70's as a framework developer by Trygve
Reenskaug for Smalltalk, and was used primary for for UI-s (user
interfaces). MVC considers three roles:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Model: Model represents application (domain) specific
information in a non-visual way. For example, an array of product
objects in the memory of your computer is the part of the
model.</para>
</listitem>
<listitem>
<para>View: View displays the model and provides UI. For example,
it's the task of the view component to render the array of product
objects to a HTML page.</para>
</listitem>
<listitem>
<para>Controller: The controller handles user input, modifies the
model, and ensures that the view is updated when needed. For
example it is the task of controller to take the incoming HTTP
requests, parse the received parameters (forms), dispatch the
requests to the proper business logic object, and chose the right
template for the HTTP response.</para>
</listitem>
</itemizedlist>
<para>The most important thing for us when applying MVC for Web
applications is the separation of View from the other two roles. This
allows the separation of designers (HTML authors) from programmers.
Designers deal with the visual aspects, programmers deal with the
application logic and other technical issues; everybody works on what
he is good at. Designers and programmers are less dependent on each
other. Designers can change the appearance without programmers having
to change or recompile the program.</para>
<para>For more information I recommend reading <link
xlink:href="http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/web-tier/web-tier5.html">chapter
4.4</link> of Designing Enterprise Applications with the J2EE Platform
blueprint.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.predefinedDirective">
<glossterm>Predefined directive</glossterm>
<glossdef>
<para>Directive what is defined by FreeMarker, thus always available.
Example of predefined directives: <literal>if</literal>,
<literal>list</literal>, <literal>include</literal></para>
<glossseealso otherterm="gloss.userDefinedDirective"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.scalarVariable">
<glossterm>Scalar</glossterm>
<glossdef>
<para>A scalar variable stores a single value. A scalar is either a
string or a number or a date/time or a <link
linkend="gloss.boolean">boolean</link>.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.sequenceVariable">
<glossterm>Sequence</glossterm>
<glossdef>
<para>A sequence is a variable that contains a sequence of
subvariables. The sequence's subvariables are accessible via numerical
index, where the index of the very first object is 0, the index of the
second objects is 1, the index of the third object is 2, etc.</para>
<glossseealso otherterm="gloss.hashVariable"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.regularExpression">
<glossterm>Regular expression</glossterm>
<glossdef>
<para>A regular expression is a string that specifies a set of strings
that matches it. For example, the regular expression
<literal>"fo*"</literal> matches <literal>"f"</literal>,
<literal>"fo"</literal>, <literal>"foo"</literal>, etc. Regular
expressions are used in several languages and other tools. In
FreeMarker, the usage of them is a ``power user'' option. So if you
have never used them before, there is no need to worry about not being
familiar with them. But if you are interested in regular expressions,
you can find several Web pages and books about them. FreeMarker uses
the variation of regular expressions described at: <link
xlink:href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html</link></para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SGML</glossterm>
<glosssee otherterm="gloss.SGML"></glosssee>
</glossentry>
<glossentry xml:id="gloss.SGML">
<glossterm>Standard Generalized Markup Language</glossterm>
<glossdef>
<para>This is an international standard (ISO 8879) that specifies the
rules for the creation of platform-independent markup languages. HTML
is a markup language created with SGML. <link
linkend="gloss.XML">XML</link> is a subset (restricted version) of
SGML.</para>
<glossseealso otherterm="gloss.XML">XML</glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.string">
<glossterm>String</glossterm>
<glossdef>
<para>A sequence of <link linkend="gloss.character">characters</link>
such as ``m'', ``o'', ``u'', ``s'', ``e''.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.tag">
<glossterm>Tag</glossterm>
<glossdef>
<para>Text fragment indicating the usage of an element in SGML.
Examples of tags: <literal><body bgcolor=black></literal>,
<literal></body></literal></para>
<glossseealso otherterm="gloss.startTag"></glossseealso>
<glossseealso otherterm="gloss.endTag"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.template">
<glossterm>Template</glossterm>
<glossdef>
<para>A template is a text file with some special character sequences
embedded into it. A template processor (e.g. FreeMarker) will
interpret special character sequences and it outputs a more or less
different text from the original text file, where the differences are
often based on a <link linkend="gloss.dataModel">data-model</link>.
Thus, the original text acts as a template of the possible
outputs.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.templateProcessingJob">
<glossterm>Template processing job</glossterm>
<glossdef>
<para>A template processing job is the act when FreeMarker merges a
template with a data-model to produce the output for a visitor. Note
that this may includes the execution of multiple template files
because the template file used for the Web page may invokes other
templates with <literal>include</literal> and
<literal>import</literal> directives. Each template-processing job is
a separated cosmos that exists only for the short period of time while
the given page is being rendered for the visitor, and then it vanishes
with all the variables created in the templates (for example,
variables created with <literal>assign</literal>,
<literal>macro</literal> or <literal>global</literal>
directives).</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.transformVariable">
<glossterm>Transform</glossterm>
<glossdef>
<para>This term refers to user-defined directives that are implemetned
with the now obsolete <literal>TemplateTransformModel</literal> Java
interface. The feature was originally made for implementing output
filters, hence the name.</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.threadSafe">
<glossterm>Thread-safe</glossterm>
<glossdef>
<para>An object is thread-safe if it is safe to call its methods from
multiple threads, even in parallel (i.e. multiple threads execute the
methods of the object at the same time). Non-thread-safe objects may
behave unpredictably in this situation, and generate wrong results,
corrupt internal data structures, etc. Thread-safety is typically
achieved in two ways with Java: with the usage
<literal>synchronized</literal> statement (or
<literal>synchronized</literal> methods), and with the immutability of
encapsulated data (i.e. you can't modify the field after you have
created the object).</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.userDefinedDirective">
<glossterm>User-defined directive</glossterm>
<glossdef>
<para>Directive that is not defined by the FreeMarker core, but by the
user. These are typically application domain specific directives, like
pull-down menu generation directives, HTML form handling
directives.</para>
<glossseealso otherterm="gloss.predefinedDirective"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.UCS">
<glossterm>UCS</glossterm>
<glossdef>
<para>This is international standard (ISO-10646) that defines a huge
set of <link linkend="gloss.character">characters</link> and assigns a
unique number for each character (``!'' is 33, ..., ``A'' is 61, ``B''
is 62, ..., Arabic letter hamza is 1569... etc.). This character set
(not charset) contains almost all characters used today (Latin
alphabet, Cyrillic alphabet, Chinese letters, etc.). The idea behind
UCS is that we can specify any character with a unique number, not
mater what the platform or the language is.</para>
<glossseealso otherterm="gloss.unicode"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.unicode">
<glossterm>Unicode</glossterm>
<glossdef>
<para>De-facto standard developed by Unicode organization. It deals
with the classification of the characters in <link
linkend="gloss.UCS">UCS</link> (which is letter, which is digit, which
is uppercase, which is lowercase, etc.), and with other problems of
processing text made from the characters of UCS (e.g.
normalization).</para>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.whiteSpace">
<glossterm>White-space</glossterm>
<glossdef>
<para>Characters that are totally transparent but have impact on the
visual appearance of the text. Examples of white-space characters:
space, tab (horizontal and vertical), line breaks (CR and LF), form
feed.</para>
<glossseealso otherterm="gloss.lineBreak"></glossseealso>
</glossdef>
</glossentry>
<glossentry>
<glossterm>XML</glossterm>
<glosssee otherterm="gloss.XML"></glosssee>
</glossentry>
<glossentry xml:id="gloss.attribute">
<glossterm>Attribute</glossterm>
<glossdef>
<para>In connection with <link linkend="gloss.XML">XML</link> or HTML
(or <link linkend="gloss.SGML">SGML</link> in general), attributes are
the named values associated with elements. For example, in
<literal><body bgcolor=black
text=green><replaceable>...</replaceable></body></literal>,
the attributes are <literal>bgcolor=black</literal> and
<literal>text=green</literal>. On the left side of
<literal>=</literal> is the name of the attribute, while on the right
side is the value of the attribute. Note that in XML, the values must
be quoted (for example: <literal><body bgcolor="black"
text='green'></literal>), while in HTML it is optional for certain
values.</para>
<glossseealso otherterm="gloss.startTag"></glossseealso>
</glossdef>
</glossentry>
<glossentry xml:id="gloss.fullQualifiedName">
<glossterm>Full-qualified name</glossterm>
<glossdef>
<para>... of nodes (XML node or other FTL node variable): The
full-qualified name of a node specifies not only the node name
(<literal><replaceable>node</replaceable>?node_name</literal>), but
also the node namespace
(<literal><replaceable>node</replaceable>?node_namespace</literal>),
this way it unambiguously identify a certain kind of node. The format
of the full-qualified name is
<literal><replaceable>nodeName</replaceable></literal> or
<literal><replaceable>prefix</replaceable>:<replaceable>nodeName</replaceable></literal>.
The prefix is shorthand to identify the node namespace (the a node
namespace is usually specified with a long ugly URI). In FTL, prefixes
are associated with the node namespaces with the
<literal>ns_prefixes</literal> parameter of <link
linkend="ref.directive.ftl">the <literal>ftl</literal>
directive</link>. In XML files, prefixes are associated with the node
namespaces with the
<literal>xmlns:<replaceable>prefix</replaceable></literal> attributes.
The lack of the prefix means that the node uses the default node
namespace, if a default node namespace is defined; otherwise it means
that the node does not belong to any node namespace. The default node
namespace is defined in FTL by registering reserved prefix
<literal>D</literal> with the <literal>ns_prefixes</literal> parameter
of the <literal>ftl</literal> directive. In XML files it is defined
with attribute <literal>xmlns</literal>.</para>
<para>... of Java classes: The full-qualified name of a Java class
contains both the class name and the name of the package the class
belongs to. This way it unambiguously specifies the class, regardless
of the context. An example of full-qualifed class name:
<literal>java.util.Map</literal> (as opposed to
<literal>Map</literal>).</para>
</glossdef>
</glossentry>
</glossary>
<index xml:id="alphaidx">
<title>Alphabetical Index</title>
</index>
</book>