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/20 14:06:08 UTC
[2/5] incubator-freemarker git commit: Made place for the Chinese
manual.
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"><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="d
<TRUNCATED>