docs/ref_directive_escape.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>escape, noescape (deprecated) - 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="escape, noescape (deprecated)">
 <meta property="og:locale" content="en_US">
 <meta property="og:url" content="https://freemarker.apache.org/docs/ref_directive_escape.html">
 <link rel="canonical" href="https://freemarker.apache.org/docs/ref_directive_escape.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="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">Directive Reference</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_escape.html"><span itemprop="name">escape, noescape (deprecated)</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","Template Language Reference","Directive Reference","escape, noescape (deprecated)"];</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="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.html"><span>Next</span></a></div><div class="title-wrapper">
 <h1 class="content-header header-section1" id="ref_directive_escape" itemprop="headline">escape, noescape (deprecated)</h1>
 </div></div><div class="page-menu">
 <div class="page-menu-title">Page Contents</div>
 <ul><li><a class="page-menu-link" href="#autoid_86" data-menu-target="autoid_86">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_87" data-menu-target="autoid_87">Description</a></li></ul> </div><a name="ref.directive.escape"></a><a name="ref.directive.noescape"></a>


 <h2 class="content-header header-section2" id="autoid_86">Synopsis</h2>


 <pre class="metaTemplate">
 <code class="inline-code">&lt;#escape <em class="code-color">identifier</em> as <em class="code-color">expression</em>&gt;
   <em class="code-color">...</em>
   &lt;#noescape&gt;<em class="code-color">...</em>&lt;/#noescape&gt;
   <em class="code-color">...</em>
 &lt;/#escape&gt;</code>
 </pre>


           <p>Camel case name variant: <code class="inline-code">noEscape</code></p>


 <h2 class="content-header header-section2" id="autoid_87">Description</h2>


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

             <p>These directives are <em>deprecated</em> by
             <a href="dgui_misc_autoescaping.html">output-format-based
             auto-escaping</a> since 2.3.24. Furthermore, on places that use
             auto-escaping (with an output format that actually does escaping)
             you aren&#39;t allowed to use the <code class="inline-code">escape</code> directive
             (as you will find out from the parsing error message
             anyway).</p>
             </div>


           <p>When you surround a part of the template with an escape
           directive, interpolations
           (<code class="inline-code">${<em class="code-color">...</em>}</code>) that occur
           inside the block are combined with the escaping expression
           automatically. This is a convenience method for avoiding writing
           similar expressions all over. It does not affect interpolations in
           string literals (as in <code class="inline-code">&lt;#assign x =
           &quot;Hello ${user}!&quot;&gt;</code>). Also, it does not affect numerical
           interpolations
           (<code class="inline-code">#{<em class="code-color">...</em>}</code>).</p>

           <p>Example:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body"><strong>&lt;#escape x as x?html&gt;</strong>
   First name: ${firstName}
   Last name: ${lastName}
   Maiden name: ${maidenName}
 <strong>&lt;/#escape&gt;</strong></pre>    </div>


           <p>is actually equivalent to:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">  First name: ${firstName<strong>?html</strong>}
   Last name: ${lastName<strong>?html</strong>}
   Maiden name: ${maidenName<strong>?html</strong>}</pre>    </div>


           <p>Note that it is irrelevant what identifier you use in the
           directive - it just serves as a formal parameter to the escaping
           expression.</p>

           <p>When you are calling macros or the <code class="inline-code">include</code>
           directive, it is important to understand that escape has effect only
           on interpolations that occur between the <code class="inline-code">&lt;#escape
           <em class="code-color">...</em>&gt;</code> and
           <code class="inline-code">&lt;/#escape&gt;</code> <em>in the template
           text</em>. That is, it will not escape anything that is before
           <code class="inline-code">&lt;#escape <em class="code-color">...</em>&gt;</code> in
           the text, or after the <code class="inline-code">&lt;/#escape&gt;</code> in the
           text, not even if that part is called from inside the
           <code class="inline-code">escape</code>-d section.</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">&lt;#assign x = &quot;&lt;test&gt;&quot;&gt;
 &lt;#macro m1&gt;
   m1: ${x}
 &lt;/#macro&gt;
 &lt;#escape x as x?html&gt;
   &lt;#macro m2&gt;m2: ${x}&lt;/#macro&gt;
   ${x}
   &lt;@m1/&gt;
 &lt;/#escape&gt;
 ${x}
 &lt;@m2/&gt;</pre>    </div>


           <p>the output will be:</p>


     <div class="code-block role-output">
 <div class="code-block-label">Output</div><pre class="code-block-body">  &amp;lt;test&amp;gt;
   m1: &lt;test&gt;
 &lt;test&gt;
 m2: &amp;lt;test&amp;gt;</pre>    </div>


           <p><span class="marked-for-programmers">More technically, the effects of
           <code class="inline-code">escape</code> directive are applied at template parsing
           time rather than at template processing time. This means that if you
           call a macro or include another template from within an escape
           block, it won&#39;t affect the interpolations in the macro/included
           template, since macro calls and template includes are evaluated at
           template processing time. On the other hand, if you surround one or
           more macro declarations (which are evaluated at template parsing
           time, as opposed to macro calls) with an escape block, the
           interpolations in those macros will be combined with the escaping
           expression.</span></p>

           <p>Sometimes there is a need to temporarily turn off escaping for
           one or two interpolations in an escape block. You can achieve this
           by closing and later reopening the escape block, but then you have
           to write the escaping expression twice. You can instead use the
           noescape directive:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">&lt;#escape x as x?html&gt;
   From: ${mailMessage.From}
   Subject: ${mailMessage.Subject}
   <strong>&lt;#noescape&gt;</strong>Message: ${mailMessage.htmlFormattedBody}<strong>&lt;/#noescape&gt;</strong>
   <em>...</em>
 &lt;/#escape&gt;</pre>    </div>


           <p>is equivalent to:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">  From: ${mailMessage.From?html}
   Subject: ${mailMessage.Subject?html}
   Message: ${mailMessage.htmlFormattedBody}
   ...</pre>    </div>


           <p>Escapes can be nested (although you will do it only in rare
           circumstances). Therefore, you can write something like the below
           code (the example is admittedly a bit stretched, as you&#39;d probably
           place item codes in a sequence and use <code class="inline-code">list</code> to
           iterate over them, but we&#39;re now doing it this way just to
           illustrate the point):</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body"><strong>&lt;#escape x as x?html&gt;</strong>
   Customer Name: ${customerName}
   Items to ship:
   <strong>&lt;#escape x as itemCodeToNameMap[x]&gt;</strong>
     ${itemCode1}
     ${itemCode2}
     ${itemCode3}
     ${itemCode4}
   <strong>&lt;/#escape&gt;</strong>
 <strong>&lt;/#escape&gt;</strong></pre>    </div>


           <p>is actually equivalent to:</p>


     <div class="code-block role-template">
 <div class="code-block-label">Template</div><pre class="code-block-body">  Customer Name: ${customerName?html}
   Items to ship:
     ${itemCodeToNameMap[itemCode1]?html}
     ${itemCodeToNameMap[itemCode2]?html}
     ${itemCodeToNameMap[itemCode3]?html}
     ${itemCodeToNameMap[itemCode4]?html}</pre>    </div>


           <p>When you use the noescape directive in a nested escape block,
           it undoes only a single level of escaping. Therefore, to completely
           turn off escaping in a two-level deep escaped block, you need to use
           two nested noescape directives as well.</p>
         <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.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>escape, noescape (deprecated) - 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="escape, noescape (deprecated)">
	<meta property="og:locale" content="en_US">
	<meta property="og:url" content="https://freemarker.apache.org/docs/ref_directive_escape.html">
	<link rel="canonical" href="https://freemarker.apache.org/docs/ref_directive_escape.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="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">Directive Reference</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_escape.html"><span itemprop="name">escape, noescape (deprecated)</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","Template Language Reference","Directive Reference","escape, noescape (deprecated)"];</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="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.html"><span>Next</span></a></div><div class="title-wrapper">
	<h1 class="content-header header-section1" id="ref_directive_escape" itemprop="headline">escape, noescape (deprecated)</h1>
	</div></div><div class="page-menu">
	<div class="page-menu-title">Page Contents</div>
	<ul><li><a class="page-menu-link" href="#autoid_86" data-menu-target="autoid_86">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_87" data-menu-target="autoid_87">Description</a></li></ul> </div><a name="ref.directive.escape"></a><a name="ref.directive.noescape"></a>




	<h2 class="content-header header-section2" id="autoid_86">Synopsis</h2>



	<pre class="metaTemplate">
	<code class="inline-code"><#escape <em class="code-color">identifier</em> as <em class="code-color">expression</em>>
	<em class="code-color">...</em>
	<#noescape><em class="code-color">...</em></#noescape>
	<em class="code-color">...</em>
	</#escape></code>
	</pre>


	<p>Camel case name variant: <code class="inline-code">noEscape</code></p>





	<h2 class="content-header header-section2" id="autoid_87">Description</h2>


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

	<p>These directives are <em>deprecated</em> by
	<a href="dgui_misc_autoescaping.html">output-format-based
	auto-escaping</a> since 2.3.24. Furthermore, on places that use
	auto-escaping (with an output format that actually does escaping)
	you aren't allowed to use the <code class="inline-code">escape</code> directive
	(as you will find out from the parsing error message
	anyway).</p>
	</div>


	<p>When you surround a part of the template with an escape
	directive, interpolations
	(<code class="inline-code">${<em class="code-color">...</em>}</code>) that occur
	inside the block are combined with the escaping expression
	automatically. This is a convenience method for avoiding writing
	similar expressions all over. It does not affect interpolations in
	string literals (as in <code class="inline-code"><#assign x =
	"Hello ${user}!"></code>). Also, it does not affect numerical
	interpolations
	(<code class="inline-code">#{<em class="code-color">...</em>}</code>).</p>

	<p>Example:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><strong><#escape x as x?html></strong>
	First name: ${firstName}
	Last name: ${lastName}
	Maiden name: ${maidenName}
	<strong></#escape></strong></pre> </div>


	<p>is actually equivalent to:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"> First name: ${firstName<strong>?html</strong>}
	Last name: ${lastName<strong>?html</strong>}
	Maiden name: ${maidenName<strong>?html</strong>}</pre> </div>


	<p>Note that it is irrelevant what identifier you use in the
	directive - it just serves as a formal parameter to the escaping
	expression.</p>

	<p>When you are calling macros or the <code class="inline-code">include</code>
	directive, it is important to understand that escape has effect only
	on interpolations that occur between the <code class="inline-code"><#escape
	<em class="code-color">...</em>></code> and
	<code class="inline-code"></#escape></code> <em>in the template
	text</em>. That is, it will not escape anything that is before
	<code class="inline-code"><#escape <em class="code-color">...</em>></code> in
	the text, or after the <code class="inline-code"></#escape></code> in the
	text, not even if that part is called from inside the
	<code class="inline-code">escape</code>-d section.</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><#assign x = "<test>">
	<#macro m1>
	m1: ${x}
	</#macro>
	<#escape x as x?html>
	<#macro m2>m2: ${x}</#macro>
	${x}
	<@m1/>
	</#escape>
	${x}
	<@m2/></pre> </div>


	<p>the output will be:</p>



	<div class="code-block role-output">
	<div class="code-block-label">Output</div><pre class="code-block-body"> &lt;test&gt;
	m1: <test>
	<test>
	m2: &lt;test&gt;</pre> </div>


	<p><span class="marked-for-programmers">More technically, the effects of
	<code class="inline-code">escape</code> directive are applied at template parsing
	time rather than at template processing time. This means that if you
	call a macro or include another template from within an escape
	block, it won't affect the interpolations in the macro/included
	template, since macro calls and template includes are evaluated at
	template processing time. On the other hand, if you surround one or
	more macro declarations (which are evaluated at template parsing
	time, as opposed to macro calls) with an escape block, the
	interpolations in those macros will be combined with the escaping
	expression.</span></p>

	<p>Sometimes there is a need to temporarily turn off escaping for
	one or two interpolations in an escape block. You can achieve this
	by closing and later reopening the escape block, but then you have
	to write the escaping expression twice. You can instead use the
	noescape directive:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><#escape x as x?html>
	From: ${mailMessage.From}
	Subject: ${mailMessage.Subject}
	<strong><#noescape></strong>Message: ${mailMessage.htmlFormattedBody}<strong></#noescape></strong>
	<em>...</em>
	</#escape></pre> </div>


	<p>is equivalent to:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"> From: ${mailMessage.From?html}
	Subject: ${mailMessage.Subject?html}
	Message: ${mailMessage.htmlFormattedBody}
	...</pre> </div>


	<p>Escapes can be nested (although you will do it only in rare
	circumstances). Therefore, you can write something like the below
	code (the example is admittedly a bit stretched, as you'd probably
	place item codes in a sequence and use <code class="inline-code">list</code> to
	iterate over them, but we're now doing it this way just to
	illustrate the point):</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"><strong><#escape x as x?html></strong>
	Customer Name: ${customerName}
	Items to ship:
	<strong><#escape x as itemCodeToNameMap[x]></strong>
	${itemCode1}
	${itemCode2}
	${itemCode3}
	${itemCode4}
	<strong></#escape></strong>
	<strong></#escape></strong></pre> </div>


	<p>is actually equivalent to:</p>



	<div class="code-block role-template">
	<div class="code-block-label">Template</div><pre class="code-block-body"> Customer Name: ${customerName?html}
	Items to ship:
	${itemCodeToNameMap[itemCode1]?html}
	${itemCodeToNameMap[itemCode2]?html}
	${itemCodeToNameMap[itemCode3]?html}
	${itemCodeToNameMap[itemCode4]?html}</pre> </div>


	<p>When you use the noescape directive in a nested escape block,
	it undoes only a single level of escaping. Therefore, to completely
	turn off escaping in a two-level deep escaped block, you need to use
	two nested noescape directives as well.</p>
	<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_compress.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_flush.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>