Google Git
Sign in
apache / freemarker-docgen / f6eb79676240e0fa3a9154cdb825da28220fc9b9 / . / legacy-tests / build / test / 1 / app_faq.html
blob: 222b0b52231254388c396b85219958f21deabf21 [file] [log] [blame]
<!doctype html>
<!-- Generated by FreeMarker/Docgen from DocBook -->
<html lang="en" class="page-type-appendix">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>FAQ - FreeMarker Manual</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker Manual">
<meta property="og:title" content="FAQ">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/app_faq.html">
<link rel="canonical" href="http://example.com/app_faq.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338519184">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://example.com/">
<meta itemprop="name" content="FreeMarker Manual">
<!--[if lte IE 9]>
<div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
<![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="app.html"><span itemprop="name">Appendixes</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="app_faq.html"><span itemprop="name">FAQ</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li>FAQ</li><li><a href="preface.html#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</a></li></ul></div></div></div> <div class="main-content site-width">
<div class="content-wrapper">
<div id="table-of-contents-wrapper" class="col-left">
<script>var breadcrumb = ["FreeMarker Manual","Appendixes","FAQ"];</script>
<script src="toc.js?1594338519184"></script>
<script src="docgen-resources/main.min.js?1594338519184"></script>
</div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="app.html"><span>Previous</span></a><a class="paging-arrow next" href="app_install.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-chapter" id="app_faq" itemprop="headline">FAQ</h1>
</div></div> <div class="qandaset">
<ol>
<li>
<a href="#faq_jsp_vs_freemarker">
JSP versus FreeMarker?
</a>
</li>
<li>
<a href="#faq_jsp_vs_velocity">
Velocity versus FreeMarker?
</a>
</li>
<li>
<a href="#faq_picky_about_missing_vars">
Why is FreeMarker so picky about <code class="inline-code">null</code>-s
and missing variables, and what to do with it?
</a>
</li>
<li>
<a href="#faq_question_4">
The documentation writes about feature
<em>X</em>, but it seems that FreeMarker doesn&#39;t
know that, or it behaves in a different way as documented, or a
bug that was supposedly fixed is still present.
</a>
</li>
<li>
<a href="#faq_number_grouping">
Why does FreeMarker print the numbers with strange
formatting (as 1,000,000 or 1 000 000 instead of 1000000)?
</a>
</li>
<li>
<a href="#faq_number_decimal_point">
Why does FreeMarker print bad decimal and/or grouping
separator symbol (as 3.14 instead of 3,14)?
</a>
</li>
<li>
<a href="#faq_number_boolean_formatting">
Why does FreeMarker give an error when I try to print a
boolean like <code class="inline-code">${aBoolean}</code>, and how to fix
it?
</a>
</li>
<li>
<a href="#faq_alternative_syntax">
The <code class="inline-code">&lt;</code> and <code class="inline-code">&gt;</code> of
FreeMarker tags confuses my editor or the XML parser. What to
do?
</a>
</li>
<li>
<a href="#faq_legal_variable_names">
What are the legal variable names?
</a>
</li>
<li>
<a href="#faq_strange_variable_name">
How can I use variable (macro) names that contain space,
dash or other special characters?
</a>
</li>
<li>
<a href="#faq_question_11">
Why do I get &quot;java.lang.IllegalArgumentException: argument
type mismatch&quot; when I try to use <em>X</em> JSP
custom tag?
</a>
</li>
<li>
<a href="#faq_servlet_include">
How to include other resources in a way as
<code class="inline-code">jsp:include</code> does it?
</a>
</li>
<li>
<a href="#faq_question_13">
How can I get the parameters to my
plain-Java-method/<code class="inline-code">TemplateMethodModelEx</code>/<code class="inline-code">TemplateTransformModel</code>/<code class="inline-code">TemplateDirectiveModel</code>
implementation as plain
<code class="inline-code">java.lang.*</code>/<code class="inline-code">java.util.*</code>
objects?
</a>
</li>
<li>
<a href="#faq_question_14">
Why I can&#39;t use non-string key in the
<code class="inline-code">myMap[myKey]</code> expression? And what to do
now?
</a>
</li>
<li>
<a href="#faq_simple_map">
When I list the contents of a map (a hash) with
<code class="inline-code">?keys</code>/<code class="inline-code">?values</code>, I get the
<code class="inline-code">java.util.Map</code> methods mixed with the real map
entries. Of course, I only want to get the map entries.
</a>
</li>
<li>
<a href="#faq_modify_seq_and_map">
How can I modify sequences (lists) and hashes (maps) in
FreeMarker templates?
</a>
</li>
<li>
<a href="#faq_null">
What about <code class="inline-code">null</code> and the FreeMarker
template language?
</a>
</li>
<li>
<a href="#faq_question_18">
How can I use the output of a directive (macro) in
expressions (as a parameter to another directive)?
</a>
</li>
<li>
<a href="#faq_question_19">
Why do I have ``?&#39;&#39;-s in the output instead of character
<em>X</em>?
</a>
</li>
<li>
<a href="#faq_question_20">
How to retrieve values calculated in templates after
template execution done?
</a>
</li>
<li>
<a href="#faq_implement_function_or_macro_in_java">
How to implement a function or macro in Java Language
instead of in the template language?
</a>
</li>
<li>
<a href="#faq_question_22">
Why is FreeMarker logging suppressed for my
application?
</a>
</li>
<li>
<a href="#faq_question_23">
In my Servlet
based application, how do I show a nice error page instead of a
stack trace when error occurs during template processing?
</a>
</li>
<li>
<a href="#faq_question_24">
I&#39;m using a visual HTML editor that mangles template tags.
Will you change the template language syntax to accommodate my
editor?
</a>
</li>
<li>
<a href="#faq_question_25">
How fast is FreeMarker? Is it true that 2.x is slower than
1.x (FreeMarker classic)?
</a>
</li>
<li>
<a href="#faq_question_26">
How can my Java classes ask a template for information about
its structure (e.g. a list of all the variables)?
</a>
</li>
<li>
<a href="#faq_question_27">
Will you ever provide backward compatibility?
</a>
</li>
<li>
<a href="#faq_question_28">
If we distribute FreeMarker with our product, do we have to
release the source code for our product?
</a>
</li>
</ol>
<dl>
<dt class="question" id="faq_jsp_vs_freemarker">
1.&nbsp;
JSP versus FreeMarker?
</dt>
<dd class="answer">
<p>Note: JSP 1.x was really bad as an MVC template engine
because it was not made for that, so I don&#39;t deal with that here.
We compare FreeMarker with the JSP 2.0 + JSTL combo.</p>
<p>FreeMarker Pros:</p>
<ul>
<li>
<p>FreeMarker is not tied to Servlets, networking or the
Web; it is just a class library to generate text output by
merging a template with Java objects (the data-model). You can
execute templates anywhere and anytime; no HTTP request
forwarding or similar tricks needed, no Servlet environment
needed at all. Because of this you can easily integrate it
into any system.</p>
</li>
<li>
<p>No servlet specific scopes and other highly technical
things in templates. It was made for MVC from the beginning,
it focuses only on the presentation.</p>
</li>
<li>
<p>You can load the templates from anywhere; from the class
path, from a data-base, etc.</p>
</li>
<li>
<p>Locale sensitive number and date formatting by default.
Since we mostly output for a human audience all you need to do
is just write <code class="inline-code">${x}</code> rather than
<code class="inline-code">&lt;fmt:formatNumber value=&quot;${x}&quot; /&gt;</code>.
You can easily switch this behavior and output non-localized
numbers by default.</p>
</li>
<li>
<p>Easier to define ad-hoc macros and functions.</p>
</li>
<li>
<p>No sweeping errors under the carpet. Missing variables
will cause an error by default, and not silently default to
arbitrary values. Also, <code class="inline-code">null</code>-s are not
treated silently as 0/false/empty string. <a href="#faq_picky_about_missing_vars">See more about this
here...</a></p>
</li>
<li>
<p>``Object wrapping&#39;&#39;. This lets you show the objects to
templates in a customized, presentation oriented way (e.g.
<a href="xgui_imperative_learn.html">see here</a> how a
W3C DOM nodes can be seen by templates using this
technology.)</p>
</li>
<li>
<p>Macros and functions are just variables (compare it to
how JSP custom tags work), so they can be easily passed around
as parameter values, put into the data-model, ...etc, just
like any other value.</p>
</li>
<li>
<p>Easier to read, more terse syntax. For example:
<code class="inline-code">&lt;#if x&gt;...&lt;/#if&gt;</code> instead of
<code class="inline-code">&lt;c:if
test=&quot;${x}&quot;&gt;...&lt;/c:if&gt;</code></p>
</li>
<li>
<p>Virtually unnoticeable delay when visiting a page for
the first time (or after it was changed), because no expensive
compilation happens.</p>
</li>
</ul>
<p>FreeMarker Cons:</p>
<ul>
<li>
<p>Not a ``standard&#39;&#39;. There are fewer tools and IDE
integrations, fewer developers knows it and there&#39;s much less
industry support in general. (However, JSP tag libraries work
without modification in FreeMarker templates, if they are not
using <code class="inline-code">.tag</code> files.)</p>
</li>
<li>
<p>Since macros and function are just variables, incorrect
directive and parameter names and missing required parameters
can be detected only on runtime.</p>
</li>
<li>
<p>Its syntax doesn&#39;t follow the HTML/XML rules appart from
some visual similarity, which is confusing for new users.
(It&#39;s the price of the terseness...)</p>
</li>
<li>
<p>Doesn&#39;t work with JSF. (It could work technically, but
nobody has implemented that yet.)</p>
</li>
</ul>
<p>You may read this if you are considering replacing JSP with
FreeMarker: <a href="pgui_misc_servlet.html#pgui_misc_servlet_model2">Programmer&#39;s Guide/Miscellaneous/Using FreeMarker with servlets/Using FreeMarker for ``Model 2&#39;&#39;</a></p>
</dd>
<dt class="question" id="faq_jsp_vs_velocity">
2.&nbsp;
Velocity versus FreeMarker?
</dt>
<dd class="answer">
<p><a href="http://jakarta.apache.org/velocity/index.html">Velocity</a>
is a simpler, more lightweight tool. Thus, it does not address
many tasks that FreeMarker does, and its template language is less
powerful in general, but it is simpler; visit <a href="http://freemarker.org/fmVsVel.html">http://freemarker.org/fmVsVel.html</a>
for details. Currently (2005) Velocity has wider third party
support and larger user community.</p>
</dd>
<dt class="question" id="faq_picky_about_missing_vars">
3.&nbsp;
Why is FreeMarker so picky about <code class="inline-code">null</code>-s
and missing variables, and what to do with it?
</dt>
<dd class="answer">
<p>To recapitulate what&#39;s this entry is about: FreeMarker by
default treats an attempt to access a non-existent variable or a
<code class="inline-code">null</code> value (<a href="#faq_null">this two
is the same for FreeMarker</a>) as error, which aborts the
template execution.</p>
<p>First of all, you should understand the reason of being
picky. Most scripting languages and template languages are rather
forgiving with missing variables (and with
<code class="inline-code">null</code>-s), and they usually treat them as empty
string and/or 0 and/or logical false. This behavior has several
problems:</p>
<ul>
<li>
<p>It potentially hiders accidental mistakes, like a typo
in a variable name, or when the template author refers to a
variable that the programmer doesn&#39;t put into the data-model,
or for which the programmer uses a different name. Human is
prone to do such accidental mistakes, computers are not, so
missing this opportunity that the template engine can show
these errors is a bad business. Even if you very carefully
check the output of the templates during development, it is
easy to look over mistakes like <code class="inline-code">&lt;#if
hasDetp&gt;<em class="code-color">print dept
here...</em>&lt;/#if&gt;</code>, which would then
silently never print the dept of the visitor, since you have
mistyped the variable name (it should be
<code class="inline-code">hasDept</code>). Also think about maintenance,
when you later modify your application... most probably you
will not re-check templates that carefully each time.</p>
</li>
<li>
<p>Makes dangerous assumptions. The script language or
template engine knows nothing about the application domain, so
when it decides the value of something it don&#39;t know to be
0/false, it is a quite irresponsible and arbitrary thing. Just
because it is not know what&#39;s your current bank account
balance, can we just say it is $0 (and how easy it is to
accidentally write <code class="inline-code">Balance: ${balanace}</code>)?
Just because it is not known if a patient has penicillin
allergy, we can just say he/she doesn&#39;t have (and how easy it
is to accidentally write <code class="inline-code">&lt;#if
hasPenicilinAllergy&gt;<em class="code-color">Warning...</em>&lt;#else&gt;<em class="code-color">Allow...</em>&lt;/#if&gt;</code>;
there is a typo in this, if you didn&#39;t see)? Just consider the
implications of such mistakes for a moment. They can be quite
severe and troubling. Showing an error page is often better
than showing incorrect information that formally looks
good.</p>
</li>
</ul>
<p>Being not picky is mostly sweeping under the carpet in this
case (not facing with the problems), which of course most people
feels more convenient, but still... we believe that in most cases
being strict will save your time and increase your software
quality in the long run.</p>
<p>On the other hand, we recognize that there are cases where
you don&#39;t want FreeMarker to be that picky with good reason, and
there is solution for them:</p>
<ul>
<li>
<p>It&#39;s often normal that your data-model contains
<code class="inline-code">null</code>-s or have optional variables. In such
cases use <a href="dgui_template_exp.html#dgui_template_exp_missing">these
operators</a>. If you use them too often, try to rethink
your data-model, because depending on them too much is not
just results in awkward verbose templates, but increases the
probability of hiding errors and printing arbitrary incorrect
output (for the reasons described earlier).</p>
</li>
<li>
<p>On a production server you may rather want to show an
incomplete/damaged page than an error page. In this case you
can <a href="pgui_config_errorhandling.html">use other error
handler</a> than the default. Error handlers can be made
that rather skip the problematic part than abort the whole
page rendering. Note, however, that although the error
handlers don&#39;t give arbitrary default values to variables, for
pages that show critical information it&#39;s maybe still better
to show an error page. (Another feature you may interested in:
<a href="ref_directive_attempt.html">the
<code>attempt</code>/<code>recover</code>
directives</a>)</p>
</li>
</ul>
</dd>
<dt class="question" id="">
4.&nbsp;
The documentation writes about feature
<em>X</em>, but it seems that FreeMarker doesn&#39;t
know that, or it behaves in a different way as documented, or a
bug that was supposedly fixed is still present.
</dt>
<dd class="answer">
<p>Are you sure that you are using the documentation written
for the same version of FreeMarker that you actually use?
Especially, note that our online documentation is for the latest
usable FreeMarker release. You may use an older release.</p>
<p>Are you sure that the Java class loader finds the same
<code class="inline-code">freemarker.jar</code> that you expect to use? Maybe
there is an older version of <code class="inline-code">freemarker.jar</code>
around (such as in the Ant <code class="inline-code">lib</code> directory),
which has higher priority. To check this, try to print the version
number in a template with <code class="inline-code">${.version}</code>. If it
dies with ``Unknown built-in variable: version&#39;&#39; error message,
then you use a release before 2.3-final or 2.2.8, but you can
still try to get the version number in the Java code of your
application with
<code class="inline-code">Configuration.getVersionNumber()</code>. If this
method is not present either, then you are using an early
2.3-preview, or a version before 2.2.6.</p>
<p>If you think that the documentation or FreeMarker is wrong,
please report it using the bug tracker, or the mailing list, or
the forums on <a href="http://sourceforge.net/projects/freemarker/">http://sourceforge.net/projects/freemarker/</a>.
Thank you!</p>
</dd>
<dt class="question" id="faq_number_grouping">
5.&nbsp;
Why does FreeMarker print the numbers with strange
formatting (as 1,000,000 or 1 000 000 instead of 1000000)?
</dt>
<dd class="answer">
<p>FreeMarker uses the locale-sensitive number formatting
capability of the Java platform. The default number format for
your locale may uses grouping or other unwanted formatting. To
prevent this, you have to override the number format suggested by
the Java platform with the <code class="inline-code">number_format</code> <a href="pgui_config_settings.html">FreeMarker setting</a>. For
example:</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setNumberFormat(&quot;0.######&quot;); // now it will print 1000000
// where cfg is a freemarker.template.Configuration object</pre></div>
<p>Note however than humans often find it hard to read big
numbers without grouping separator. So in general it is
recommended to keep them, and in cases where the numbers are for
&#39;&#39;computer audience&#39;&#39; that is confused on the grouping separators,
use the <a href="ref_builtins_number.html#ref_builtin_c"><code>c</code>
built-in</a>. For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;a href=&quot;/shop/productdetails?id=${<strong>product.id?c</strong>}&quot;&gt;Details...&lt;/a&gt;</pre></div>
</dd>
<dt class="question" id="faq_number_decimal_point">
6.&nbsp;
Why does FreeMarker print bad decimal and/or grouping
separator symbol (as 3.14 instead of 3,14)?
</dt>
<dd class="answer">
<p>Different countries use different decimal/grouping separator
symbols. If you see incorrect symbols, then probably your locale
is not set properly. Set the default locale of the JVM or override
the default locale with the <code class="inline-code">locale</code> <a href="pgui_config_settings.html">FreeMarker setting</a>. For
example:</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setLocale(java.util.Locale.ITALY);
// where cfg is a freemarker.template.Configuration object</pre></div>
<p>However, sometimes you want to output a number not for human
audience, but for ``computer audience&#39;&#39; (like you want to print a
size in CSS), in which case you must use dot as decimal separator,
regardless of the locale (language) of the page. For that use the
<a href="ref_builtins_number.html#ref_builtin_c"><code>c</code>
built-in</a>, for example:</p>
<div class="code-wrapper"><pre class="code-block code-template">font-size: ${<strong>fontSize?c</strong>}pt;</pre></div>
</dd>
<dt class="question" id="faq_number_boolean_formatting">
7.&nbsp;
Why does FreeMarker give an error when I try to print a
boolean like <code class="inline-code">${aBoolean}</code>, and how to fix
it?
</dt>
<dd class="answer">
<p>Unlike numbers, booleans has no commonly accepted format,
not even a common format within the same page. Like when you show
on a HTML page if a product is washable, you will hardly want to
show for the visitor &quot;Washable: true&quot;, but rather &quot;Washable: yes&quot;.
So we force the template author (by <code class="inline-code">${washable}</code>
causing error) to find out with his human knowledge how the
boolean value should be shown at the given place. The common way
of formatting a boolean is like <code class="inline-code">${washable?string(&quot;yes&quot;,
&quot;no&quot;)}</code>, <code class="inline-code">${caching?string(&quot;Enabled&quot;,
&quot;Disabled&quot;)}</code>, <code class="inline-code">${heating?string(&quot;on&quot;,
&quot;off&quot;)}</code>, etc. However, for generating source code
<code class="inline-code">${washable?string(&quot;true&quot;, &quot;false&quot;)}</code> would be
very often used, so <code class="inline-code">${washable?string}</code> (i.e.,
omitting the parameter list) is equivalent with that.</p>
</dd>
<dt class="question" id="faq_alternative_syntax">
8.&nbsp;
The <code class="inline-code">&lt;</code> and <code class="inline-code">&gt;</code> of
FreeMarker tags confuses my editor or the XML parser. What to
do?
</dt>
<dd class="answer">
<p>Starting from FreeMarker 2.3.4 you can use
<code class="inline-code">[</code> and <code class="inline-code">]</code> instead of
<code class="inline-code">&lt;</code> and <code class="inline-code">&gt;</code>. For more
details <a href="dgui_misc_alternativesyntax.html">read
this...</a></p>
</dd>
<dt class="question" id="faq_legal_variable_names">
9.&nbsp;
What are the legal variable names?
</dt>
<dd class="answer">
<p>FreeMarker has no limitations regarding the characters used
in variable names, nor regarding the length of the variable names,
but for your convenience try to chose variable names that can be
used with the simple variable reference expressions (see it <a href="dgui_template_exp.html#dgui_template_exp_var_toplevel">here</a>). If you have
to choose a more extreme variable name, that&#39;s not a bid problem
either: <a href="#faq_strange_variable_name">see
here</a>.</p>
</dd>
<dt class="question" id="faq_strange_variable_name">
10.&nbsp;
How can I use variable (macro) names that contain space,
dash or other special characters?
</dt>
<dd class="answer">
<p>If you have a variable with strange name, such as
<code class="inline-code">foo-bar</code>, FreeMarker will misinterpret what do
you want when you write thing as <code class="inline-code">${foo-bar}</code>. In
this concrete case, it will believe that you want subtract the
value of <code class="inline-code">bar</code> from <code class="inline-code">foo</code>. This
FAQ entry explains how to handle situations like this.</p>
<p>First of all it should be clean that these are just
syntactical problems. FreeMarker has no limitations regarding the
characters used in variable names, nor regarding the length of the
variable names, but sometimes you need to use syntactical
tricks.</p>
<p>If you want to read the variable: Use the square bracket
syntax. An example of square bracket syntax is
<code class="inline-code">baaz[&quot;foo&quot;]</code>, which is equivalent with
<code class="inline-code">baaz.foo</code>. As the subvariable name with the
square bracket syntax is a string literal (in fact, arbitrary
expression), it let you write <code class="inline-code">baaz[&quot;foo-bar&quot;]</code>.
Now you may say that it can be used for hash subvariables only.
Yes, but top-level variables are accessible through special hash
variable <code class="inline-code">.vars</code>. For example,
<code class="inline-code">foo</code> is equivalent with
<code class="inline-code">.vars[&quot;foo&quot;]</code>. So you can also write
<code class="inline-code">.vars[&quot;foo-bar&quot;]</code>. Naturally, this trick works
with macro invocations too:
<code class="inline-code">&lt;@.vars[&quot;foo-bar&quot;]/&gt;</code></p>
<p>If you want to create or modify the variable: All directives
that let you create or modify a variable (such as
<code class="inline-code">assign</code>, <code class="inline-code">local</code>,
<code class="inline-code">global</code>, <code class="inline-code">macro</code>,
<code class="inline-code">function</code>, etc.) allows the quotation of the
destination variable name. For example, <code class="inline-code">&lt;#assign foo =
1&gt;</code> is the same as <code class="inline-code">&lt;#assign &quot;foo&quot; =
1&gt;</code>. So you can write things like <code class="inline-code">&lt;#assign
&quot;foo-bar&quot; = 1&gt;</code> and <code class="inline-code">&lt;#macro
&quot;foo-bar&quot;&gt;</code>.</p>
</dd>
<dt class="question" id="">
11.&nbsp;
Why do I get &quot;java.lang.IllegalArgumentException: argument
type mismatch&quot; when I try to use <em>X</em> JSP
custom tag?
</dt>
<dd class="answer">
<p>On JSP pages you quote all parameter (attribute) values, it
does not mater if the type of the parameter is string or boolean
or number. But since custom tags are accessible in FTL templates
as plain user-defined FTL directives, you have to use the FTL
syntax rules inside the custom tags, not the JSP rules. Thus,
according to FTL rules, you must not quote boolean and numerical
parameter values, or they are interpreted as string values, and
this will cause a type mismatch error when FreeMarker tries to
pass the value to the custom tag that expects non-string
value.</p>
<p>For example, the <code class="inline-code">flush</code> parameter to
Struts Tiles <code class="inline-code">insert</code> tag is boolean. In JSP the
correct syntax was:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;tiles:insert page=&quot;/layout.jsp&quot; <strong>flush=&quot;true&quot;</strong>/&gt;
<em>...</em></pre></div>
<p>but in FTL you should write:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;@tiles.insert page=&quot;/layout.ftl&quot; <strong>flush=true</strong>/&gt;
<em>...</em></pre></div>
<p>Also, for similar reasons, this is wrong:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;tiles:insert page=&quot;/layout.jsp&quot; <strong>flush=&quot;${needFlushing}&quot;</strong>/&gt;
<em>...</em></pre></div>
<p>and you should write:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;tiles:insert page=&quot;/layout.jsp&quot; <strong>flush=needFlushing</strong>/&gt;
<em>...</em></pre></div>
<p>(Not <code class="inline-code">flush=${needFlushing}</code>!)</p>
</dd>
<dt class="question" id="faq_servlet_include">
12.&nbsp;
How to include other resources in a way as
<code class="inline-code">jsp:include</code> does it?
</dt>
<dd class="answer">
<p>Not with <code class="inline-code">&lt;#include ...&gt;</code>, as that
just includes another FreeMarker template without involving the
Servlet container.</p>
<p>Since the inclusion method you look for is Servlet-related,
and pure FreeMarker is unaware of Servlets or even HTTP, it&#39;s the
Web Application Framework that decides if you can do this and if
so how. For example, in Struts 2 you can do this like this:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;@s.include value=&quot;/WEB-INF/just-an-example.jspf&quot; /&gt;</pre></div>
<p>If the FreeMarker support of the Web Application Framework
is based on
<code class="inline-code">freemarker.ext.servlet.FreemarkerServlet</code>, then
you can also do this (since FreeMarker 2.3.15):</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;@include_page path=&quot;/WEB-INF/just-an-example.jspf&quot; /&gt;</pre></div>
<p>but if the Web Application Framework provides its own
solution, then you may prefer that, after all it may does
something special.</p>
<p>For more information about <code class="inline-code">include_page</code>
<a href="pgui_misc_servlet.html#pgui_misc_servlet_include">read
this...</a></p>
</dd>
<dt class="question" id="">
13.&nbsp;
How can I get the parameters to my
plain-Java-method/<code class="inline-code">TemplateMethodModelEx</code>/<code class="inline-code">TemplateTransformModel</code>/<code class="inline-code">TemplateDirectiveModel</code>
implementation as plain
<code class="inline-code">java.lang.*</code>/<code class="inline-code">java.util.*</code>
objects?
</dt>
<dd class="answer">
<p>Unfortunately, there is no simple general-purpose solution
for this problem. The problem is that FreeMarker object wrapping
is very flexible, which is good when you access variables from
templates, but makes unwrapping on the Java side a tricky
question. For example, it is possible to wrap a
non-<code class="inline-code">java.util.Map</code> object as
<code class="inline-code">TemplateHashModel</code> (FTL hash variable). But
then, it can&#39;t be unwrapped to <code class="inline-code">java.util.Map</code>,
since there is no wrapped <code class="inline-code">java.util.Map</code> around
at all.</p>
<p>So what to do then? Basically there are two cases:</p>
<ul>
<li>
<p>Directives and methods that are written for presentation
purposes (like kind of ``tools&#39;&#39; for helping FreeMarker
templates) should declare their arguments as
<code class="inline-code">TemplateModel</code>-s and the more specific sub
interfaces of that. After all, the object wrapping is about
apparently transforming the data-model to something that
serves the purpose of the presentation layer, and these
methods are part of the presentation layer.</p>
</li>
<li>
<p>Methods that are not for presentation related tasks (but
for business logic and like) should be implemented as plain
Java methods, and should not use any FreeMarker specific
classes at all, since according the MVC paradigm they must be
independent of the presentation technology (FreeMarker). If
such a method is called from a template, then it is the
responsibility of the <a href="pgui_datamodel_objectWrapper.html">object wrapper</a>
to ensure the conversion of the arguments to the proper type.
If you use the <code class="inline-code">DefaultObjectWrapper</code> or the
<a href="pgui_misc_beanwrapper.html"><code>BeansWrapper</code></a>
then this will happen automatically (but be sure you are using
at least FreeMarker 2.3.3). Furthermore if you use
<code class="inline-code">BeansWrapper</code>, then the method will surely
get exactly the same instance that was earlier wrapped (as far
as it was wrapped by the
<code class="inline-code">BeansWrapper</code>).</p>
</li>
</ul>
</dd>
<dt class="question" id="">
14.&nbsp;
Why I can&#39;t use non-string key in the
<code class="inline-code">myMap[myKey]</code> expression? And what to do
now?
</dt>
<dd class="answer">
<p>The ``hash&#39;&#39; type of the FreeMarker Template Language (FTL)
is not the same as Java&#39;s <code class="inline-code">Map</code>. FTL&#39;s hash is an
associative array too, but it uses string keys exclusively. This
is because it was introduced for subvariables (as
<code class="inline-code">password</code> in <code class="inline-code">user.password</code>,
which is the same as <code class="inline-code">user[&quot;password&quot;]</code>), and
variable names are strings.</p>
<p>So FTL&#39;s hashes are not general purpose associate arrays
that could be used for looking up values with keys of arbitrary
type. FTL is presentation oriented language, and it has no feature
dedicated for that purpose. It has, however, methods. Methods are
part of the data-model, and they can do all kind of fancy
data-model related calculations, so of course you can add some
methods to the data-model for <code class="inline-code">Map</code> lookup. The
bad news is that the building of the data-model, as it&#39;s an
application specific issue, is the task of the programmers who use
FreeMarker, so it&#39;s their task to ensure that such methods are
present there to serve the template authors. (However, when
template authors need to call methods that are not about
presentation, then consider if the data-model is simple enough.
Maybe you should push some calculations back to the data-model
building phase. Ideally the data-model contains what should be
displayed, and not something that serves as the base of further
calculations.)</p>
<p>If you read the programmer&#39;s guide, then you know that
technically, the data-model is a tree of
<code class="inline-code">freemarker.template.TemplateModel</code> objects. The
building of the data-model usually (but not necessary) happens by
automatically wrapping (enclosing) plain Java objects into
<code class="inline-code">TemplateModel</code> objects. The object that does
this wrapping is the object wrapper, and it&#39;s specified when you
configure FreeMarker. FreeMarker comes with a few object wrapper
implementations out-of-the-box, and probably the most widely used
of them is <a href="pgui_misc_beanwrapper.html"><code>freemarker.ext.beans.BeansWrapper</code></a>.
If you use an instance of this as the object wrapper, then
<code class="inline-code">java.util.Map</code>-s you put into the data-model
will also act as a method, so you can write
<code class="inline-code">myMap(myKey)</code> in the template, that will
internally call <code class="inline-code">Map.get(myKey)</code>. There will be
no restriction regarding the type of <code class="inline-code">myKey</code>, as
<code class="inline-code">Map.get(Object key)</code> has no such restriction. If
the value of <code class="inline-code">myKey</code> was wrapped with
<code class="inline-code">BeansWrapper</code> or other object wrapper whose
wrapped objects support unwrapping, or it is given as literal in
the template, then the value will be automatically unwrapped to
plain Java object before the actual invocation of the
<code class="inline-code">Map.get(Object key)</code> method, so it will not be
invoked with <code class="inline-code">TemplateModel</code>-s.</p>
<p>But there still will be a problem. Java&#39;s
<code class="inline-code">Map</code> is particular about the exact class of the
key, so for numerical keys calculated inside the templates you
will have to cast them to the proper Java type, otherwise the item
will not be found. For example if you use
<code class="inline-code">Integer</code> keys in a Map, then you have to write
<code class="inline-code">${myMap.get(123?int)}</code>. This is an ugly effect
caused by that FTL&#39;s deliberately simplified type system just has
a single numerical type, while Java distinguishes a lot of
numerical types. (Ideally, in the above case, the programmers
ensure that the <code class="inline-code">get</code> method automatically
converts the key to <code class="inline-code">Integer</code>, so it&#39;s not the
problem of the template author. This can be done with wrapper
customization, but the wrapper has to know that the particular
<code class="inline-code">Map</code> object uses <code class="inline-code">Integer</code>
keys, which assumes application specific knowledge.) Note that the
casting is not needed when the key value comes directly from the
data-model (i.e. you didn&#39;t modified its value with arithmetical
caluclations in the template), including the case when it&#39;s the
return value of a method, and it was of the proper class before
wrapping, because then the result of the unwrapping will be of the
original type.</p>
</dd>
<dt class="question" id="faq_simple_map">
15.&nbsp;
When I list the contents of a map (a hash) with
<code class="inline-code">?keys</code>/<code class="inline-code">?values</code>, I get the
<code class="inline-code">java.util.Map</code> methods mixed with the real map
entries. Of course, I only want to get the map entries.
</dt>
<dd class="answer">
<p>Certainly you are using <code class="inline-code">BeansWrapper</code> as
your object wrapper, or a custom subclass of it, and the
<code class="inline-code">simpleMapWrapper</code> property of that is left to
<code class="inline-code">false</code>. Unfortunatelly, it&#39;s the default (for
backward compatibility), so you have to explicitly set it to
<code class="inline-code">true</code> where you create the object
wrapper.</p>
</dd>
<dt class="question" id="faq_modify_seq_and_map">
16.&nbsp;
How can I modify sequences (lists) and hashes (maps) in
FreeMarker templates?
</dt>
<dd class="answer">
<p>First of all, you may don&#39;t want to modify the
sequence/hash, just concatenate (add) two or more of them, which
results in a new sequence/hash, rather than modifying an existing
one. In this case use the <a href="dgui_template_exp.html#dgui_template_exp_sequenceop_cat">sequence
concatenation</a> and <a href="dgui_template_exp.html#dgui_template_exp_hashop_cat">hash concatenation
operators</a>. Also, you may use the <a href="dgui_template_exp.html#dgui_template_exp_seqenceop_slice">subsequence
operator</a> instead of removing sequence items. However, be
aware of the performance implications: these operations are fast,
but the hashes/sequences that are the result of many subseqent
applications of these operations (i.e. when you use the result of
the operation as the input of yet another operation, and so on)
will be slow to read.</p>
<p>Now if you still want to modify sequences/hashes, then read
on...</p>
<p>The FreeMarkes Template Language doesn&#39;t support the
modification of sequences/hashes. It&#39;s for displaying already
calculated things, not for calculating data. Keep templates
simple. But don&#39;t give it up, you will see some advices and tricks
bellow.</p>
<p>The best is if you can divide the work between the
data-model builder program and the template so that the template
doesn&#39;t need to modify sequences/hashes. Maybe if you rethink your
data-model, you will realize this is possible. But, seldom there
are cases where you need to modify sequences/hashes for some
complex but purely presentation related algorithms. It seldom
happens, so think twice whether that calculation (or parts of it)
rather belongs to the data-model domain than to the presentation
domain. Let&#39;s assume you are sure it belongs to the presentation
domain. For example, you want to display a keyword index on some
very smart way, whose algorithm need you to create and write some
sequence variables. Then you should do something like this (ugly
situations has ugly solutions...):</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign caculatedResults =
&#39;com.example.foo.SmartKeywordIndexHelper&#39;?new().calculate(keywords)&gt;
&lt;#-- some simple algorithms comes here, like: --&gt;
&lt;ul&gt;
&lt;#list caculatedResults as kw&gt;
&lt;li&gt;&lt;a href=&quot;${kw.link}&quot;&gt;${kw.word}&lt;/a&gt;
&lt;/#list&gt;
&lt;/ul&gt;</pre></div>
<p>That is, you move out the complex part of the presentation
task from the template into Java code. Note that it doesn&#39;t affect
the data-model, so the presentation is still kept separated from
other the other application logic. Of course the drawback is that
for this the template author will need the help of a Java
programmer, but for complex algorithms that&#39;s probably needed
anyway.</p>
<p>Now, if you still say you need to modify sequences/hashes
directly with the FreeMarker template, here are two solutions, but
please read the warning after them:</p>
<ul>
<li>
<p>You can write a <code class="inline-code">TemplateMethodModelEx</code>
and <code class="inline-code">TemplateDirectiveModel</code> implementation
that can modify certain types of sequences/hashes. Just
certain types, because
<code class="inline-code">TemplateSequenceModel</code> and
<code class="inline-code">TemplateHashModel</code> doesn&#39;t have methods for
modification, so you will need the sequence or hash to
implement some additional methods. An example of this solution
can be seen in FMPP. It allows you to do things like this
(<code class="inline-code">pp</code> stores the services provided by FMPP
for templates):</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign a = pp.newWritableSequence()&gt;
&lt;@pp.add seq=a value=&quot;red&quot; /&gt;</pre></div>
<p>The <code class="inline-code">pp.add</code> directive works only with
sequences that were created with
<code class="inline-code">pp.newWritableSequence()</code>. So for example
the template author can&#39;t modify a sequence that comes from
the data-model with this.</p>
</li>
<li>
<p>A sequence can have some methods/directives if you use a
customized wrapper (so you can <code class="inline-code">&lt;@myList.append foo
/&gt;</code>). (Also, if you use
<code class="inline-code">BeansWrapper</code> and configure it so it exposes
the public methods, you can use the Java API for variables
that are for <code class="inline-code">java.util.Map</code>-s and
<code class="inline-code">java.util.List-s</code>. Just like with Apache
Velocity.)</p>
</li>
</ul>
<p>But beware, these solutions have a problem: The <a href="dgui_template_exp.html#dgui_template_exp_sequenceop_cat">sequence
concatenation</a>, <a href="dgui_template_exp.html#dgui_template_exp_seqenceop_slice">sequence slice</a>
operator (like <code class="inline-code">seq[5..10]</code>) and
<code class="inline-code">?reverse</code> do not copy the original sequence,
just wraps it (for efficiency), so the resulting sequence will
change if the original sequence is changed later (an abnormal
aliasing effect). The same problem exists with the result of <a href="dgui_template_exp.html#dgui_template_exp_hashop_cat">hash concatenation</a>;
it just wraps the two hashes, so the resulting hash will magically
change if you modify the hashes you have added earlier. As a
work-around, after you did the above problematic operations,
either be sure you will not modify the objects that were used as
input, or create a copy of the result with a method provided by
the solution described in above two points (e.g. in FMPP you could
do <code class="inline-code">&lt;#assign b =
pp.newWritableSequence(a[5..10])&gt;</code> and
<code class="inline-code">&lt;#assign c = pp.newWritableHash(hashA +
hashB)&gt;</code>). Of course this is easy to miss... so again,
rather try to build the data-model so you will not need to modify
collections, or use a presentation task helper class as was shown
earlier.</p>
</dd>
<dt class="question" id="faq_null">
17.&nbsp;
What about <code class="inline-code">null</code> and the FreeMarker
template language?
</dt>
<dd class="answer">
<p>The FreeMarker template language doesn&#39;t know the Java
language <code class="inline-code">null</code> at all. It doesn&#39;t have
<code class="inline-code">null</code> keyword, and it can&#39;t test if something is
<code class="inline-code">null</code> or not. When it technically faces with a
<code class="inline-code">null</code>, it treats it exactly as a missing
variable. For example, both if <code class="inline-code">x</code> is
<code class="inline-code">null</code> in the data-model and if it&#39;s not present
at all, <code class="inline-code">${x!&#39;missing&#39;}</code> will print ``missing&#39;&#39;,
you can&#39;t tell the difference. Also, if for example you want to
test if a Java method has returned <code class="inline-code">null</code>, just
write something like <code class="inline-code">&lt;#if
foo.bar()??&gt;</code>.</p>
<p>You may interested in the rationale behind this. From the
viewpoint of the presentation layer a <code class="inline-code">null</code> and
non-existent thing is almost always the same. The difference
between this two is usually just a technical detail, which is
rather the result of implementation details than of the
application logic. That you can&#39;t compare something to
<code class="inline-code">null</code> (unlike in Java); it doesn&#39;t make sense to
compare something with <code class="inline-code">null</code> in a template,
since the template language doesn&#39;t do identity comparison (like
the Java <code class="inline-code">==</code> operator when you compare two
objects) but the more common sense value comparison (like Java&#39;s
<code class="inline-code">Object.equals(Object)</code>; that doesn&#39;t work with
<code class="inline-code">null</code> either). And how could FreeMarker tell if
something concrete equals with something that is missing and thus
unknown? Or if two missing (unknown) things are equal? Of course
these questions can&#39;t be answered.</p>
<p>There is at least one problem with this
<code class="inline-code">null</code>-unaware approach. When you call a Java
method from a template, you may want to pass a
<code class="inline-code">null</code> value as argument (since the method was
designed to be used in Java language, where the concept of
<code class="inline-code">null</code> is known). In this case you can exploit a
bug of FreeMarker (that we will not fix until we provide a correct
solution for passing <code class="inline-code">null</code> values to a method):
if you specify a missing variable as the argument, then it will
not cause an error, but a <code class="inline-code">null</code> will be passed
to the method instead. Like <code class="inline-code">foo.bar(nullArg)</code>
will call the <code class="inline-code">bar</code> method with
<code class="inline-code">null</code> as argument, assuming that there is no
varaible exists with ``nullArg&#39;&#39; name.</p>
</dd>
<dt class="question" id="">
18.&nbsp;
How can I use the output of a directive (macro) in
expressions (as a parameter to another directive)?
</dt>
<dd class="answer">
<p>Capture the output into a variable with the
<code class="inline-code">assign</code> or <code class="inline-code">local</code> directive.
For example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign capturedOutput&gt;&lt;@outputSomething /&gt;&lt;/#assign&gt;
&lt;@otherDirective someParam=capturedOutput /&gt;</pre></div>
</dd>
<dt class="question" id="">
19.&nbsp;
Why do I have ``?&#39;&#39;-s in the output instead of character
<em>X</em>?
</dt>
<dd class="answer">
<p>This is because the character that you want to print can&#39;t
be represented with the <a href="gloss.html#gloss.charset">charset</a> (encoding) used for the
output stream, so the Java platform (not FreeMarker) substitutes
the problematic character with question mark. In general you
should use the same charset for the output as for the template
(use the <code class="inline-code">getEncoding()</code> method of the template
object), or which is even safer, you should always use UTF-8
charset for the output. The charset used for the output stream is
not decided by FreeMarker, but by you, when you create the
<code class="inline-code">Writer</code> that you pass to the
<code class="inline-code">process</code> method of the template.</p>
<p>Example: Here I use UTF-8 charset in a servlet:</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">...
resp.setContentType(&quot;text/html; charset=utf-8&quot;);
Writer out = resp.getWriter();
...
t.process(root, out);
...</pre></div>
<p>Note that the question marks (or other substitution
characters) may be produced outside FreeMarker, in which case the
above obviously will not help. For example a bad/missconfigured
database connection or JDBC driver may bring the text already with
substitution characters in it. HTML forms are another potential
source of encoding problems. It&#39;s a good idea to print the
numerical code of the characters of the string on various places,
to see where the problem occurs first.</p>
<p>You can read more about charsets and FreeMarker <a href="pgui_misc_charset.html">here...</a></p>
</dd>
<dt class="question" id="">
20.&nbsp;
How to retrieve values calculated in templates after
template execution done?
</dt>
<dd class="answer">
<p>First of all, be sure your application is designed well:
templates should display data, and almost never calculate data. If
you are still sure you want to do it, read on...</p>
<p>When you use <code class="inline-code">&lt;#assign x = &quot;foo&quot;&gt;</code>,
then you do not actually modify the data-model (since that is
read-only, see: <a href="pgui_misc_multithreading.html">Programmer&#39;s Guide/Miscellaneous/Multithreading</a>), but
create the <code class="inline-code">x</code> variable in the runtime <a href="gloss.html#gloss.environment">environment</a> of the processing
(see <a href="pgui_misc_var.html">Programmer&#39;s Guide/Miscellaneous/Variables</a>). The problem is that this
runtime environment will be discarded when
<code class="inline-code">Template.process</code> returns, as it was created for
a single <code class="inline-code">Template.process</code> call:</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">// internally an Environment will be created, and then discarded
myTemplate.process(root, out);</pre></div>
<p>To prevent this, you can do the below, which is equivalent
with the above, except that you have chance to return the
variables created in the template:</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out);
env.process(); // process the template
TemplateModel x = env.getVariable(&quot;x&quot;); // get variable x</pre></div>
</dd>
<dt class="question" id="faq_implement_function_or_macro_in_java">
21.&nbsp;
How to implement a function or macro in Java Language
instead of in the template language?
</dt>
<dd class="answer">
<p>It&#39;s not possible (yet), but something very similar is
possible if you write a class that implements
<code class="inline-code">freemarker.template.TemplateMethodModelEx</code> or
<code class="inline-code">freemarker.template.TemplateDirectiveModel</code>
respectively, and then where you were write <code class="inline-code">&lt;#function
my
<em class="code-color">...</em>&gt;<em class="code-color">...</em>&lt;/#function&gt;</code>
or <code class="inline-code">&lt;#macro my
<em class="code-color">...</em>&gt;<em class="code-color">...</em>&lt;/#macro&gt;</code>
you write <code class="inline-code">&lt;#assign my = &quot;your.package.YourClass
&quot;?</code><a href="ref_builtins_expert.html#ref_builtin_new"><code>new</code></a><code class="inline-code">()&gt;</code>
instead. Note that using the <code class="inline-code">assign</code> directive
for this works because functions (and methods) and macros are just
plain variables in FreeMarker. (For the same reason you could also
put <code class="inline-code">TemplateMethodModelEx</code> or
<code class="inline-code">TemplateDirectiveModel</code> instances into the
data-model before calling the template, or into the shared
variable map (see:
<code class="inline-code">freemarker.template.Configuration.setSharedVariable(String,
TemplateModel)</code>) when you initialize the
application.)</p>
</dd>
<dt class="question" id="">
22.&nbsp;
Why is FreeMarker logging suppressed for my
application?
</dt>
<dd class="answer">
<p>It is because FreeMarker does not find any logging system.
To fix this, you must make available one of the following logging
systems for your application: Avalon
(<code class="inline-code">org.apache.log</code>), Log4J
(<code class="inline-code">org.apache.log4j</code>), or use J2SE 1.4 or later
(that contains <code class="inline-code">java.util.logging</code>). That is, the
class-loader used with your application must find one of the
mentioned classes.</p>
</dd>
<dt class="question" id="">
23.&nbsp;
<a name="misc.faq.niceErrorPage"></a> In my Servlet
based application, how do I show a nice error page instead of a
stack trace when error occurs during template processing?
</dt>
<dd class="answer">
<p>First of all, use <code class="inline-code">RETHROW_HANDLER</code> instead
of the default <code class="inline-code">DEBUG_HANDLER</code> (for more
information about template exception handlers <a href="pgui_config_errorhandling.html">read this...</a>). Now
FreeMarker will not print anything to the output when an error
occurs, so the control is in your hands. After you have caught the
exception of
<code class="inline-code">Template.process(<em class="code-color">...</em>)</code>
basically you can follow two strategies:</p>
<ul>
<li>
<p>Call <code class="inline-code">httpResp.isCommitted()</code>, and if
that returns <code class="inline-code">false</code>, then you call
<code class="inline-code">httpResp.reset()</code> and print a ``nice error
page&#39;&#39; for the visitor. If the return value was
<code class="inline-code">true</code>, then try to finish the page be
printing something that makes clear for the visitor that the
page generation was abruptly interrupted because of an error
on the Web server. You may have to print a lot of redundant
HTML end-tags and set colors and font size to ensure that the
error message will be actually readable in the browser window
(check the source code of the
<code class="inline-code">HTML_DEBUG_HANDLER</code> in
<code class="inline-code">src\freemarker\template\TemplateException.java</code>
to see an example).</p>
</li>
<li>
<p>Use full page buffering. This means that the
<code class="inline-code">Writer</code> doesn&#39;t send the output to the
client progressively, but buffers the whole page in the
memory. Since you provide the <code class="inline-code">Writer</code>
instance for the
<code class="inline-code">Template.process(<em class="code-color">...</em>)</code>
method, this is your responsibility, FreeMarker has nothing to
do with it. For example, you may use a
<code class="inline-code">StringWriter</code>, and if
<code class="inline-code">Template.process(<em class="code-color">...</em>)</code>
returns by throwing an exception, then ignore the content
accumulated by the <code class="inline-code">StringWriter</code>, and send
an error page instead, otherwise you print the content of
<code class="inline-code">StringWriter</code> to the output. With this
method you surely don&#39;t have to deal with partially sent
pages, but it can have negative performance implications
depending on the characteristic of the pages (for example, the
user will experience more response delay for a long page that
is generated slowly, also the server will consume more RAM).
Note that using a <code class="inline-code">StringWriter</code> is surely
not the most efficient solution, as it often reallocates its
buffer as the accumulated content grows.</p>
</li>
</ul>
</dd>
<dt class="question" id="">
24.&nbsp;
I&#39;m using a visual HTML editor that mangles template tags.
Will you change the template language syntax to accommodate my
editor?
</dt>
<dd class="answer">
<p>We won&#39;t change the standard version, because a lot of
templates depend on it.</p>
<p>Our view is that the editors that break template code are
themselves broken. A good editor should ignore, not mangle, what
it doesn&#39;t understand.</p>
<p>You maybe interested in that starting from FreeMarker 2.3.4
you can use <code class="inline-code">[</code> and <code class="inline-code">]</code> instead
of <code class="inline-code">&lt;</code> and <code class="inline-code">&gt;</code>. For more
details <a href="dgui_misc_alternativesyntax.html">read
this...</a></p>
</dd>
<dt class="question" id="">
25.&nbsp;
How fast is FreeMarker? Is it true that 2.x is slower than
1.x (FreeMarker classic)?
</dt>
<dd class="answer">
<p>First of all, don&#39;t forget that FreeMarker is only the view
rendering component in an <a href="gloss.html#gloss.MVC">MVC</a>
system. Furthermore MVC templates tend to be simple: many static
text with a few interpolations and loops and conditional block. So
it is not like PHP or Model 1 JSP; your application performance is
not affected that much by the execution time of templates.</p>
<p>FreeMarker is certainly fast enough that it will only very
rarely be a bottleneck in your application. Rather, other factors
such as the speed of the data-base operations or network bandwidth
will likely dominate. The impact of FreeMarker performance could
be noticeable only for really busy sites (say, over 30 hits per
second per server), where almost all database data is cached. If
you are finding FreeMarker slow, do make sure that the cache of
parsed templates works well
(<code class="inline-code">Configuration.getTemplate</code> be default uses
caching). Parsing a template file is a relatively costly step; in
most long-running server-side applications, you will want to parse
a template once and have it be used many times. (Note that
FreeMarker 2.1.4 and earlier versions have bugs that sometimes can
ruin caching.)</p>
<p>FreeMarker 2.1 is slower than 1.7.1. This surely depends on
your templates, but it could be slower by a factor of 2 or 3. But
again, it does not means that response time will be 2 or 3 times
slower; most FreeMarker user simply should not be able to perceive
the change in the final response time.</p>
</dd>
<dt class="question" id="">
26.&nbsp;
How can my Java classes ask a template for information about
its structure (e.g. a list of all the variables)?
</dt>
<dd class="answer">
<p>In FreeMarker 2.2, <code class="inline-code">Template</code> has an
undocumented method for examining the parsed template:
<code class="inline-code">getRootTreeNode</code>.</p>
<p>But listing all accessed variables is not possible, because
variable names can be dynamically generated from data. However,
there&#39;s a more important reason why FreeMarker doesn&#39;t support
this. The design of FreeMarker is based on the idea of a
separation between business objects and presentation objects. This
separation takes two forms:</p>
<div class="orderedlist"><ol type="1">
<li>
<p>The templates know what data to expect, but they don&#39;t
know how it&#39;s generated.</p>
</li>
<li>
<p>The business objects know what data to produce, but they
don&#39;t know how it&#39;s going to be displayed. Therefore, they
don&#39;t know anything about templates.</p>
</li>
</ol></div>
<p>Since the business objects don&#39;t rely on the templates, if
you need to use them with some other presentation system, you
won&#39;t have to rewrite your application.</p>
</dd>
<dt class="question" id="">
27.&nbsp;
Will you ever provide backward compatibility?
</dt>
<dd class="answer">
<p>FreeMarker 2.0 was a complete rewrite of FreeMarker 1.x, by
a new author. The 1.x series continues as separated project:
FreeMarker Classic. Since 2.x follows different philosophy than
1.x, 2.0x releases were immature despite the high major version
number. This caused further radical changes between 2.01 and 2.1.
As of 2.1 things were much more matured, and 2.2 is almost
backward compatible with 2.1. We hope that this tendency
continues.</p>
<p>Currently, the rule is that releases with different second
version number (as 2.1.x and 2.2.x) are not (fully) compatible.
Releases where only the third version number differs (as 2.2.1 and
2.2.6) are compatible.</p>
<p>We always provide backward compatible bugfix releases for
the released versions. So basically, you don&#39;t
<em>have</em> to switch to a new, non-backward
compatible release in an already written product. It&#39;s a something
for something situation... FreeMarker recovers faster from design
mistakes than many other projects, but the price of this is that
major releases are not backward compatible. This is admittedly not
optimal, it would be better if there are fewer design mistakes...
but, well, it is the reality.</p>
</dd>
<dt class="question" id="">
28.&nbsp;
If we distribute FreeMarker with our product, do we have to
release the source code for our product?
</dt>
<dd class="answer">
<p>No. As of 2.0, FreeMarker is released under a BSD-style
license. This means that source or binary distributions may be
made freely, and can be included in other products, whether
commercial or open source.</p>
<p>The only restrictions apply to the copyright of FreeMarker
itself, and the use of FreeMarker or its contributors as
endorsements of your own product. See the <a href="app_license.html">LICENSE</a> for further details.</p>
<p>If you use FreeMarker, we hope you&#39;ll send us a link to some
information about your product, but that&#39;s optional as
well.</p>
</dd>
</dl>
</div>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="app.html"><span>Previous</span></a><a class="paging-arrow next" href="app_install.html"><span>Next</span></a></div></div></div></div> </div>
</div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"></div><div class="col-right"><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated">
Last generated:
<time itemprop="dateModified" datetime="2020-07-09T23:48:39Z" title="Thursday, July 9, 2020 11:48:39 PM GMT">2020-07-09 23:48:39 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>