| <!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>Template configurations - 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="Template configurations"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/pgui_config_templateconfigurations.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/pgui_config_templateconfigurations.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_templateconfigurations.html"><span itemprop="name">Template configurations</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","Template configurations"];</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_errorhandling.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_outputformatsautoesc.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="pgui_config_templateconfigurations" itemprop="headline">Template configurations</h1> |
| </div></div><p>"Template configurations" refers to the |
| <code class="inline-code">template_configurations</code> setting of |
| <code class="inline-code">Configuration</code> |
| (<code class="inline-code">Configuration.setTemplateConfigurations(<em class="code-color">...</em>)</code>). |
| This setting lets you override individual settings coming from the |
| common <code class="inline-code">Configuration</code> object, depending on the name |
| (path) of the template.</p><p>It's important to understand, however, that this setting only |
| has effect if you get templates with |
| <code class="inline-code">Configuration.getTemplate(<em class="code-color">...</em>)</code>, |
| not when you create templates directly with the |
| <code class="inline-code">Template</code> constructors. In that case it's up to you |
| to invoke this mechanism (see <code class="inline-code">TemplateCache</code> source |
| code as an example).</p><p>You will use these kind of objects to declare your template |
| configuration rules:</p><ul> |
| <li> |
| <p><code class="inline-code">TemplateConfiguration</code>-s: These store the |
| actual setting assignments that you want to apply. For example, |
| this <code class="inline-code">TemplateConfiguration</code> will set the |
| encoding and the output format of the matched template (and leave |
| all other settings of it alone):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">TemplateConfiguration tcUTF8XML = new TemplateConfiguration(); |
| tc.setEncoding("utf-8"); |
| tc.setOutputFormat(XMLOutputFormat.INSTANCE);</pre> </div> |
| |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateSourceMatcher</code> (abstract) |
| subclasses: These define a rule that matches templates based on |
| their source name (their source path; as in |
| <code class="inline-code">Template.getSourceName()</code>), and possibly on |
| other <code class="inline-code">TemplateLoader</code>-dependent properties. For |
| example, <code class="inline-code">new FileExtensionMatcher("xml")</code> |
| matches templates that has <code class="inline-code">xml</code> file extension. |
| See all the subclasses in the Java API documentation.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateConfigurationFactory</code>-es: This is |
| what connects <code class="inline-code">TemplateConfiguration</code>-s and |
| <code class="inline-code">TemplateSourceMatcher</code>-s together. This is the |
| Java type of the <code class="inline-code">template_configurations</code> |
| setting. See the examples below for more.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_47">Example 1</h2> |
| |
| |
| <p>This setup combines our earlier two example objects with a |
| <code class="inline-code">ConditionalTemplateConfigurationFactory</code>, causing |
| all templates with <code class="inline-code">xml</code> extension to get UTF-8 |
| encoding and XML output format:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">cfg.setTemplateConfigurations( |
| new ConditionalTemplateConfigurationFactory( |
| new FileExtensionMatcher("xml"), |
| tcUTF8XML));</pre> </div> |
| |
| |
| <p>The same configuring is also doable if you don't have access |
| to the configuring Java code, but only to a Java |
| <code class="inline-code">*.properties</code> file, or other kind of string-string |
| key value pairs (the <code class="inline-code">\</code>-s are prescribed by the |
| Java Properties file format for multi-line values, so omit them |
| elsewhere):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">templateConfigurations = \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileExtensionMatcher("xml"), \ |
| TemplateConfiguration( \ |
| encoding = "utf-8", \ |
| outputFormat = XMLOutputFormat() \ |
| ) \ |
| )</pre> </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_48">Example 2</h2> |
| |
| |
| <p>Let's say you only need to handle templates in the |
| <code class="inline-code">mail</code> directory specially, other templates can use |
| the setting coming from the shared <code class="inline-code">Configuration</code> |
| singleton. The names of templates there must contain |
| <code class="inline-code">".subject."</code> or <code class="inline-code">".body."</code>. |
| Subject templates must get <code class="inline-code">plainText</code> output |
| format, while body templates must get <code class="inline-code">HTML</code> output |
| format. So we have to make a choice here, and that's when you need a |
| <code class="inline-code">FirstMatchTemplateConfigurationFactory</code>.</p> |
| |
| <p>Assuming <code class="inline-code">cfg</code> stores the shared |
| <code class="inline-code">Configuration</code> singleton, you set this up like |
| this:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">TemplateConfiguration tcSubject = new TemplateConfiguration(); |
| tcSubject.setOutputFormat(PlainTextOutputFormat.INSTANCE); |
| |
| TemplateConfiguration tcBody = new TemplateConfiguration(); |
| tcBody.setOutputFormat(HTMLOutputFormat.INSTANCE); |
| |
| cfg.setTemplateConfigurations( |
| new ConditionalTemplateConfigurationFactory( |
| new PathGlobMatcher("mail/**"), |
| new FirstMatchTemplateConfigurationFactory( |
| new ConditionalTemplateConfigurationFactory( |
| new FileNameGlobMatcher("*.subject.*"), |
| tcSubject), |
| new ConditionalTemplateConfigurationFactory( |
| new FileNameGlobMatcher("*.body.*"), |
| tcBody) |
| ) |
| .noMatchErrorDetails( |
| "Mail template names must contain \".subject.\" or \".body.\"!") |
| ));</pre> </div> |
| |
| |
| <p>The equivalent configuration using a Java |
| <code class="inline-code">*.properties</code> file or other kind of string-string |
| key value pairs (the <code class="inline-code">\</code>-s are prescribed by the |
| Java Properties file format only, so omit them elsewhere):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">templateConfigurations = \ |
| ConditionalTemplateConfigurationFactory( \ |
| PathGlobMatcher("mail/**"), \ |
| FirstMatchTemplateConfigurationFactory( \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileNameGlobMatcher("*.subject.*"), \ |
| TemplateConfiguration(outputFormat = PlainTextOutputFormat()) \ |
| ), \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileNameGlobMatcher("*.body.*"), \ |
| TemplateConfiguration(outputFormat = HTMLOutputFormat()) \ |
| ), \ |
| noMatchErrorDetails = 'Mail template names must contain ".subject." or ".body."!' \ |
| ) \ |
| )</pre> </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-simplesect" id="autoid_49">Example 3</h2> |
| |
| |
| <p>Let's say you want the following deviations from the shared |
| <code class="inline-code">Configuration</code> settings in your |
| application:</p> |
| |
| <ul> |
| <li> |
| <p>All templates whose name contains |
| <code class="inline-code">".stats."</code> should use ISO date/time format and |
| UTC time zone</p> |
| </li> |
| |
| <li> |
| <p>All templates inside the <code class="inline-code">mail</code> directory |
| should use UTF-8 encoding</p> |
| </li> |
| |
| <li> |
| <p>Templates with <code class="inline-code">xml</code> file extension |
| should use XML <code class="inline-code">output_format</code>, templates with |
| <code class="inline-code">html</code> or <code class="inline-code">htm</code> extension |
| should use HTML output format. For other templates, the shared |
| <code class="inline-code">Configuration</code> can dictate the |
| <code class="inline-code">output_format</code>.</p> |
| </li> |
| </ul> |
| |
| <p>Here we have 3 independent concerns, and possibly multiple (or |
| none) of those apply to a template; that's when you need a |
| <code class="inline-code">MergingTemplateConfigurationFactory</code>. In file |
| extension related rule above you have mutually exclusive choices, so |
| you need a |
| <code class="inline-code">FirstMatchTemplateConfigurationFactory</code>, but this |
| time no choice is also allowed. Here's the source code, assuming |
| <code class="inline-code">cfg</code> stores the shared |
| <code class="inline-code">Configuration</code> instance:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">TemplateConfiguration tcStats = new TemplateConfiguration(); |
| tcStats.setDateTimeFormat("iso"); |
| tcStats.setDateFormat("iso"); |
| tcStats.setTimeFormat("iso"); |
| tcStats.setTimeZone(DateUtil.UTC); |
| |
| TemplateConfiguration tcMail = new TemplateConfiguration(); |
| tcMail.setEncoding("utf-8"); |
| |
| TemplateConfiguration tcHTML = new TemplateConfiguration(); |
| tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE); |
| |
| TemplateConfiguration tcXML = new TemplateConfiguration(); |
| tcXML.setOutputFormat(XMLOutputFormat.INSTANCE); |
| |
| cfg.setTemplateConfigurations( |
| new MergingTemplateConfigurationFactory( |
| new ConditionalTemplateConfigurationFactory( |
| new FileNameGlobMatcher("*.stats.*"), |
| tcStats), |
| new ConditionalTemplateConfigurationFactory( |
| new PathGlobMatcher("mail/**"), |
| tcMail), |
| new FirstMatchTemplateConfigurationFactory( |
| new ConditionalTemplateConfigurationFactory( |
| new FileExtensionMatcher("xml"), |
| tcXML), |
| new ConditionalTemplateConfigurationFactory( |
| new OrMatcher( |
| new FileExtensionMatcher("html"), |
| new FileExtensionMatcher("htm")), |
| tcHTML) |
| ).allowNoMatch(true) |
| ) |
| );</pre> </div> |
| |
| |
| <p>The equivalent configuration using a Java |
| <code class="inline-code">*.properties</code> file or other kind of string-string |
| key value pairs (the <code class="inline-code">\</code>-s are prescribed by the |
| Java Properties file format only):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">templateConfigurations = \ |
| MergingTemplateConfigurationFactory( \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileNameGlobMatcher("*.stats.*"), \ |
| TemplateConfiguration( \ |
| dateTimeFormat = "iso", \ |
| dateFormat = "iso", \ |
| timeFormat = "iso", \ |
| timeZone = TimeZone("UTC") \ |
| ) \ |
| ), \ |
| ConditionalTemplateConfigurationFactory( \ |
| PathGlobMatcher("mail/**"), \ |
| TemplateConfiguration(encoding = "utf-8") \ |
| ), \ |
| FirstMatchTemplateConfigurationFactory( \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileExtensionMatcher("xml"), \ |
| TemplateConfiguration(outputFormat = XMLOutputFormat()) \ |
| ), \ |
| ConditionalTemplateConfigurationFactory( \ |
| OrMatcher( \ |
| FileExtensionMatcher("html"), \ |
| FileExtensionMatcher("htm") \ |
| ), \ |
| TemplateConfiguration(outputFormat = HTMLOutputFormat()) \ |
| ), \ |
| allowNoMatch = true \ |
| ) \ |
| )</pre> </div> |
| |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_errorhandling.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_outputformatsautoesc.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> |
