freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [02/35] incubator-freemarker git commit: Made place for the Chinese manual.
Date Wed, 30 Dec 2015 18:11:57 GMT
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
new file mode 100644
index 0000000..c561322
--- /dev/null
+++ b/src/manual/en_US/book.xml
@@ -0,0 +1,37479 @@
+<?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">
+  <info>
+    <title>FreeMarker Manual</title>
+
+    <titleabbrev>Manual</titleabbrev>
+
+    <productname>Freemarker 2.3.24 Preview 1</productname>
+  </info>
+
+  <preface role="index.html" xml:id="preface">
+    <title>What is FreeMarker?</title>
+
+    <para>FreeMarker is a <emphasis>template engine</emphasis>: a generic tool
+    to generate text output (HTML web pages, e-mails, configuration files,
+    source code, etc.) based on templates and changing data. It's not an
+    application for end-users in itself, but a Java library, a component that
+    programmers can embed into their products.</para>
+
+    <para>Templates are written in the FreeMarker Template Language (FTL).
+    It's a simple, specialized language, <emphasis>not</emphasis> a full-blown
+    programming language like PHP. You meant to prepare the data to display in
+    a real programming language, like issue database queries and do business
+    calculations, and then the template displays that already prepared data.
+    In the template you are focusing on how to present the data, and outside
+    the template you are focusing on what data to present.</para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/overview.png"/>
+      </imageobject>
+    </mediaobject>
+
+    <para>This approach is often referred to as the <link
+    linkend="gloss.MVC">MVC (Model View Controller) pattern</link>, and is
+    particularly popular for dynamic Web pages. It helps in separating the Web
+    page designers (HTML authors) from the developers (Java programmers
+    usually). Designers won't face complicated logic in templates, and can
+    change the appearance of a page without programmers having to change or
+    recompile code.</para>
+
+    <para>While FreeMarker was originally created for generating HTML pages in
+    MVC web application frameworks, it isn't bound to servlets or HTML or
+    anything Web-related. It's used in non-web application environments as
+    well.</para>
+
+    <para>FreeMarker is <link
+    xlink:href="http://www.fsf.org/philosophy/free-sw.html">Free</link>,
+    released under the Apache License, Version 2.0.</para>
+  </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>Let's assume that you need a HTML page in a Web shop, similar to
+        this:</para>
+
+        <programlisting role="output">&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;Welcome!&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+  &lt;h1&gt;Welcome <emphasis>John Doe</emphasis>!&lt;/h1&gt;
+  &lt;p&gt;Our latest product:
+  &lt;a href="<emphasis>products/greenmouse.html</emphasis>"&gt;<emphasis>green mouse</emphasis>&lt;/a&gt;!
+&lt;/body&gt;
+&lt;/html&gt;</programlisting>
+
+        <para>But the user name ("John Doe" 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 too. Thus you can't enter
+        these into the HTML directly, you can't use static HTML. Instead, you
+        can use a <emphasis role="term">template</emphasis> of the desired
+        output. The template is the same as the static HTML would be, except
+        that it contains some instructions to FreeMarker that makes it
+        dynamic:</para>
+
+        <programlisting role="template" xml:id="example.first">&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;Welcome!&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+  &lt;h1&gt;Welcome <emphasis>${user}</emphasis>!&lt;/h1&gt;
+  &lt;p&gt;Our latest product:
+  &lt;a href="<emphasis>${latestProduct.url}</emphasis>"&gt;<emphasis>${latestProduct.name}</emphasis>&lt;/a&gt;!
+&lt;/body&gt;
+&lt;/html&gt;</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, 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. (Of course, the
+        template file stored on the Web server is not changed by this; the
+        substitutions only appear in the Web server's response.)</para>
+
+        <para>Note that the template doesn't contain the programming logic to
+        find out who the current visitor is, or to query the database to get
+        the latest product. The data to be displayed is prepared outside
+        FreeMarker, usually by parts written in some <quote>real</quote>
+        programming language like Java. The template author needn't know how
+        these values were calculated. In fact, the way these values are
+        calculated can be completely changed while the templates can remain
+        exactly the same, and also, the look of the page can be completely
+        changed without touching anything but the template. This separation of
+        presentation logic and business logic can be especially useful when
+        the template authors (designers) and the programmers are different
+        individuals, but also helps managing application complexity if they
+        are the same person. Keeping templates focused on presentation issues
+        (visual design, layout and formatting) is a key for using template
+        engines like FreeMarker efficiently.</para>
+
+        <para><indexterm>
+            <primary>data-model</primary>
+          </indexterm>The totality of data that was prepared for the template
+        is called the <emphasis role="term">data-model</emphasis>. As far as
+        the template author is concerned, the data-model is a tree-like
+        structure (like folders and files on your hard disk), which, 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>
+
+        <note>
+          <para>The above is just a visualization; the data-model is not in a
+          textual format, it's from Java objects. For the Java programmers,
+          the root is perhaps a Java object with <literal>getUser()</literal>
+          and <literal>getLatestProduct()</literal> methods, or maybe a Java
+          <literal>Map</literal> with <literal>"user"</literal> and
+          <literal>"latestProducts"</literal> keys. Similarly,
+          <literal>latestProduct</literal> is perhaps a Java Object with
+          <literal>getUrl()</literal> and <literal>getName()</literal>
+          methods.</para>
+        </note>
+
+        <para>Earlier, you have picked values from this data-model, with the
+        <literal>user</literal> and <literal>latestProduct.name</literal>
+        expressions. If we go on with the analogy that the data model is like
+        a file system, then <quote>(root)</quote> and
+        <literal>latestProduct</literal> correspond to directories (folders),
+        and <literal>user</literal>, <literal>url</literal> and
+        <literal>name</literal> are files in those directories.</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
+  |
+  +- message = "It is a test"
+  |
+  +- misc
+      |
+      +- foo = "Something"</programlisting>
+
+        <para>The variables that act like directories (the root,
+        <literal>animals</literal>, <literal>mouse</literal>,
+        <literal>elephant</literal>, <literal>python</literal>,
+        <literal>misc</literal>) are called <emphasis
+        role="term">hashes</emphasis>. Hashes store other variables (the so
+        called <anchor xml:id="topic.dataModel.subVar"/><emphasis>sub
+        variables</emphasis>) by a lookup name (e.g., <quote>animals</quote>,
+        <quote>mouse</quote> or <quote>price</quote>).</para>
+
+        <para>The variables that store a single value
+        (<literal>size</literal>, <literal>price</literal>,
+        <literal>message</literal> and <literal>foo</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>.</para>
+
+        <para>Another important kind of variables are <emphasis
+        role="term">sequences</emphasis>. They store subvariables like hashes,
+        but here subvariables doesn't have a name, they are just items in a
+        list. For example, in this data-model, <literal>animals</literal> and
+        <literal>misc.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
+  |
+  +- misc
+      |
+      +- 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 1st item is 0, the index of
+        the 2nd 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>misc.fruits</literal> (the string
+        <literal>"banana"</literal>) you write
+        <literal>misc.fruits[1]</literal>. (In practice, you usually just walk
+        through sequences in order, not caring about the index, but that will
+        be <link linkend="topic.tutorial.list">shown later</link>.)</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 in arithmetical calculations.</para>
+          </listitem>
+
+          <listitem>
+            <para>Date-like: Either a date-time (stores a date with time of
+            the day), or a date (no time of day), or a time (time of day, no
+            date).</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/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>
+
+        <note>
+          <para>There are other, more advanced value types that we don't cover
+          here, such as methods and directives.</para>
+        </note>
+      </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 expression inside the curly brackets. They are called
+            <emphasis role="term">interpolation</emphasis>s.</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>&lt;#--</literal> and <literal>--&gt;</literal>. Unlike
+            HTML comments, FTL comments won't get into the output (won't be
+            visible in the page source for the visitor), because FreeMarker
+            skips them.</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>&lt;table&gt;</literal> and
+        <literal>&lt;/table&gt;</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>
+
+        <note>
+          <para>You can easily try writing templates on <link
+          xlink:href="http://freemarker-online.kenshoo.com/">http://freemarker-online.kenshoo.com/</link></para>
+        </note>
+
+        <section>
+          <title>Some basic directives</title>
+
+          <para>Here we will look at some of the most commonly used directives
+          (<link linkend="ref_directives">but there are much
+          more</link>).</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
+            than other users:</para>
+
+            <programlisting role="template">&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;Welcome!&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+  &lt;h1&gt;
+    Welcome ${user}<emphasis>&lt;#if user == "Big Joe"&gt;</emphasis>, our beloved leader<emphasis>&lt;/#if&gt;</emphasis>!
+  &lt;/h1&gt;
+  &lt;p&gt;Our latest product:
+  &lt;a href="${latestProduct.url}"&gt;${latestProduct.name}&lt;/a&gt;!
+&lt;/body&gt;
+&lt;/html&gt;</programlisting>
+
+            <para>Here you have told FreeMarker that the <quote>, our beloved
+            leader</quote> 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>&lt;#if
+            <replaceable>condition</replaceable>&gt;</literal> and
+            <literal>&lt;/#if&gt;</literal> tags are skipped if
+            <literal><replaceable>condition</replaceable></literal> is false
+            (the boolean value).</para>
+
+            <para>Let's look at
+            <literal><replaceable>condition</replaceable></literal> more
+            closely: <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 <quote>Pythons are free today!</quote> if
+            their price is 0:</para>
+
+            <programlisting role="template">&lt;#if animals.python.price == <emphasis>0</emphasis>&gt;
+  Pythons are free today!
+&lt;/#if&gt;</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, and because the price to compare it to is number,
+            you get an error.</para>
+
+            <para>This will print "Pythons are not free today!" if their price
+            is not 0:</para>
+
+            <programlisting role="template">&lt;#if animals.python.price <emphasis>!=</emphasis> 0&gt;
+  Pythons are not free today!
+&lt;/#if&gt;</programlisting>
+
+            <para>As you probably guessed, <literal>!=</literal> means
+            <quote>not equals</quote>.</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">&lt;#if <emphasis>animals.python.price &lt; animals.elephant.price</emphasis>&gt;
+  Pythons are cheaper than elephants today.
+&lt;/#if&gt;</programlisting>
+
+            <para>With the <literal>&lt;#else&gt;</literal> tag you can
+            specify what to do if the condition is false. For example:</para>
+
+            <programlisting role="template">&lt;#if animals.python.price &lt; animals.elephant.price&gt;
+  Pythons are cheaper than elephants today.
+<emphasis>&lt;#else&gt;</emphasis>
+  Pythons are not cheaper than elephants today.
+&lt;/#if&gt;</programlisting>
+
+            <para>This prints <quote>Pythons are cheaper than elephants
+            today.</quote> if the price of python is less than the price of
+            elephant, or else it prints <quote>Pythons are not cheaper than
+            elephants today.</quote> You can refine this further by using
+            <literal>elseif</literal>:</para>
+
+            <programlisting role="template">&lt;#if animals.python.price &lt; animals.elephant.price&gt;
+  Pythons are cheaper than elephants today.
+<emphasis>&lt;#elseif animals.elephant.price &lt; animals.python.price&gt;</emphasis>
+  Elephants are cheaper than pythons today.
+&lt;#else&gt;
+  Elephants and pythons cost the same today.
+&lt;/#if&gt;</programlisting>
+
+            <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">&lt;#if animals.python.protected&gt;
+  Pythons are protected animals!
+&lt;/#if&gt;</programlisting>
+          </section>
+
+          <section>
+            <title>The list directive</title>
+
+            <anchor xml:id="topic.tutorial.list"/>
+
+            <para>This is needed when you want to list something. For example
+            if you merge this template with the <link
+            linkend="example.qStart.dataModelWithSequences">data-model used
+            earlier to demonstrate sequences</link>:</para>
+
+            <programlisting role="template">&lt;p&gt;We have these animals:
+&lt;table border=1&gt;
+  <emphasis>&lt;#list animals as animal&gt;</emphasis>
+    &lt;tr&gt;&lt;td&gt;${<emphasis>animal</emphasis>.name}&lt;td&gt;${<emphasis>animal</emphasis>.price} Euros
+  <emphasis>&lt;/#list&gt;</emphasis>
+&lt;/table&gt;</programlisting>
+
+            <para>then the output will be:</para>
+
+            <programlisting role="output">&lt;p&gt;We have these animals:
+&lt;table border=1&gt;
+    <emphasis>&lt;tr&gt;&lt;td&gt;mouse&lt;td&gt;50 Euros
+    &lt;tr&gt;&lt;td&gt;elephant&lt;td&gt;5000 Euros
+    &lt;tr&gt;&lt;td&gt;python&lt;td&gt;4999 Euros</emphasis>
+&lt;/table&gt;</programlisting>
+
+            <para>The generic form of the <literal>list</literal> directive
+            is:<literal> &lt;#list <replaceable>sequence</replaceable> as
+            <replaceable>loopVariable</replaceable>&gt;<replaceable>repeatThis</replaceable>&lt;/#list&gt;</literal>.
+            The <literal><replaceable>repeatThis</replaceable></literal> part
+            will be repeated for each item in the sequence that you have
+            specified 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>&lt;#list
+            <replaceable>...</replaceable>&gt;</literal> and
+            <literal>&lt;/#list&gt;</literal> tags.</para>
+
+            <para>The <literal><replaceable>sequence</replaceable></literal>
+            can be any kind of expression, like we could list the fruits of
+            the example data model like this:</para>
+
+            <programlisting role="template">&lt;ul&gt;
+<emphasis>&lt;#list misc.fruits as fruit&gt;</emphasis>
+  &lt;li&gt;${fruit}
+<emphasis>&lt;/#list&gt;</emphasis>
+&lt;/ul&gt;</programlisting>
+
+            <para>The <literal>misc.fruits</literal> expression should be
+            familiar to you; it <link
+            linkend="topic.qStart.accessVariables">references a variable in
+            the data-model</link>.</para>
+
+            <para>A problem with the above example is that if we happen to
+            have 0 fruits, it will still print an empty
+            <literal>&lt;ul&gt;&lt;/ul&gt;</literal> instead of just nothing.
+            To avoid that, you can use this form of
+            <literal>list</literal>:</para>
+
+            <programlisting role="template">&lt;#list misc.fruits&gt;
+  &lt;ul&gt;
+   <emphasis> &lt;#items as fruit&gt;</emphasis>
+      &lt;li&gt;${fruit}
+ <emphasis>   &lt;/#items&gt;</emphasis>
+  &lt;/ul&gt;
+&lt;/#list&gt;</programlisting>
+
+            <para>Here, the <literal>list</literal> directive represents the
+            listing as a whole, and only the part inside the
+            <literal>items</literal> directive is repeated for each fruit. If
+            we have 0 fruits, everything inside <literal>list</literal> is
+            skipped, hence we will not have <literal>ul</literal> tags in
+            case.</para>
+
+            <para>Another frequent listing-related task: let's list the fruits
+            separating them with something, like comma:</para>
+
+            <programlisting role="template">&lt;p&gt;Fruits: &lt;#list misc.fruits as fruit&gt;${fruit}<emphasis>&lt;#sep&gt;, </emphasis>&lt;/#list&gt;</programlisting>
+
+            <programlisting role="output">&lt;p&gt;Fruits: orange, banana</programlisting>
+
+            <para>The section covered by <literal>sep</literal> (which we
+            could be written like this too:
+            <literal><replaceable>...</replaceable>&lt;#sep&gt;,
+            &lt;/#sep&gt;&lt;/#list&gt;</literal>) will be only executed when
+            there will be a next item. Hence there's no comma after the last
+            fruit.</para>
+
+            <para>Here again, what's if we have 0 fruits? Just printing
+            <quote>Fruits:</quote> and then nothing is awkward. A
+            <literal>list</literal>, just like an <literal>if</literal>, can
+            have an <literal>else</literal>, which is executed if there were 0
+            list items:</para>
+
+            <programlisting role="template">&lt;p&gt;Fruits: &lt;#list misc.fruits as fruit&gt;${fruit}&lt;#sep&gt;, <emphasis>&lt;#else&gt;None</emphasis>&lt;/#list&gt;</programlisting>
+
+            <note>
+              <para>As a matter of fact, this simplistic example could be
+              written like this, but it uses language devices that are off
+              topic here:</para>
+
+              <programlisting role="template">&lt;p&gt;Fruits: ${fruits?join(", ", "None")}</programlisting>
+            </note>
+
+            <para>All these directives (<literal>list</literal>,
+            <literal>items</literal>, <literal>sep</literal>,
+            <literal>else</literal>) can be used together:</para>
+
+            <programlisting role="template">&lt;#list misc.fruits&gt;
+  &lt;p&gt;Fruits:
+  &lt;ul&gt;
+    &lt;#items as fruit&gt;
+      &lt;li&gt;${fruit}&lt;#sep&gt; and&lt;/#sep&gt;
+    &lt;/#items&gt;
+  &lt;/ul&gt;
+&lt;#else&gt;
+  &lt;p&gt;We have no fruits.
+&lt;/#list&gt;</programlisting>
+
+            <note>
+              <para>You can read more about these directives <link
+              linkend="ref_directive_list">in the Reference</link>.</para>
+            </note>
+          </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">&lt;hr&gt;
+&lt;i&gt;
+Copyright (c) 2000 &lt;a href="http://www.acmee.com"&gt;Acmee Inc&lt;/a&gt;,
+&lt;br&gt;
+All Rights Reserved.
+&lt;/i&gt;</programlisting>
+
+            <para>Whenever you need that file you simply insert it with the
+            <literal>include</literal> directive:</para>
+
+            <programlisting role="template">&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;Test page&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+  &lt;h1&gt;Test page&lt;/h1&gt;
+  &lt;p&gt;Blah blah...
+<emphasis>  &lt;#include "/copyright_footer.html"&gt;</emphasis>
+&lt;/body&gt;
+&lt;/html&gt;</programlisting>
+
+            <para>and the output will be:</para>
+
+            <programlisting role="output">&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;Test page&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+  &lt;h1&gt;Test page&lt;/h1&gt;
+  &lt;p&gt;Blah blah...
+<emphasis>&lt;hr&gt;
+&lt;i&gt;
+Copyright (c) 2000 &lt;a href="http://www.acmee.com"&gt;Acmee Inc&lt;/a&gt;,
+&lt;br&gt;
+All Rights Reserved.
+&lt;/i&gt;</emphasis>
+&lt;/body&gt;
+&lt;/html&gt;</programlisting>
+
+            <para>If you change the <literal>copyright_footer.html</literal>,
+            then the visitor will see the new copyright notice on all
+            pages.</para>
+
+            <note>
+              <para>A much more powerful way of reusing snippets is using
+              macros, but that's an advanced topic <link
+              linkend="dgui_misc_userdefdir">discussed later</link>.</para>
+            </note>
+          </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 freely. For example,
+          here you nest <literal>if</literal> directive inside a
+          <literal>list</literal> directive:</para>
+
+          <programlisting role="template"><emphasis>&lt;#list animals as animal&gt;</emphasis>
+      &lt;div<emphasis>&lt;#if animal.protected&gt;</emphasis><emphasis> </emphasis>class="protected"<emphasis>&lt;/#if&gt;</emphasis>&gt;
+        ${animal.name} for ${animal.price} Euros
+      &lt;/div&gt;
+<emphasis>&lt;/#list&gt;</emphasis></programlisting>
+
+          <para>Note that since FreeMarker does not interpret text outside FTL
+          tags, interpolations and FTL comments, above you could use the FTL
+          tags inside a HTML attributes without problem.</para>
+        </section>
+
+        <section>
+          <title>Using built-ins</title>
+
+          <para>The so called built-ins are like subvariables (or rather like
+          methods, if you know that Java term) that aren't coming coming from
+          the data-model, but added by FreeMarker to the values. To make it
+          unambiguous where the subvarable comes from, to access them you have
+          to use <literal>?</literal> (question mark) instead of
+          <literal>.</literal> (dot). <anchor
+          xml:id="topic.commonlyUsedBuiltIns"/>Examples with some of the most
+          commonly used built-ins:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>user?upper_case</literal> gives the upper case
+              version of the value of <literal>user</literal> (like
+              <quote>JOHN DOE</quote> instead of <quote>John
+              Doe</quote>)</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>animal.name?cap_first</literal> give the
+              <literal>animal.name</literal> with its first letter converted
+              to upper case (like <quote>Mouse</quote> instead of
+              <quote>mouse</quote>)</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>user?length</literal> gives the number of
+              <emphasis>characters</emphasis> in the value of
+              <literal>user</literal> (8 for <quote>John Doe</quote>)</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>animals?size</literal> gives the number of
+              <emphasis>items</emphasis> in the <literal>animals</literal>
+              sequence (3 in our example data-model)</para>
+            </listitem>
+
+            <listitem>
+              <para>If you are between <literal>&lt;#list animals as
+              animal&gt;</literal> and the corresponding
+              <literal>&lt;/#list&gt;</literal> tag:</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para><literal>animal?index</literal> gives the 0-based
+                  index of <literal>animal</literal> inside
+                  <literal>animals</literal></para>
+                </listitem>
+
+                <listitem>
+                  <para><literal>animal?counter</literal> is like
+                  <literal>index</literal>, but gives the 1-based index</para>
+                </listitem>
+
+                <listitem>
+                  <para><literal>animal?item_parity</literal> gives the
+                  strings <quote>odd</quote> or <quote>even</quote>, depending
+                  on the current counter parity. This is commonly used for
+                  coloring rows with alternating colors, like in
+                  <literal>&lt;td
+                  class="${animal?item_parity}Row"&gt;</literal>.</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+
+          <para>Some built-ins require parameters to specify the behavior
+          more, for example:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>animal.protected?string("Y", "N")</literal>
+              return the string <quote>Y</quote> or <quote>N</quote> depending
+              on the boolean value of
+              <literal>animal.protected</literal>.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>animal?item_cycle('lightRow',
+              'darkRow')</literal> is the more generic variant of
+              <literal>item_parity</literal> from earlier.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>fruits?join(", ")</literal>: converts the list to
+              a string by concatenating items, and inserting the parameter
+              separator between each items (like <quote>orange,
+              banana</quote>)</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>user?starts_with("J")</literal> gives boolean
+              true of false depending on if <literal>user</literal> starts
+              with the letter <quote>J</quote> or not.</para>
+            </listitem>
+          </itemizedlist>
+
+          <para>Built-in applications can be chained, like
+          <literal>fruits?join(", ")?upper_case</literal> will first convert
+          the list a to a string, then converts it to upper case. (This is
+          just like you can chain <literal>.</literal>-s (dots) too.)</para>
+
+          <para>You can find the <link linkend="ref_builtins">full set of
+          built-ins in the Reference</link>.</para>
+        </section>
+
+        <section>
+          <title>Dealing with missing variables</title>
+
+          <para>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
+          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>"visitor"</literal>. (When <literal>user</literal> isn't
+          missing, this template behaves exactly like with
+          <literal>${user}</literal>):</para>
+
+          <programlisting role="template">&lt;h1&gt;Welcome ${user<emphasis>!"visitor"</emphasis>}!&lt;/h1&gt;</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">&lt;#if <emphasis>user??</emphasis>&gt;&lt;h1&gt;Welcome ${user}!&lt;/h1&gt;&lt;/#if&gt;</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 xml:id="dgui_quickstart_template_autoescaping">
+          <title>Escaping for HTML, XML and other markup</title>
+
+          <para>Let's say the template generates HTML, and you insert values
+          with <literal>${<replaceable>...</replaceable>}</literal> that are
+          plain text (not HTML), like company names coming from a database.
+          Characters that has special meaning in HTML must be
+          <emphasis>escaped</emphasis> in such values, like if
+          <literal>name</literal> is <quote>Someone &amp; Co.</quote> then
+          <literal>${name}</literal> should print <quote>Someone
+          <emphasis>&amp;amp;</emphasis> Co.</quote>.</para>
+
+          <para>FreeMarker automatically escapes all values printed with
+          <literal>${<replaceable>...</replaceable>}</literal> <emphasis>if
+          it's properly configured</emphasis> (that's the responsibility of
+          the programmers; <link
+          linkend="pgui_config_outputformatsautoesc">see here how</link>). The
+          recommended practice is using <literal>ftlh</literal> file extension
+          to activate HTML auto-escaping, and <literal>ftlx</literal> file
+          extension to activate XML auto-escaping.</para>
+
+          <para>You can try if auto-escaping is on like
+          <literal>${"&lt;"}</literal> (for HTML or XML escaping). If it's
+          not, and the configuration won't be adjusted, add this as the very
+          first line of the template:</para>
+
+          <programlisting role="template">&lt;#ftl output_format="HTML"&gt;</programlisting>
+
+          <para>(Use <literal>"XML"</literal> instead of
+          <literal>"HTML"</literal> above if you generate XML.)</para>
+
+          <para>If the string value to print deliberately contains markup,
+          auto-escaping must be prevented like
+          <literal>${<replaceable>value</replaceable>?no_esc}</literal>.</para>
+
+          <para>You can find out much more about auto-escaping and output
+          formats <link linkend="dgui_misc_autoescaping">here...</link></para>
+
+          <note>
+            <para>The kind of automatic escaping described here requires at
+            least FreeMarker 2.3.24. If you have to use an earlier version,
+            use the deprecated <link
+            linkend="ref_directive_escape"><literal>escape</literal>
+            directive</link> instead.</para>
+          </note>
+        </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">&lt;#if cargo.weight &lt; <emphasis>100</emphasis>&gt;Light cargo&lt;/#if&gt;</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>&lt;#list <replaceable>...</replaceable>&gt;</literal>
+          sequences only. Or, the condition of <literal>&lt;#if
+          ...&gt;</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}       &lt;#-- uses mouse as a string --&gt;
+${mouse.age}   &lt;#-- uses mouse as a hash --&gt;
+${mouse.color} &lt;#-- uses mouse as a hash --&gt;</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-like (date, time, or date-time)</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>
+
+              <listitem>
+                <para><link linkend="dgui_datamodel_markupoutput">Markup
+                output</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>&lt;#if
+              loggedIn
+              &gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal> or
+              <literal>&lt;#if price ==
+              0&gt;<replaceable>...</replaceable>&lt;/#if&gt;</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-like value stores date/time related
+              data. It has three variations:</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para>Date: Like April 4, 2003. Day precision, no time of
+                  day part.</para>
+                </listitem>
+
+                <listitem>
+                  <para>Time: Like 10:19:18 PM. Millisecond precision, no date
+                  part.</para>
+                </listitem>
+
+                <listitem>
+                  <para>Date-time (sometimes called "time stamp") as April 4,
+                  2003 10:19:18 PM. Both date and time, 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, a date or a time).
+              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-like 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, booleans and date-like values. For example, while the
+          string <literal>"150"</literal> looks like the number
+          <literal>150</literal>, a string is still just arbitrary sequence of
+          characters, and you can't do arithmetic with it, can't compare it
+          with another number, etc.</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>sub variables</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 sub variables. The name is an unrestricted string. A hash
+              <emphasis>doesn't define an ordering</emphasis> for the sub
+              variables 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 sub variables. The first subvariable is associated with
+              0, the second with 1, the third to 2, and so on; the sub
+              variables are ordered. These numbers are often called the
+              <emphasis>indexes</emphasis> of the sub variables. 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 sub variables 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">&lt;@<emphasis>box</emphasis> title="Attention!"&gt;
+  Too much copy-pasting may leads to
+  maintenance headaches.
+&lt;/@<emphasis>box</emphasis>&gt;</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 purpose of it is generating a piece of the
+                output that's not just a single value, and typically involves
+                markup. The template language was designed for printing to the
+                output directly, piece by piece, as it goes though
+                <literal>list</literal> loops, <literal>if</literal>-s, etc.
+                Building up a string value in a variable then returning it is
+                much less convenient.</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 on the caller side (like for
+                example <literal>list</literal> or <literal>if</literal>
+                directives do). You just can't do that with a
+                function/method.</para>
+              </listitem>
+
+              <listitem>
+                <para>... you are using legacy escaping via the
+                <literal>escape</literal> directive (instead of <link
+                linkend="dgui_misc_autoescaping">auto-escaping</link>), and
+                the result contains markup. When you print the result with
+                <literal>${<replaceable>...</replaceable>}</literal>, the
+                markup will be escaped and thus ruined, but if it's printed by
+                a directive call
+                (<literal>&lt;@<replaceable>...</replaceable>&gt;</literal>),
+                it won't be.</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; 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 xml:id="dgui_datamodel_markupoutput">
+            <title>Markup output</title>
+
+            <indexterm>
+              <primary>markup output</primary>
+
+              <secondary>the FTL value type</secondary>
+            </indexterm>
+
+            <para>This type is related to <link
+            linkend="dgui_misc_autoescaping">auto-escaping mechanism</link>
+            introduced FreeMarker 2.3.24; you can <link
+            linkend="dgui_misc_autoescaping_movalues">read about this type
+            there</link>. But in short, this is a value that stores text
+            that's already in the output markup format (like HTML, XML, RTF,
+            etc.), and hence must not be auto-escaped.</para>
+
+            <para>Values of this type are usually produced inside the
+            templates (like with <link
+            linkend="ref_builtin_no_esc"><literal>no_esc</literal>
+            built-in</link> or <link linkend="ref_directive_assign">output
+            capturing assignments</link>), but can also be part of the
+            data-model. Such values in the data-model are useful for example
+            if you have message resources that sometimes contain the message
+            in HTML format, rather than in plain text. If the data-model uses
+            HTML markup output values for those messages instead of strings,
+            then the template author need not know which messages contain HTML
+            and which plain text, as double escaping will be avoided
+            automatically when the message is inserted with
+            <literal>${<replaceable>...</replaceable>}</literal>.</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>&lt;#--...--&gt;</primary>
+              </indexterm><indexterm>
+                <primary>#</primary>
+              </indexterm>: Comments are similar to HTML comments, but they
+            are delimited by <literal>&lt;#--</literal> and
+            <literal>--&gt;</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">&lt;html&gt;<phrase
+              role="markedInvisibleText">[BR]</phrase>
+&lt;head&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+  &lt;title&gt;Welcome!&lt;/title&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+&lt;/head&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+&lt;body&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+  <phrase role="markedComment">&lt;#-- Greet the user with his/her name --&gt;</phrase><phrase
+              role="markedInvisibleText">[BR]</phrase>
+  &lt;h1&gt;Welcome <phrase role="markedInterpolation">${user}</phrase>!&lt;/h1&gt;<phrase
+              role="markedInvisibleText">[BR]</phrase>
+  &lt;p&gt;We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
+  &lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+  <phrase role="markedFTLTag">&lt;#list animals as animal&gt;</phrase><phrase
+              role="markedInvisibleText">[BR]</phrase>
+    &lt;li&gt;<phrase role="markedInterpolation">${animal.name}</phrase> for <phrase
+              role="markedInterpolation">${animal.price}</phrase> Euros<phrase
+              role="markedInvisibleText">[BR]</phrase>
+  <phrase role="markedFTLTag">&lt;/#list&gt;</phrase><phrase
+              role="markedInvisibleText">[BR]</phrase>
+  &lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+&lt;/body&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+&lt;/html&gt;</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>&lt;#if &lt;#include
+        'foo'&gt;='bar'&gt;...&lt;/#if&gt;</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">&lt;h1&gt;Welcome <phrase
+              role="markedInterpolation">${user <phrase role="markedComment">&lt;#-- The name of user --&gt;</phrase>}</phrase>!&lt;/h1&gt;<phrase
+              role="markedInvisibleText">[BR]</phrase>
+&lt;p&gt;We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
+&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
+<phrase role="markedFTLTag">&lt;#list <phrase role="markedComment">&lt;#-- some comment... --&gt;</phrase> animals as <phrase
+                role="markedComment">&lt;#-- again... --&gt;</phrase> animal&gt;</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>&lt;#...&gt;</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>&lt;#list animals as animal&gt;</literal> and
+        <literal>&lt;/#list&gt;</literal>.</para>
+
+        <para><indexterm>
+            <primary>FTL tag</primary>
+          </indexterm>There are two kind of FTL tags:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Start-tag:
+            <literal>&lt;#<replaceable>directivename</replaceable>
+            <replaceable>parameters</replaceable>&gt;</literal></para>
+          </listitem>
+
+          <listitem>
+            <para>End-tag:
+            <literal>&lt;/#<replaceable>directivename</replaceable>&gt;</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>&lt;#if
+        <replaceable>something</replaceable>&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>,
+        but just <literal>&lt;#include
+        <replaceable>something</replaceable>&gt;</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>&lt;@mydirective
+        <replaceable>parameters</replaceable>&gt;<replaceable>...</replaceable>&lt;/@mydirective&gt;</literal>.
+        Further difference is that if the directive has no nested content, you
+        must use a tag like <literal>&lt;@mydirective
+        <replaceable>parameters</replaceable> /&gt;</literal>, similarly as in
+        XML (e.g. <literal>&lt;img <replaceable>...</replaceable>
+        /&gt;</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">&lt;ul&gt;
+<emphasis>&lt;#list animals as animal&gt;</emphasis>
+  &lt;li&gt;${animal.name} for ${animal.price} Euros
+  <emphasis>&lt;#if user == "Big Joe"&gt;</emphasis>
+     (except for you)
+<emphasis>&lt;/#list&gt;</emphasis> &lt;#-- WRONG! The "if" has to be closed first. --&gt;
+<emphasis>&lt;/#if&gt;</emphasis>
+&lt;/ul&gt;</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">&lt;#list<phrase role="markedInvisibleText">[BR]</phrase>
+  animals       as<phrase role="markedInvisibleText">[BR]</phrase>
+     animal<phrase role="markedInvisibleText">[BR]</phrase>
+&gt;</phrase><phrase role="markedInvisibleText">[BR]</phrase>
+<phrase role="markedInterpolation">${animal.name}</phrase> for <phrase
+              role="markedInterpolation">${animal.price}</phrase> Euros<phrase
+              role="markedInvisibleText">[BR]</phrase>
+<phrase role="markedFTLTag">&lt;/#list    &gt;</phrase></phrase></programlisting>
+
+        <para>You may not, however, insert white-space between the
+        <literal>&lt;</literal> or <literal>&lt;/</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>&lt;</literal> and
+          <literal>&gt;</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>&lt;if user
+          == "Big
+          Joe"&gt;<replaceable>...</replaceable>&lt;/if&gt;</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>&lt;#if
+            <replaceable>expression</replaceable>&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>.
+            The expression here must evaluate to a boolean value. For example
+            in <literal>&lt;#if 2 &lt; 3&gt;</literal> the <literal>2 &lt;
+            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>'It\'s
+                  "quoted"'</literal> or
+                  <literal>r"C:\raw\string"</literal></para>
+                </listitem>
+
+                <listitem>
+                  <para><link
+                  linkend="d

<TRUNCATED>


Mime
View raw message