| <!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>Associating output formats with templates - 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="Associating output formats with templates"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/pgui_config_outputformatsautoesc.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/pgui_config_outputformatsautoesc.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_outputformatsautoesc.html"><span itemprop="name">Associating output formats with templates</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","Associating output formats with templates"];</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_templateconfigurations.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_custom_formats.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="pgui_config_outputformatsautoesc" itemprop="headline">Associating output formats with templates</h1> |
| </div></div><p>The output format associated to a template decides if and what |
| kind of auto-escaping is used in that template (unless the template |
| <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_overrideoformat">overrides that |
| with directives</a>). By default, templates have |
| "undefined" output format associated, which does no |
| escaping, and in general gives the behavior that you would expect from |
| a template engine that doesn't care about output formats and escaping. |
| However, if the <code class="inline-code">recognize_standard_file_extensions</code> |
| <a href="pgui_config_settings.html">setting</a> is |
| <code class="inline-code">true</code> (which is the default with <a href="pgui_config_incompatible_improvements.html">the |
| <code>incompatible_improvements</code> setting</a> set to |
| 2.3.24 or higher), templates whose source name ends with |
| <code class="inline-code">".ftlh"</code> gets "HTML" output format, and |
| those with <code class="inline-code">".ftlx"</code> get "XML" output |
| format. Using the <code class="inline-code">ftlh</code> and <code class="inline-code">ftlx</code> |
| file extensions is the recommended way of activating HTML and XML |
| auto-escaping. You can also associate output formats to templates |
| based on arbitrary name patterns with the <a href="pgui_config_templateconfigurations.html"><code>template_configurations</code> |
| setting</a>; see some examples of that below.</p><p>There's another a related setting, called |
| <code class="inline-code">auto_escaping_policy</code>, which can be used to disable |
| auto-escaping even if the current output format supports it, or enable |
| auto-escaping even if the format by default doesn't escape (but it |
| supports it). Using this setting rarely advisable, as it's potentially |
| confusing for the template authors. (Instead, escaping can be turned |
| on/off explicitly inside the templates with the |
| <code class="inline-code">auto_esc</code> parameter of the <a href="ref_directive_ftl.html"><code>ftl</code> directive</a>, |
| or with the <a href="ref_directive_autoesc.html"><code>noautoesc</code></a> |
| and <a href="ref_directive_autoesc.html"><code>autoesc</code> |
| directive</a>s.)</p><p>To check if you have configured FreeMarker properly, you can use |
| this template:</p> |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><p>Output format: ${.output_format} |
| <p>Auto-escaping: ${.auto_esc?c}</pre> </div> |
| <p>See the <a href="dgui_misc_autoescaping.html#topic.predefinedOutputFormats">table of |
| predefined output formats here...</a></p><p>Configuration examples:</p><ul> |
| <li> |
| <p>To enable automatic output format associations to |
| <code class="inline-code">*.ftlh</code> and <code class="inline-code">*.ftlx</code>, |
| either:</p> |
| |
| <ul> |
| <li> |
| <p>Use <code class="inline-code">incompatible_improvements</code> 2.3.24 |
| or higher; see <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set">how |
| to set |
| <code>incompatible_improvements</code></a></p> |
| </li> |
| |
| <li> |
| <p>Or, enable standard file extension recognizing |
| explicitly:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">// Where you initalize the Configuration singletion, add: |
| cfg.setRecognizeStandardFileExtensions(true);</pre> </div> |
| |
| |
| <p>or if you configure FreeMarker with Java |
| <code class="inline-code">*.properties</code> file:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">recognizeStandardFileExtensions = true</pre> </div> |
| |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Let's say that you want to associate all templates in the |
| <code class="inline-code">mail</code> directory to the HTML output format. You |
| could achieve that like this (assuming that you are getting the |
| templates with |
| <code class="inline-code">cfg.getTemplate(<em class="code-color">...</em>)</code>, |
| and not instantiating them yourself):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">// Where you initalize the Configuration singletion, add: |
| |
| TemplateConfiguration tcHTML = new TemplateConfiguration(); |
| tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE); |
| |
| cfg.setTemplateConfigurations( |
| new ConditionalTemplateConfigurationFactory( |
| new PathGlobMatcher("mail/**"), |
| tcHTML));</pre> </div> |
| |
| |
| <p>or if you are configuring FreeMarker from Java |
| <code class="inline-code">*.properties</code> file (the <code class="inline-code">\</code>-s |
| are required for the Java Properties file format only):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">templateConfigurations = \ |
| ConditionalTemplateConfigurationFactory( \ |
| PathGlobMatcher("mail/**"), \ |
| TemplateConfiguration(outputFormat = HTMLOutputFormat()))</pre> </div> |
| |
| </li> |
| |
| <li> |
| <p>Let's say you want to associate templates with |
| <code class="inline-code">xml</code> file extension to the XML output format, |
| templates with <code class="inline-code">html</code> and <code class="inline-code">htm</code> |
| extension to the HTML output format, and templates with |
| <code class="inline-code">rtf</code> extension to the <code class="inline-code">RTF</code> |
| output format. You could achieve that like this (assuming that you |
| are getting the templates with |
| <code class="inline-code">cfg.getTemplate(<em class="code-color">...</em>)</code>, |
| and not instantiating them yourself):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">TemplateConfiguration tcHTML = new TemplateConfiguration(); |
| tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE); |
| |
| TemplateConfiguration tcXML = new TemplateConfiguration(); |
| tcXML.setOutputFormat(XMLOutputFormat.INSTANCE); |
| |
| TemplateConfiguration tcRTF = new TemplateConfiguration(); |
| tcRTF.setOutputFormat(RTFOutputFormat.INSTANCE); |
| |
| cfg.setTemplateConfigurations( |
| new FirstMatchTemplateConfigurationFactory( |
| new ConditionalTemplateConfigurationFactory( |
| new FileExtensionMatcher("xml"), |
| tcXML), |
| new ConditionalTemplateConfigurationFactory( |
| new OrMatcher( |
| new FileExtensionMatcher("html"), |
| new FileExtensionMatcher("htm")), |
| tcHTML), |
| new ConditionalTemplateConfigurationFactory( |
| new FileExtensionMatcher("rtf"), |
| tcRTF) |
| ).allowNoMatch(true) |
| );</pre> </div> |
| |
| |
| <p>or if you are configuring FreeMarker from Java |
| <code class="inline-code">*.properties</code> file (the <code class="inline-code">\</code>-s |
| are required for the Java Properties file format only):</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">templateConfigurations = \ |
| FirstMatchTemplateConfigurationFactory( \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileExtensionMatcher("xml"), \ |
| TemplateConfiguration(outputFormat = XMLOutputFormat())), \ |
| ConditionalTemplateConfigurationFactory( \ |
| OrMatcher( \ |
| FileExtensionMatcher("html"), \ |
| FileExtensionMatcher("htm")), \ |
| TemplateConfiguration(outputFormat = HTMLOutputFormat())), \ |
| ConditionalTemplateConfigurationFactory( \ |
| FileExtensionMatcher("rtf"), \ |
| TemplateConfiguration(outputFormat = RTFOutputFormat())), \ |
| allowNoMatch = true)</pre> </div> |
| |
| </li> |
| </ul><p>(You can find some more complex |
| <code class="inline-code">template_configurations</code> setups <a href="pgui_config_templateconfigurations.html">here...</a>)</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_templateconfigurations.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_custom_formats.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> |
