You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2015/12/30 19:11:24 UTC
[04/35] incubator-freemarker git commit: Made place for the Chinese
manual.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/book.xml b/src/manual/book.xml
deleted file mode 100644
index c561322..0000000
--- a/src/manual/book.xml
+++ /dev/null
@@ -1,37479 +0,0 @@
-<?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"><html>
-<head>
- <title>Welcome!</title>
-</head>
-<body>
- <h1>Welcome <emphasis>John Doe</emphasis>!</h1>
- <p>Our latest product:
- <a href="<emphasis>products/greenmouse.html</emphasis>"><emphasis>green mouse</emphasis></a>!
-</body>
-</html></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"><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, 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><#--</literal> and <literal>--></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><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>
-
- <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"><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 <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><#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 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"><#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, 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"><#if animals.python.price <emphasis>!=</emphasis> 0>
- Pythons are not free today!
-</#if></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"><#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 <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"><#if animals.python.price < animals.elephant.price>
- Pythons are cheaper than elephants today.
-<emphasis><#elseif animals.elephant.price < animals.python.price></emphasis>
- Elephants are cheaper than pythons today.
-<#else>
- Elephants and pythons cost the same today.
-</#if></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"><#if animals.python.protected>
- Pythons are protected animals!
-</#if></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"><p>We have these animals:
-<table border=1>
- <emphasis><#list animals as animal></emphasis>
- <tr><td>${<emphasis>animal</emphasis>.name}<td>${<emphasis>animal</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>
- <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 form of the <literal>list</literal> directive
- is:<literal> <#list <replaceable>sequence</replaceable> as
- <replaceable>loopVariable</replaceable>><replaceable>repeatThis</replaceable></#list></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><#list
- <replaceable>...</replaceable>></literal> and
- <literal></#list></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"><ul>
-<emphasis><#list misc.fruits as fruit></emphasis>
- <li>${fruit}
-<emphasis></#list></emphasis>
-</ul></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><ul></ul></literal> instead of just nothing.
- To avoid that, you can use this form of
- <literal>list</literal>:</para>
-
- <programlisting role="template"><#list misc.fruits>
- <ul>
- <emphasis> <#items as fruit></emphasis>
- <li>${fruit}
- <emphasis> </#items></emphasis>
- </ul>
-</#list></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"><p>Fruits: <#list misc.fruits as fruit>${fruit}<emphasis><#sep>, </emphasis></#list></programlisting>
-
- <programlisting role="output"><p>Fruits: orange, banana</programlisting>
-
- <para>The section covered by <literal>sep</literal> (which we
- could be written like this too:
- <literal><replaceable>...</replaceable><#sep>,
- </#sep></#list></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"><p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, <emphasis><#else>None</emphasis></#list></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"><p>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"><#list misc.fruits>
- <p>Fruits:
- <ul>
- <#items as fruit>
- <li>${fruit}<#sep> and</#sep>
- </#items>
- </ul>
-<#else>
- <p>We have no fruits.
-</#list></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"><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>
-
- <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><#list animals as animal></emphasis>
- <div<emphasis><#if animal.protected></emphasis><emphasis> </emphasis>class="protected"<emphasis></#if></emphasis>>
- ${animal.name} for ${animal.price} Euros
- </div>
-<emphasis></#list></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><#list animals as
- animal></literal> and the corresponding
- <literal></#list></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><td
- class="${animal?item_parity}Row"></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"><h1>Welcome ${user<emphasis>!"visitor"</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 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 & Co.</quote> then
- <literal>${name}</literal> should print <quote>Someone
- <emphasis>&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>${"<"}</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"><#ftl output_format="HTML"></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"><#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-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><#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-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"><@<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 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><@<replaceable>...</replaceable>></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><#--...--></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 animal></phrase><phrase
- role="markedInvisibleText">[BR]</phrase>
- <li><phrase role="markedInterpolation">${animal.name}</phrase> for <phrase
- role="markedInterpolation">${animal.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> animal></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 animal></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 animal></emphasis>
- <li>${animal.name} for ${animal.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>
- animal<phrase role="markedInvisibleText">[BR]</phrase>
-></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"></#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>'It\'s
- "quoted"'</literal> or
- <literal>r"C:\raw\string"</literal></para>
- </listitem>
-
- <listitem>
- <para><link
- linkend="dgui_template_exp_dir
<TRUNCATED>