docs/pgui_config_settings.html - freemarker-site - Git at Google

 <!doctype html>
 <!-- Generated by FreeMarker/Docgen from DocBook -->
 <html lang="en" class="page-type-section">
 <head prefix="og: http://ogp.me/ns#">
 <meta charset="utf-8">
 <title>Settings - Apache 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="Apache FreeMarker Manual">
 <meta property="og:title" content="Settings">
 <meta property="og:locale" content="en_US">
 <meta property="og:url" content="https://freemarker.apache.org/docs/pgui_config_settings.html">
 <link rel="canonical" href="https://freemarker.apache.org/docs/pgui_config_settings.html">
 <link rel="icon" href="favicon.png" type="image/png">
 <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono">
 <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859">
 <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script>
 </head>
 <body itemscope itemtype="https://schema.org/Code">
     <meta itemprop="url" content="https://freemarker.apache.org/docs/">
     <meta itemprop="name" content="Apache FreeMarker Manual">

   <!--[if lte IE 9]>
   <div class="oldBrowserWarning" style="display: block">
     Unsupported web browser - Use a modern browser to view this website!
   </div>
   <![endif]-->  <div class="oldBrowserWarning">
     Unsupported web browser - Use a modern browser to view this website!
   </div>
 <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div>          <div class="logo">
 <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a>          </div>
 <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row">  <div class="breadcrumbs">
 <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">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">Programmer&#39;s Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config.html"><span itemprop="name">The Configuration</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config_settings.html"><span itemprop="name">Settings</span></a></li></ul>  </div>
 <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</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 = ["Apache FreeMarker Manual","Programmer\'s Guide","The Configuration","Settings"];</script>
       <script src="toc.js?1707770044859"></script>
       <script src="docgen-resources/main.min.js?1707770044859"></script>
   </div>
 <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.html"><span>Next</span></a></div><div class="title-wrapper">
 <h1 class="content-header header-section1" id="pgui_config_settings" itemprop="headline">Settings</h1>
 </div></div><p><strong>Settings</strong> are named values that
         influence the behavior of FreeMarker. Examples of settings are:
         <code class="inline-code">locale</code>, <code class="inline-code">number_format</code>,
         <code class="inline-code">default_encoding</code>,
         <code class="inline-code">template_exception_handler</code>. The full list of
         settings can be found in the <a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Java API documentation of
         <code class="inline-code">Configuration.setSetting(...)</code></a>.</p><p>The settings coming from the <code class="inline-code">Configuration</code>
         can be overridden in a <code class="inline-code">Template</code> instance. For
         example, if you set the <code class="inline-code">locale</code> setting to
         <code class="inline-code">&quot;en_US&quot;</code> in the configuration, then the
         <code class="inline-code">locale</code> in all templates that use this configuration
         will be <code class="inline-code">&quot;en_US&quot;</code>, except in templates where the
         <code class="inline-code">locale</code> was explicitly specified differently (see
         <a href="ref_directive_include.html#ref_directive_include_localized">localization</a>).
         Thus, the setting values in the <code class="inline-code">Configuration</code> serve
         as defaults that can be overridden in a per template manner. The value
         coming from the <code class="inline-code">Configuration</code> instance or
         <code class="inline-code">Template</code> instance can be further overridden for a
         single <code class="inline-code">Template.process</code> call. For each such call a
         <code class="inline-code">freemarker.core.Environment</code> object is created
         internally that holds the runtime environment of the template
         processing, including the setting values that were overridden on that
         level. The values stored there can even be changed during the template
         processing, so a template can set settings itself, like switching
         <code class="inline-code">locale</code> at the middle of the ongoing
         processing.</p><p>This can be imagined as 3 layers
         (<code class="inline-code">Configuration</code>, <code class="inline-code">Template</code>,
         <code class="inline-code">Environment</code>) of settings, where the topmost layer
         that contains the value for a certain setting provides the effective
         value of that setting. For example (settings A to F are just imaginary
         settings for this example):</p>  <div class="table-responsive">
     <table class="table">


           <thead>
             <tr>
               <th align="left"></th>


               <th align="center">Setting A</th>


               <th align="center">Setting B</th>


               <th align="center">Setting C</th>


               <th align="center">Setting D</th>


               <th align="center">Setting E</th>


               <th align="center">Setting F</th>

             </tr>

           </thead>


           <tbody>
             <tr>
               <td align="left">Layer 3: <code class="inline-code">Environment</code></td>


               <td align="center">1</td>


               <td align="center">-</td>


               <td align="center">-</td>


               <td align="center">1</td>


               <td align="center">-</td>


               <td align="center">-</td>

             </tr>


             <tr>
               <td align="left">Layer 2: <code class="inline-code">Template</code></td>


               <td align="center">2</td>


               <td align="center">2</td>


               <td align="center">-</td>


               <td align="center">-</td>


               <td align="center">2</td>


               <td align="center">-</td>

             </tr>


             <tr>
               <td align="left">Layer 1: <code class="inline-code">Configuration</code></td>


               <td align="center">3</td>


               <td align="center">3</td>


               <td align="center">3</td>


               <td align="center">3</td>


               <td align="center">-</td>


               <td align="center">-</td>

             </tr>

           </tbody>

             </table>
   </div>
 <p>The effective value of settings will be: A = 1, B = 2, C = 3, D
         = 1, E = 2. The F setting is probably <code class="inline-code">null</code>, or it
         throws exception when you try to get it.</p><p>Let&#39;s see exactly how to set settings:</p><ul>
           <li>
             <p><code class="inline-code">Configuration</code> layer: In principle you set
             the settings with the setter methods of the
             <code class="inline-code">Configuration</code> object, fore example:</p>


     <div class="code-block role-unspecified">
 <pre class="code-block-body">Configuration myCfg = new Configuration(Configuration.VERSION_2_3_27);
 myCfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
 myCfg.setDefaultEncoding(&quot;UTF-8&quot;);
 DefaultObjectWrapperBuilder owb = new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_27);
 owb.setForceLegacyNonListCollections(false);
 owb.setDefaultDateType(TemplateDateModel.DATETIME);
 myCfg.setObjectWrapper(owb.build());</pre>    </div>


             <p>You do this before you start to actually use the
             <code class="inline-code">Configuration</code> object (typically, when you
             initialize the application); you should treat the object as
             read-only after that.</p>

             <p>In practice, in most frameworks you have to specify the
             settings in some kind of framework-specific configuration file
             that require specifying settings as <code class="inline-code">String</code>
             name-value pairs (like in a <code class="inline-code">.properties</code> file).
             In that case the authors of the frameworks most probably use the
             <code class="inline-code">Confguration.setSetting(String name, String
             value)</code> method; see available setting names and the
             format of the values in the <a href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-">API
             documentation of <code>setSetting</code></a>. Example for
             Spring Framework:</p>


     <div class="code-block role-unspecified">
 <pre class="code-block-body">&lt;bean id=&quot;freemarkerConfig&quot;
     class=&quot;org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer&quot;&gt;
   &lt;property name=&quot;freemarkerSettings&quot;&gt;
     &lt;props&gt;
       &lt;prop key=&quot;incompatible_improvements&quot;&gt;2.3.27&lt;/prop&gt;
       &lt;prop key=&quot;template_exception_handler&quot;&gt;rethrow&lt;/prop&gt;
       &lt;prop key=&quot;default_encoding&quot;&gt;UTF-8&lt;/prop&gt;
       &lt;prop key=&quot;object_wrapper&quot;&gt;
         DefaultObjectWrapper(
                 2.3.27,
                 forceLegacyNonListCollections = false,
                 defaultDateType = freemarker.template.TemplateDateModel.DATETIME)
       &lt;/prop&gt;
     &lt;/props&gt;
   &lt;/property&gt;
 &lt;/bean&gt;</pre>    </div>


             <p>Here&#39;s the same when configuring FreeMarker for Struts,
             which looks for a <code class="inline-code">freemarker.properties</code> in the
             classpath:</p>


     <div class="code-block role-unspecified">
 <pre class="code-block-body">incompatible_improvements=2.3.27
 template_exception_handler=rethrow
 default_encoding=UTF-8
 object_wrapper=DefaultObjectWrapper( \
         2.3.27, \
         forceLegacyNonListCollections = false, \
         defaultDateType = freemarker.template.TemplateDateModel.DATETIME)</pre>    </div>


             <p>As demonstrated above with
             <code class="inline-code">object_wrapper</code>, some settings can accept quite
             complex values, which can be used to instantiate objects of
             arbitrary classes and set their properties. Still, configuring
             with <code class="inline-code">String</code> key-value pairs is limited compared
             to directly using the Java API, so in some cases you have to find
             a way to do this in Java.</p>
           </li>

           <li>
             <p><code class="inline-code">Template</code> layer: Settings on individual
             templates are normally set by <a href="pgui_config_templateconfigurations.html">template
             configurations (see them in their own chapter)</a>, which
             basically associate setting assignments to template name (template
             path) patterns. There&#39;s a deviation from this approach with the
             <code class="inline-code">locale</code> setting, because that you can also
             specify to <code class="inline-code">Configuration.getTemplate(...)</code> as
             parameter, to get the template for the requested locale (so called
             localized lookup).</p>

               <div class="callout warning">
     <strong class="callout-label">Warning!</strong>

               <p>You should never set settings directly on the
               <code class="inline-code">Template</code> object that you get from
               <code class="inline-code">Configuration.getTemplate(...)</code>! Those objects
               should be treated as already initialized and read-only.</p>
               </div>


             <p>When a template includes or imports another template, most
             of the settings (like <code class="inline-code">locale</code>,
             <code class="inline-code">number_format</code>, etc.) will remain those
             specified by the top-level template. The exceptions are the
             settings that affect the parsing of the template (like
             <code class="inline-code">tag_syntax</code>,
             <code class="inline-code">whitespace_stripping</code>, etc.), as these are not
             inherited from the top-level template, instead each template
             always uses its own values, no mater how it was invoked.</p>

               <div class="callout note">
     <strong class="callout-label">Note:</strong>

               <p>If you are going to use template layer settings, you
               should set <a href="pgui_config_incompatible_improvements.html">the
               <code>incompatible_improvements</code> setting</a> to
               2.3.22 or higher, to avoid some confusing legacy bugs.</p>
               </div>

           </li>

           <li>
             <p><code class="inline-code">Environment </code>layer: There are two ways of
             doing it:</p>

             <ul>
               <li>
                 <p>With Java API: Use the setter methods of the
                 <code class="inline-code">Environment</code> object. You may run into the
                 API problem that <code class="inline-code">myTemplate.process(...)</code>
                 both creates the <code class="inline-code">Environment</code> object
                 internally and processes the template, so you have no
                 opportunity to adjust the <code class="inline-code">Environment</code> in
                 between. The solution is that those two steps can be separated
                 like this:</p>


     <div class="code-block role-unspecified">
 <pre class="code-block-body">Environment env = myTemplate.createProcessingEnvironment(root, out);
 env.setLocale(java.util.Locale.ITALY);
 env.setNumberFormat(&quot;0.####&quot;);
 env.process();  // process the template</pre>    </div>

               </li>

               <li>
                 <p>Directly in the Template (considered as bad style,
                 usually): Use the <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
                 directive</a>, for example:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">&lt;#setting locale=&quot;it_IT&quot;&gt;
 &lt;#setting number_format=&quot;0.####&quot;&gt;</pre>    </div>

               </li>
             </ul>

             <p>There are no restriction regarding when can you change the
             settings in this layer.</p>
           </li>
         </ul><p>To see the list of supported settings and their meaning, please
         read the following parts of the FreeMarker Java API
         documentation:</p><ul>
           <li>
             <p>Setter methods of
             <code class="inline-code">freemarker.core.Configurable</code> for the settings
             that are in all three layers</p>
           </li>

           <li>
             <p>Setter methods of
             <code class="inline-code">freemarker.template.Configuration</code> for the
             settings that are available only in the
             <code class="inline-code">Configuration</code> layer</p>
           </li>

           <li>
             <p><code class="inline-code">freemarker.core.Configurable.setSetting(String,
             String)</code> for settings that are available in all three
             layers and are writable with <code class="inline-code">String</code> key-value
             pairs.</p>
           </li>

           <li>
             <p><code class="inline-code">freemarker.template.Configuration.setSetting(String,
             String)</code> for settings that are available only in the
             <code class="inline-code">Configuration</code> layer and are writable with
             <code class="inline-code">String</code> key-value pairs.</p>
           </li>
         </ul><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.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 class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><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="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p>
 <p class="copyright">
 © <span itemprop="copyrightYear">1999</span>–2024
 <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p>
 </div></div></div></body>
 </html>
	<!doctype html>
	<!-- Generated by FreeMarker/Docgen from DocBook -->
	<html lang="en" class="page-type-section">
	<head prefix="og: http://ogp.me/ns#">
	<meta charset="utf-8">
	<title>Settings - Apache 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="Apache FreeMarker Manual">
	<meta property="og:title" content="Settings">
	<meta property="og:locale" content="en_US">
	<meta property="og:url" content="https://freemarker.apache.org/docs/pgui_config_settings.html">
	<link rel="canonical" href="https://freemarker.apache.org/docs/pgui_config_settings.html">
	<link rel="icon" href="favicon.png" type="image/png">
	<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300\|Droid+Sans+Mono">
	<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859">
	<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script>
	</head>
	<body itemscope itemtype="https://schema.org/Code">
	<meta itemprop="url" content="https://freemarker.apache.org/docs/">
	<meta itemprop="name" content="Apache FreeMarker Manual">

	<!--[if lte IE 9]>
	<div class="oldBrowserWarning" style="display: block">
	Unsupported web browser - Use a modern browser to view this website!
	</div>
	<![endif]--> <div class="oldBrowserWarning">
	Unsupported web browser - Use a modern browser to view this website!
	</div>
	<div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo">
	<a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div>
	<ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs">
	<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">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">Programmer's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config.html"><span itemprop="name">The Configuration</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config_settings.html"><span itemprop="name">Settings</span></a></li></ul> </div>
	<div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</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 = ["Apache FreeMarker Manual","Programmer\'s Guide","The Configuration","Settings"];</script>
	<script src="toc.js?1707770044859"></script>
	<script src="docgen-resources/main.min.js?1707770044859"></script>
	</div>
	<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.html"><span>Next</span></a></div><div class="title-wrapper">
	<h1 class="content-header header-section1" id="pgui_config_settings" itemprop="headline">Settings</h1>
	</div></div><p><strong>Settings</strong> are named values that
	influence the behavior of FreeMarker. Examples of settings are:
	<code class="inline-code">locale</code>, <code class="inline-code">number_format</code>,
	<code class="inline-code">default_encoding</code>,
	<code class="inline-code">template_exception_handler</code>. The full list of
	settings can be found in the <a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Java API documentation of
	<code class="inline-code">Configuration.setSetting(...)</code></a>.</p><p>The settings coming from the <code class="inline-code">Configuration</code>
	can be overridden in a <code class="inline-code">Template</code> instance. For
	example, if you set the <code class="inline-code">locale</code> setting to
	<code class="inline-code">"en_US"</code> in the configuration, then the
	<code class="inline-code">locale</code> in all templates that use this configuration
	will be <code class="inline-code">"en_US"</code>, except in templates where the
	<code class="inline-code">locale</code> was explicitly specified differently (see
	<a href="ref_directive_include.html#ref_directive_include_localized">localization</a>).
	Thus, the setting values in the <code class="inline-code">Configuration</code> serve
	as defaults that can be overridden in a per template manner. The value
	coming from the <code class="inline-code">Configuration</code> instance or
	<code class="inline-code">Template</code> instance can be further overridden for a
	single <code class="inline-code">Template.process</code> call. For each such call a
	<code class="inline-code">freemarker.core.Environment</code> object is created
	internally that holds the runtime environment of the template
	processing, including the setting values that were overridden on that
	level. The values stored there can even be changed during the template
	processing, so a template can set settings itself, like switching
	<code class="inline-code">locale</code> at the middle of the ongoing
	processing.</p><p>This can be imagined as 3 layers
	(<code class="inline-code">Configuration</code>, <code class="inline-code">Template</code>,
	<code class="inline-code">Environment</code>) of settings, where the topmost layer
	that contains the value for a certain setting provides the effective
	value of that setting. For example (settings A to F are just imaginary
	settings for this example):</p> <div class="table-responsive">
	<table class="table">





	<thead>
	<tr>
	<th align="left"></th>


	<th align="center">Setting A</th>


	<th align="center">Setting B</th>


	<th align="center">Setting C</th>


	<th align="center">Setting D</th>


	<th align="center">Setting E</th>


	<th align="center">Setting F</th>

	</tr>

	</thead>


	<tbody>
	<tr>
	<td align="left">Layer 3: <code class="inline-code">Environment</code></td>


	<td align="center">1</td>


	<td align="center">-</td>


	<td align="center">-</td>


	<td align="center">1</td>


	<td align="center">-</td>


	<td align="center">-</td>

	</tr>


	<tr>
	<td align="left">Layer 2: <code class="inline-code">Template</code></td>


	<td align="center">2</td>


	<td align="center">2</td>


	<td align="center">-</td>


	<td align="center">-</td>


	<td align="center">2</td>


	<td align="center">-</td>

	</tr>


	<tr>
	<td align="left">Layer 1: <code class="inline-code">Configuration</code></td>


	<td align="center">3</td>


	<td align="center">3</td>


	<td align="center">3</td>


	<td align="center">3</td>


	<td align="center">-</td>


	<td align="center">-</td>

	</tr>

	</tbody>

	</table>
	</div>
	<p>The effective value of settings will be: A = 1, B = 2, C = 3, D
	= 1, E = 2. The F setting is probably <code class="inline-code">null</code>, or it
	throws exception when you try to get it.</p><p>Let's see exactly how to set settings:</p><ul>
	<li>
	<p><code class="inline-code">Configuration</code> layer: In principle you set
	the settings with the setter methods of the
	<code class="inline-code">Configuration</code> object, fore example:</p>



	<div class="code-block role-unspecified">
	<pre class="code-block-body">Configuration myCfg = new Configuration(Configuration.VERSION_2_3_27);
	myCfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
	myCfg.setDefaultEncoding("UTF-8");
	DefaultObjectWrapperBuilder owb = new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_27);
	owb.setForceLegacyNonListCollections(false);
	owb.setDefaultDateType(TemplateDateModel.DATETIME);
	myCfg.setObjectWrapper(owb.build());</pre> </div>


	<p>You do this before you start to actually use the
	<code class="inline-code">Configuration</code> object (typically, when you
	initialize the application); you should treat the object as
	read-only after that.</p>

	<p>In practice, in most frameworks you have to specify the
	settings in some kind of framework-specific configuration file
	that require specifying settings as <code class="inline-code">String</code>
	name-value pairs (like in a <code class="inline-code">.properties</code> file).
	In that case the authors of the frameworks most probably use the
	<code class="inline-code">Confguration.setSetting(String name, String
	value)</code> method; see available setting names and the
	format of the values in the <a href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-">API
	documentation of <code>setSetting</code></a>. Example for
	Spring Framework:</p>



	<div class="code-block role-unspecified">
	<pre class="code-block-body"><bean id="freemarkerConfig"
	class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
	<property name="freemarkerSettings">
	<props>
	<prop key="incompatible_improvements">2.3.27</prop>
	<prop key="template_exception_handler">rethrow</prop>
	<prop key="default_encoding">UTF-8</prop>
	<prop key="object_wrapper">
	DefaultObjectWrapper(
	2.3.27,
	forceLegacyNonListCollections = false,
	defaultDateType = freemarker.template.TemplateDateModel.DATETIME)
	</prop>
	</props>
	</property>
	</bean></pre> </div>


	<p>Here's the same when configuring FreeMarker for Struts,
	which looks for a <code class="inline-code">freemarker.properties</code> in the
	classpath:</p>



	<div class="code-block role-unspecified">
	<pre class="code-block-body">incompatible_improvements=2.3.27
	template_exception_handler=rethrow
	default_encoding=UTF-8
	object_wrapper=DefaultObjectWrapper( \
	2.3.27, \
	forceLegacyNonListCollections = false, \
	defaultDateType = freemarker.template.TemplateDateModel.DATETIME)</pre> </div>


	<p>As demonstrated above with
	<code class="inline-code">object_wrapper</code>, some settings can accept quite
	complex values, which can be used to instantiate objects of
	arbitrary classes and set their properties. Still, configuring
	with <code class="inline-code">String</code> key-value pairs is limited compared
	to directly using the Java API, so in some cases you have to find
	a way to do this in Java.</p>
	</li>

	<li>
	<p><code class="inline-code">Template</code> layer: Settings on individual
	templates are normally set by <a href="pgui_config_templateconfigurations.html">template
	configurations (see them in their own chapter)</a>, which
	basically associate setting assignments to template name (template
	path) patterns. There's a deviation from this approach with the
	<code class="inline-code">locale</code> setting, because that you can also
	specify to <code class="inline-code">Configuration.getTemplate(...)</code> as
	parameter, to get the template for the requested locale (so called
	localized lookup).</p>

	<div class="callout warning">
	<strong class="callout-label">Warning!</strong>

	<p>You should never set settings directly on the
	<code class="inline-code">Template</code> object that you get from
	<code class="inline-code">Configuration.getTemplate(...)</code>! Those objects
	should be treated as already initialized and read-only.</p>
	</div>


	<p>When a template includes or imports another template, most
	of the settings (like <code class="inline-code">locale</code>,
	<code class="inline-code">number_format</code>, etc.) will remain those
	specified by the top-level template. The exceptions are the
	settings that affect the parsing of the template (like
	<code class="inline-code">tag_syntax</code>,
	<code class="inline-code">whitespace_stripping</code>, etc.), as these are not
	inherited from the top-level template, instead each template
	always uses its own values, no mater how it was invoked.</p>

	<div class="callout note">
	<strong class="callout-label">Note:</strong>

	<p>If you are going to use template layer settings, you
	should set <a href="pgui_config_incompatible_improvements.html">the
	<code>incompatible_improvements</code> setting</a> to
	2.3.22 or higher, to avoid some confusing legacy bugs.</p>
	</div>

	</li>

	<li>
	<p><code class="inline-code">Environment </code>layer: There are two ways of
	doing it:</p>

	<ul>
	<li>
	<p>With Java API: Use the setter methods of the
	<code class="inline-code">Environment</code> object. You may run into the
	API problem that <code class="inline-code">myTemplate.process(...)</code>
	both creates the <code class="inline-code">Environment</code> object
	internally and processes the template, so you have no
	opportunity to adjust the <code class="inline-code">Environment</code> in
	between. The solution is that those two steps can be separated
	like this:</p>



	<div class="code-block role-unspecified">
	<pre class="code-block-body">Environment env = myTemplate.createProcessingEnvironment(root, out);
	env.setLocale(java.util.Locale.ITALY);
	env.setNumberFormat("0.####");
	env.process(); // process the template</pre> </div>

	</li>

	<li>
	<p>Directly in the Template (considered as bad style,
	usually): Use the <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
	directive</a>, for example:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><#setting locale="it_IT">
	<#setting number_format="0.####"></pre> </div>

	</li>
	</ul>

	<p>There are no restriction regarding when can you change the
	settings in this layer.</p>
	</li>
	</ul><p>To see the list of supported settings and their meaning, please
	read the following parts of the FreeMarker Java API
	documentation:</p><ul>
	<li>
	<p>Setter methods of
	<code class="inline-code">freemarker.core.Configurable</code> for the settings
	that are in all three layers</p>
	</li>

	<li>
	<p>Setter methods of
	<code class="inline-code">freemarker.template.Configuration</code> for the
	settings that are available only in the
	<code class="inline-code">Configuration</code> layer</p>
	</li>

	<li>
	<p><code class="inline-code">freemarker.core.Configurable.setSetting(String,
	String)</code> for settings that are available in all three
	layers and are writable with <code class="inline-code">String</code> key-value
	pairs.</p>
	</li>

	<li>
	<p><code class="inline-code">freemarker.template.Configuration.setSetting(String,
	String)</code> for settings that are available only in the
	<code class="inline-code">Configuration</code> layer and are writable with
	<code class="inline-code">String</code> key-value pairs.</p>
	</li>
	</ul><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.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 class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><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="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p>
	<p class="copyright">
	© <span itemprop="copyrightYear">1999</span>–2024
	<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p>
	</div></div></div></body>
	</html>