You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/03/13 10:58:01 UTC
[25/50] incubator-freemarker-site git commit: 2.3.26-nightly docs
preview
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/ref_builtins_string.html
----------------------------------------------------------------------
diff --git a/builds/2.3.26-nightly/ref_builtins_string.html b/builds/2.3.26-nightly/ref_builtins_string.html
new file mode 100644
index 0000000..6ebdd42
--- /dev/null
+++ b/builds/2.3.26-nightly/ref_builtins_string.html
@@ -0,0 +1,2374 @@
+<!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>Built-ins for strings - 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="Built-ins for strings">
+<meta property="og:locale" content="en_US">
+<meta property="og:url" content="http://freemarker.org/docs/ref_builtins_string.html">
+<link rel="canonical" href="http://freemarker.org/docs/ref_builtins_string.html">
+<link rel="icon" href="favicon.png" type="image/png">
+<link rel="stylesheet" type="text/css" href="http://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?1489402528979">
+<script>
+(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+ga('create', 'UA-55420501-1', 'auto');
+ga('send', 'pageview');
+</script>
+</head>
+<body itemscope itemtype="https://schema.org/Code">
+ <meta itemprop="url" content="http://freemarker.org/docs/">
+ <meta itemprop="name" content="Apache FreeMarker Manual">
+
+ <!--[if lte IE 9]>
+ <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
+ <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker">
+</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc
h-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"><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_builtins.html"><span itemprop="name">Built-in Reference</span></a></li><li class="step-3"
itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_builtins_string.html"><span itemprop="name">Built-ins for strings</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Built-in Reference","Built-ins for strings"];</script>
+ <script src="toc.js?1489402528979"></script>
+ <script src="docgen-resources/main.min.js?1489402528979"></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_builtins_alphaidx.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_number.html"><span>Next</span></a></div><div class="title-wrapper">
+<h1 class="content-header header-section1" id="ref_builtins_string" itemprop="headline">Built-ins for strings</h1>
+</div></div><div class="page-menu">
+<div class="page-menu-title">Page Contents</div>
+<ul><li><a class="page-menu-link" href="#ref_builtin_boolean" data-menu-target="ref_builtin_boolean">boolean</a></li><li><a class="page-menu-link" href="#ref_builtin_cap_first" data-menu-target="ref_builtin_cap_first">cap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_capitalize" data-menu-target="ref_builtin_capitalize">capitalize</a></li><li><a class="page-menu-link" href="#ref_builtin_chop_linebreak" data-menu-target="ref_builtin_chop_linebreak">chop_linebreak</a></li><li><a class="page-menu-link" href="#ref_builtin_contains" data-menu-target="ref_builtin_contains">contains</a></li><li><a class="page-menu-link" href="#ref_builtin_string_date" data-menu-target="ref_builtin_string_date">date, time, datetime</a></li><li><a class="page-menu-link" href="#ref_builtin_ends_with" data-menu-target="ref_builtin_ends_with">ends_with</a></li><li><a class="page-menu-link" href="#ref_builtin_ensure_ends_with" data-menu-target="ref_builtin_ensure_ends_with">ensure_ends_with</a><
/li><li><a class="page-menu-link" href="#ref_builtin_ensure_starts_with" data-menu-target="ref_builtin_ensure_starts_with">ensure_starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_esc" data-menu-target="ref_builtin_esc">esc</a></li><li><a class="page-menu-link" href="#ref_builtin_groups" data-menu-target="ref_builtin_groups">groups</a></li><li><a class="page-menu-link" href="#ref_builtin_html" data-menu-target="ref_builtin_html">html (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_index_of" data-menu-target="ref_builtin_index_of">index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_j_string" data-menu-target="ref_builtin_j_string">j_string</a></li><li><a class="page-menu-link" href="#ref_builtin_js_string" data-menu-target="ref_builtin_js_string">js_string</a></li><li><a class="page-menu-link" href="#ref_builtin_json_string" data-menu-target="ref_builtin_json_string">json_string</a></li><li><a class="page-menu-link" href="#ref_bu
iltin_keep_after" data-menu-target="ref_builtin_keep_after">keep_after</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_after_last" data-menu-target="ref_builtin_keep_after_last">keep_after_last</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_before" data-menu-target="ref_builtin_keep_before">keep_before</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_before_last" data-menu-target="ref_builtin_keep_before_last">keep_before_last</a></li><li><a class="page-menu-link" href="#ref_builtin_last_index_of" data-menu-target="ref_builtin_last_index_of">last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_left_pad" data-menu-target="ref_builtin_left_pad">left_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_length" data-menu-target="ref_builtin_length">length</a></li><li><a class="page-menu-link" href="#ref_builtin_lower_case" data-menu-target="ref_builtin_lower_case">lower_case</a></li><li><a class="page-menu-link" href="#
ref_builtin_matches" data-menu-target="ref_builtin_matches">matches</a></li><li><a class="page-menu-link" href="#ref_builtin_no_esc" data-menu-target="ref_builtin_no_esc">no_esc</a></li><li><a class="page-menu-link" href="#ref_builtin_number" data-menu-target="ref_builtin_number">number</a></li><li><a class="page-menu-link" href="#ref_builtin_replace" data-menu-target="ref_builtin_replace">replace</a></li><li><a class="page-menu-link" href="#ref_builtin_right_pad" data-menu-target="ref_builtin_right_pad">right_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_remove_beginning" data-menu-target="ref_builtin_remove_beginning">remove_beginning</a></li><li><a class="page-menu-link" href="#ref_builtin_remove_ending" data-menu-target="ref_builtin_remove_ending">remove_ending</a></li><li><a class="page-menu-link" href="#ref_builtin_rtf" data-menu-target="ref_builtin_rtf">rtf (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_split" data-menu-target="ref_builti
n_split">split</a></li><li><a class="page-menu-link" href="#ref_builtin_starts_with" data-menu-target="ref_builtin_starts_with">starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_string" data-menu-target="ref_builtin_string_for_string">string (when used with a string value)</a></li><li><a class="page-menu-link" href="#ref_builtin_substring" data-menu-target="ref_builtin_substring">substring (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_trim" data-menu-target="ref_builtin_trim">trim</a></li><li><a class="page-menu-link" href="#ref_builtin_uncap_first" data-menu-target="ref_builtin_uncap_first">uncap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_upper_case" data-menu-target="ref_builtin_upper_case">upper_case</a></li><li><a class="page-menu-link" href="#ref_builtin_url" data-menu-target="ref_builtin_url">url</a></li><li><a class="page-menu-link" href="#ref_builtin_url_path" data-menu-target="ref_builtin_url_path">ur
l_path</a></li><li><a class="page-menu-link" href="#ref_builtin_word_list" data-menu-target="ref_builtin_word_list">word_list</a></li><li><a class="page-menu-link" href="#ref_builtin_xhtml" data-menu-target="ref_builtin_xhtml">xhtml (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_xml" data-menu-target="ref_builtin_xml">xml (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_string_flags" data-menu-target="ref_builtin_string_flags">Common flags</a></li></ul> </div><p>These built-ins act on a string left-value. However, if the
+ left-value is number or date/time/date-time or boolean (since 2.3.20),
+ it will automatically converted to string according the current
+ number-, date/time/date-time- and boolean-format settings (which are
+ the same formatters that are applied when inserting such values with
+ <code class="inline-code">${<em class="code-color">...</em>}</code>).</p>
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_boolean">boolean</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The string converted to boolean value. The string must be
+ <code class="inline-code">true</code> or <code class="inline-code">false</code> (case
+ sensitive!), or must be in the format specified by the
+ <code class="inline-code">boolean_format</code> setting.</p>
+
+ <p>If the string is not in the appropriate format, an error will
+ abort template processing when you try to access this
+ built-in.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_cap_first">cap_first</h2>
+
+
+
+
+ <p>The string with the very first word of the string capitalized.
+ For the precise meaning of "word" see the <a href="#ref_builtin_word_list">word_list built-in</a>.
+ Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?cap_first}
+${"GreEN mouse"?cap_first}
+${"- green mouse"?cap_first}</pre></div>
+
+ <p>The output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output"> Green mouse
+GreEN mouse
+- green mouse</pre></div>
+
+ <p>In the case of <code class="inline-code">"- green mouse"</code>, the first
+ word is the <code class="inline-code">-</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_capitalize">capitalize</h2>
+
+
+
+
+ <p>The string with all words capitalized. For the precise meaning
+ of "word" see the <a href="#ref_builtin_word_list">word_list built-in</a>.
+ Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?capitalize}
+${"GreEN mouse"?capitalize}</pre></div>
+
+ <p>The output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output"> Green Mouse
+Green Mouse</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_chop_linebreak">chop_linebreak</h2>
+
+
+
+
+ <p>The string without the <a href="gloss.html#gloss.lineBreak">line-break</a> at its very end if there
+ was a line-break, otherwise the unchanged string.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_contains">contains</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.1. It
+ doesn't exist in 2.3.</p>
+ </div>
+
+
+ <p>Returns if the substring specified as the parameter to this
+ built-in occurrs in the string. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#if "piceous"?contains("ice")>It contains "ice"</#if></pre></div>
+
+ <p>This will output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">It contains "ice"</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_string_date">date, time, datetime</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The string value converted to a date, time, or date-time
+ value. It will expect the format specified by the <a href="ref_directive_setting.html#topic.dateTimeFormatSettings"><code>date_format</code>,
+ <code>time_format</code> and
+ <code>datetime_format</code> settings</a>. If the string is
+ not in the appropriate format, an error will abort template
+ processing when you try to access this built-in.</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#-- The date_format, time_format and datetime_format settings must match this format! -->
+<#assign someDate = "Oct 25, 1995"?date>
+<#assign someTime = "3:05:30 PM"?time>
+<#assign someDatetime = "Oct 25, 1995 03:05:00 PM"?datetime>
+
+<#-- Changing the setting value changes the expected format: -->
+<#setting datetime_format="iso">
+<#assign someDatetime = "1995-10-25T15:05"?datetime></pre></div>
+
+ <p>You can also specify the format explicitly like
+ <code class="inline-code">?datetime.<em class="code-color">format</em></code> (and
+ hence also as
+ <code class="inline-code">?datetime["<em class="code-color">format</em>"]</code>)
+ or
+ <code class="inline-code">?datetime("<em class="code-color">format</em>")</code>;
+ these three forms do the same. The format can be specified similarly
+ with <code class="inline-code">?date</code> and <code class="inline-code">?time</code> too. For
+ the syntax and meaning of format values see the possible values of
+ the <a href="ref_directive_setting.html#topic.dateTimeFormatSettings"><code>date_format</code>,
+ <code>time_format</code> and
+ <code>datetime_format</code> settings</a>. Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#-- Parsing XML Schema xs:date, xs:time and xs:dateTime values: -->
+<#assign someDate = "1995-10-25"?date.xs>
+<#assign someTime = "15:05:30"?time.xs>
+<#assign someDatetime = "1995-10-25T15:05:00"?datetime.xs>
+
+<#-- Parsing ISO 8601 (both extended and basic formats): -->
+<#assign someDatetime = "1995-10-25T15:05"?datetime.iso>
+<#assign someDatetime = "19951025T1505"?datetime.iso>
+
+<#-- Parsing with SimpleDateFormat patterns: -->
+<#assign someDate = "10/25/1995"?date("MM/dd/yyyy")>
+<#assign someTime = "15:05:30"?time("HH:mm:ss")>
+<#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>
+
+<#-- Parsing with custom date formats: -->
+<#assign someDatetime = "October/25/1995 03:05 PM"?datetime.@worklog></pre></div>
+
+ <p>To prevent misunderstandings, the left-hand value need not be
+ a string literal. For example, when you read data from XML DOM (from
+ where all values come as unparsed strings), you may do things like
+ <code class="inline-code">order.confirmDate?date.xs</code> to convert the string
+ value to a real date.</p>
+
+ <p>Of course, the format also can be a variable, like in
+ <code class="inline-code">"<em class="code-color">...</em>"?datetime(myFormat)</code>.</p>
+
+ <p>Note that since 2.3.24, these built-ins can also be called
+ with 0 arguments, like <code class="inline-code">?date()</code>. It's almost the
+ same as just writing <code class="inline-code">?date</code>. The difference is
+ highly technical and rarely matters: <code class="inline-code">?date()</code> and
+ such returns exactly the same Java object that the date parser
+ (<code class="inline-code">freemarker.core.TemplateDateFormat</code>
+ implementation) returns, while <code class="inline-code">?date</code> without the
+ <code class="inline-code">()</code> returns a tricky wrapper value that's a date
+ and a method and hash on the same time.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_ends_with">ends_with</h2>
+
+
+
+
+ <p>Returns whether this string ends with the substring specified
+ in the parameter. For example
+ <code class="inline-code">"ahead"?ends_with("head")</code> returns boolean
+ <code class="inline-code">true</code>. Also,
+ <code class="inline-code">"head"?ends_with("head")</code> will return
+ <code class="inline-code">true</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_ensure_ends_with">ensure_ends_with</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>If the string doesn't end with the substring specified as the
+ 1st parameter, it adds it after the string, otherwise it returns the
+ original string. For example, both
+ <code class="inline-code">"foo"?ensure_ends_with("/")</code> and
+ <code class="inline-code">"foo/"?ensure_ends_with("/")</code> returns
+ <code class="inline-code">"foo/"</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_ensure_starts_with">ensure_starts_with</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>If the string doesn't start with the substring specified as
+ the 1st parameter, it adds it before the string, otherwise it
+ returns the original string. For example, both
+ <code class="inline-code">"foo"?ensure_starts_with("/")</code> and
+ <code class="inline-code">"/foo"?ensure_starts_with("/")</code> returns
+ <code class="inline-code">"/foo"</code>.</p>
+
+ <p>If you specify two parameters, then the 1st parameter is
+ interpreted as a Java regular expression, and if it doesn't match
+ the beginning of the string, then the string specified as the 2nd
+ parameter is added before the string. For example
+ <code class="inline-code">someURL?ensure_starts_with("[a-zA-Z]+://",
+ "http://")</code> will check if the string starts with something
+ that matches <code class="inline-code">"[a-zA-Z]+://"</code> (note that no
+ <code class="inline-code">^</code> is needed), and if it doesn't, it prepends
+ <code class="inline-code">"http://"</code>.</p>
+
+ <p>This method also accepts a 3rd <a href="#ref_builtin_string_flags">flags parameter</a>. As
+ calling with 2 parameters implies <code class="inline-code">"r"</code> there
+ (i.e., regular expression mode), you rarely need this. One notable
+ case is when you don't want the 1st parameter to be interpreted as a
+ regular expression, only as plain text, but you want the comparison
+ to be case-insensitive, in which case you would use
+ <code class="inline-code">"i"</code> as the 3rd parameter.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_esc">esc</h2>
+
+
+ <p></p>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.24.</p>
+ </div>
+
+
+ <p>Escapes the value with the current <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output format</a>,
+ and prevents the <a href="dgui_misc_autoescaping.html">auto-escaping</a> of the
+ returned value (to avoid double escaping). Because of auto-escaping,
+ you usually only need this where auto-escaping was disabled:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML" <strong>auto_esc=false</strong>>
+<#assign s = "R&D">
+${s}
+${s?esc}</pre></div>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">R&D
+R&amp;D</pre></div>
+
+ <p>In templates, where auto-escaping is on, using it is
+ redundant:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML">
+<#assign s = "R&D">
+${s}
+${s?esc} <#-- ?esc is redundant here --></pre></div>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">R&amp;D
+R&amp;D</pre></div>
+
+ <p>This built-in works by converting the string value to a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ value</a>, by escaping the string with the current output format,
+ and using the result as the markup. The resulting markup output
+ value belongs to the current output format at the point of the
+ invocation.</p>
+
+ <p>This built-in can also be applied on markup output values,
+ which it will bypass without change, as far as the input markup
+ output value belongs to the current output format. If it doesn't,
+ then the markup has to be converted to the current output format,
+ which currently (as of 2.3.24) will be only successful if that value
+ was created by escaping plain text (usually, with
+ <code class="inline-code">?esc</code>).</p>
+
+ <p>This built-in can't be used where the current output format is
+ a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_nonmarkupof">non-markup
+ output format</a>. An attempt to do so will cause a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>.</p>
+
+ <p>This built-in is not related to the deprecated <a href="ref_directive_escape.html"><code>escape</code> and
+ <code>noescape</code> directives</a>. In fact, the parser
+ will prevent using them on the same place, to prevent
+ confusion.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_groups">groups</h2>
+
+
+
+
+ <p>This is used only with the result of the
+ <code class="inline-code">matches</code> built-in. See <a href="#ref_builtin_matches">there...</a></p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_html">html (deprecated)</h2>
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is <em>deprecated</em> by the
+ <a href="dgui_misc_autoescaping.html">auto-escaping
+ mechanism</a> introduced in 2.3.24. To prevent double escaping
+ and confusion in general, using this built-in on places where
+ auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
+ migration, this built-in silently bypasses HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ values</a> without changing them.</p>
+ </div>
+
+
+ <p>The string as HTML markup. That is, the string with
+ all:</p>
+
+ <ul>
+ <li>
+ <code class="inline-code"><</code> replaced with
+ <code class="inline-code">&lt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">></code> replaced with
+ <code class="inline-code">&gt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">&</code> replaced with
+ <code class="inline-code">&amp;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">"</code> replaced with
+ <code class="inline-code">&quot;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">'</code> is replaced with
+ <code class="inline-code">&#39;</code> <em>if</em> the
+ programmers has <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set">set
+ the <code>incompatible_improvements</code> setting</a>
+ to 2.3.24 or higher (also if it's set to 2.3.20 or higher and
+ you are outside a string literal). Otherwise
+ <code class="inline-code">'</code> won't be replaced, so you must use
+ quotation mark (<code class="inline-code">"</code>, not <code class="inline-code">'</code>)
+ to quote attribute values where you want to insert a value
+ safely.
+ </li>
+ </ul>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><input type=text name=user value=<strong>"</strong>${user?html}<strong>"</strong>></pre></div>
+
+ <div class="callout warning">
+ <strong class="callout-label">Warning!</strong>
+
+ <p>When inserting the value of an attribute, always quote it,
+ or else it can be exploited by attackers! This is WRONG:
+ <code class="inline-code"><input name="user" value=${user?xhtml}></code>.
+ This is good: <code class="inline-code"><input name="user"
+ value="${user?xhtml}"></code>.</p>
+ </div>
+
+
+ <p>Note that in HTML pages usually you want to use this built-in
+ for all interpolations. You can spare a lot of typing and lessen the
+ chances of accidental mistakes by using the <a href="ref_directive_escape.html"><code>escape</code>
+ directive</a>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_index_of">index_of</h2>
+
+
+
+
+ <p>Returns the index within this string of the first occurrence
+ of the specified substring. For example,
+ <code class="inline-code">"abcabc"?index_of("bc")</code> will return 1 (don't
+ forget that the index of the first character is 0). Also, you can
+ specify the index to start the search from:
+ <code class="inline-code">"abcabc"?index_of("bc", 2)</code> will return 4. There
+ is no restriction on the numerical value of the second parameter: if
+ it is negative, it has the same effect as if it were zero, and if it
+ is greater than the length of this string, it has the same effect as
+ if it were equal to the length of this string. Decimal values will
+ be truncated to integers.</p>
+
+ <p>If the 1st parameter does not occur as a substring in this
+ string (starting from the given index, if you use the second
+ parameter), then it returns -1.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_j_string">j_string</h2>
+
+
+
+
+ <p>Escapes the string with the escaping rules of Java language
+ string literals, so it's safe to insert the value into a string
+ literal. Note that it will <em>not</em> add quotation
+ marks around the inserted value; you meant to use this
+ <em>inside</em> the string literal.</p>
+
+ <p>All characters under <a href="gloss.html#gloss.UCS">UCS</a> code
+ point 0x20 will be escaped. When they have no dedicated escape
+ sequence in the Java language (like <code class="inline-code">\n</code>,
+ <code class="inline-code">\t</code>, etc.), they will be replaced with a UNICODE
+ escape
+ (<code class="inline-code">\u<em class="code-color">XXXX</em></code>).</p>
+
+ <p>Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#assign beanName = 'The "foo" bean.'>
+String BEAN_NAME = "${beanName?j_string}";</pre></div>
+
+ <p>will output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">String BEAN_NAME = "The \"foo\" bean.";</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_js_string">js_string</h2>
+
+
+
+
+ <p>Escapes the string with the escaping rules of JavaScript
+ language string literals, so it's safe to insert the value into a
+ string literal. Note that it will <em>not</em> add
+ quotation marks around the inserted value; you meant to use this
+ <em>inside</em> the string literal.</p>
+
+ <div class="callout warning">
+ <strong class="callout-label">Warning!</strong>
+
+ <p>When inserting into a JavaScript string literal that's
+ inside a HTML attribute, you also must escape the value with HTML
+ escaping. Thus, of you don't have <a href="pgui_config_outputformatsautoesc.html">automatic HTML
+ escaping</a>, this is WRONG: <code class="inline-code"><p
+ onclick="alert('${message?js_string}')"></code>, and this is
+ good: <code class="inline-code"><p
+ onclick="alert('${message?js_string?html}')"></code>.</p>
+ </div>
+
+
+ <p>Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#assign user = "Big Joe's \"right hand\"">
+<script>
+ alert("Welcome ${user?js_string}!");
+</script></pre></div>
+
+ <p>will output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output"><script>
+ alert("Welcome Big Joe\'s \"right hand\"!");
+</script></pre></div>
+
+ <p>The exact escaping rules are:</p>
+
+ <ul>
+ <li>
+ <p><code class="inline-code">"</code> is escaped as
+ <code class="inline-code">\"</code></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">'</code> is escaped as
+ <code class="inline-code">\'</code></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">\</code> is escaped as
+ <code class="inline-code">\\</code></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">/</code> is escaped as <code class="inline-code">\/</code>
+ if the <code class="inline-code">/</code> is directly after
+ <code class="inline-code"><</code> in the escaped string, or if it's at the
+ beginning of the escaped string</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">></code> is escaped as
+ <code class="inline-code">\></code> if the <code class="inline-code">></code> is
+ directly after <code class="inline-code">]]</code> or <code class="inline-code">--</code> in
+ the escaped string, or if it's at the beginning of the escaped
+ string, or if there's only a <code class="inline-code">]</code> or
+ <code class="inline-code">-</code> before it at the beginning of the escaped
+ string</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code"><</code> is escaped as
+ <code class="inline-code">\u003C</code> if it's followed by
+ <code class="inline-code">?</code> or <code class="inline-code">!</code> in the escaped
+ string, or if it's at the end of the escaped string</p>
+ </li>
+
+ <li>
+ <p>Control characters in <a href="gloss.html#gloss.UCS">UCS</a>
+ code point ranges U+0000...U+001f and U+007f...U+009f are
+ escaped as <code class="inline-code">\r</code>, <code class="inline-code">\n</code>, etc.,
+ or as <code class="inline-code">\x<em class="code-color">XX</em></code> where
+ there's no special escape for them in JavaScript.</p>
+ </li>
+
+ <li>
+ <p>Control characters with <a href="gloss.html#gloss.UCS">UCS</a> code point U+2028 (Line
+ separator) and U+2029 (Paragraph separator) are escaped as
+ <code class="inline-code">\u<em class="code-color">XXXX</em></code>, as they
+ are source code line-breaks in ECMAScript.</p>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_json_string">json_string</h2>
+
+
+
+
+ <p>Escapes the string with the escaping rules of JSON language
+ string literals, so it's safe to insert the value into a string
+ literal. Note that it will <em>not</em> add quotation
+ marks around the inserted value; you meant to use this
+ <em>inside</em> the string literal.</p>
+
+ <p>This will not escape <code class="inline-code">'</code> characters, since
+ JSON strings must be quoted with <code class="inline-code">"</code>.</p>
+
+ <p>The escaping rules are almost identical to those <a href="#ref_builtin_j_string">documented for
+ <code>js_string</code></a>. The differences are that
+ <code class="inline-code">'</code> is not escaped at all, that > is escaped as
+ \u003E (not as \>), and that
+ <code class="inline-code">\u<em class="code-color">XXXX</em></code> escapes are
+ used instead of <code class="inline-code">\x<em class="code-color">XX</em></code>
+ escapes.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_keep_after">keep_after</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>Removes the part of the string that is not after the first
+ occurrence of the given substring. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"abcdefgh"?keep_after("de")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">fgh</pre></div>
+
+ <p>If the parameter string is not found, it will return an empty
+ string. If the parameter string is a 0-length string, it will return
+ the original string unchanged.</p>
+
+ <p>This method accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
+ 2nd parameter:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"foo : bar"?keep_after(r"\s*:\s*", "r")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">bar</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_keep_after_last">keep_after_last</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.22.</p>
+ </div>
+
+
+ <p>Same as <a href="#ref_builtin_keep_after"><code>keep_after</code></a>,
+ but keeps the part after the last occurrence of the parameter,
+ rather than after the first. Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"foo.bar.txt"?keep_after_last(".")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">txt</pre></div>
+
+ <p>while with <code class="inline-code">keep_after</code> you would get
+ <code class="inline-code">bar.txt</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_keep_before">keep_before</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>Removes the part of the string that starts with the given
+ substring. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?keep_before("de")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">abc</pre></div>
+
+ <p>If the parameter string is not found, it will return the
+ original string unchanged. If the parameter string is a 0-length
+ string, it will return an empty string.</p>
+
+ <p>This method accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
+ 2nd parameter:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"foo : bar"?keep_before(r"\s*:\s*", "r")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">foo</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_keep_before_last">keep_before_last</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.22.</p>
+ </div>
+
+
+ <p>Same as <a href="#ref_builtin_keep_before"><code>keep_before</code></a>,
+ but keeps the part before the last occurrence of the parameter,
+ rather than after the first. Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"foo.bar.txt"?keep_after_last(".")}</pre></div>
+
+ <p>will print</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">foo.bar</pre></div>
+
+ <p>while with <code class="inline-code">keep_before</code> you would get
+ <code class="inline-code">foo</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_last_index_of">last_index_of</h2>
+
+
+
+
+ <p>Returns the index within this string of the last (rightmost)
+ occurrence of the specified substring. It returns the index of the
+ first (leftmost) character of the substring. For example:
+ <code class="inline-code">"abcabc"?last_index_of("ab")</code> will return 3. Also,
+ you can specify the index to start the search from. For example,
+ <code class="inline-code">"abcabc"?last_index_of("ab", 2)</code> will return 0.
+ Note that the second parameter indicates the maximum index of the
+ start of the substring. There is no restriction on the numerical
+ value of the second parameter: if it is negative, it has the same
+ effect as if it were zero, and if it is greater than the length of
+ this string, it has the same effect as if it were equal to the
+ length of this string. Decimal values will be truncated to
+ inegers.</p>
+
+ <p>If the 1st parameter does not occur as a substring in this
+ string (before the given index, if you use the second parameter),
+ then it returns -1.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_left_pad">left_pad</h2>
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.1.</p>
+ </div>
+
+
+ <p>If it's used with 1 parameter, then it inserts spaces on the
+ beginning of the string until it reaches the length that is
+ specified as the parameter. If the string is already as long or
+ longer than the specified length, then it does nothing. For example,
+ this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(5)}]
+[${"a"?left_pad(5)}]
+[${"ab"?left_pad(5)}]
+[${"abc"?left_pad(5)}]
+[${"abcd"?left_pad(5)}]
+[${"abcde"?left_pad(5)}]
+[${"abcdef"?left_pad(5)}]
+[${"abcdefg"?left_pad(5)}]
+[${"abcdefgh"?left_pad(5)}]</pre></div>
+
+ <p>will output this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">[ ]
+[ a]
+[ ab]
+[ abc]
+[ abcd]
+[abcde]
+[abcdef]
+[abcdefg]
+[abcdefgh]</pre></div>
+
+ <p>If it's used with 2 parameters, then the 1st parameter means
+ the same as if you were using the built-in with only 1 parameter,
+ and the second parameter specifies what to insert instead of space
+ characters. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(5, "-")}]
+[${"a"?left_pad(5, "-")}]
+[${"ab"?left_pad(5, "-")}]
+[${"abc"?left_pad(5, "-")}]
+[${"abcd"?left_pad(5, "-")}]
+[${"abcde"?left_pad(5, "-")}]</pre></div>
+
+ <p>will output this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">[-----]
+[----a]
+[---ab]
+[--abc]
+[-abcd]
+[abcde]</pre></div>
+
+ <p>The 2nd parameter can be a string whose length is greater than
+ 1. Then the string will be inserted periodically, for
+ example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(8, ".oO")}]
+[${"a"?left_pad(8, ".oO")}]
+[${"ab"?left_pad(8, ".oO")}]
+[${"abc"?left_pad(8, ".oO")}]
+[${"abcd"?left_pad(8, ".oO")}]</pre></div>
+
+ <p>will output this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">[.oO.oO.o]
+[.oO.oO.a]
+[.oO.oOab]
+[.oO.oabc]
+[.oO.abcd]</pre></div>
+
+ <p>The 2nd parameter must be a string value, and it must be at
+ least 1 character long.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_length">length</h2>
+
+
+
+
+ <p>The number of characters in the string.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_lower_case">lower_case</h2>
+
+
+
+
+ <p>The lower case version of the string. For example
+ <code class="inline-code">"GrEeN MoUsE"?lower_case</code> will be <code class="inline-code">"green
+ mouse"</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_matches">matches</h2>
+
+
+
+
+ <p>This is a "power user" built-in. Ignore it if you
+ don't know <a href="gloss.html#gloss.regularExpression">regular
+ expressions</a>.</p>
+
+ <p>This built-in determines if the string exactly matches the
+ pattern. Also, it returns the list of matching sub-strings. The
+ return value is a multi-type value:</p>
+
+ <ul>
+ <li>
+ <p>Boolean: <code class="inline-code">true</code>, if it the entire string
+ matches the pattern, otherwise <code class="inline-code">false</code>. For
+ example, <code class="inline-code">"fooo"?matches('fo*')</code> is
+ <code class="inline-code">true</code>, but
+ <code class="inline-code">"fooo�bar"?matches('fo*')</code> is
+ <code class="inline-code">false</code>.</p>
+ </li>
+
+ <li>
+ <p>Sequence: the list of matched substrings of the string.
+ Possibly a 0 length sequence.</p>
+ </li>
+ </ul>
+
+ <p>For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if>
+
+<#assign res = "foo bar fyo"?matches("f.?o")>
+<#if res>Matches.<#else>Does not match.</#if>
+Matching sub-strings:
+<#list res as m>
+- ${m}
+</#list></pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">Matches.
+
+Does not match.
+Matching sub-strings:
+- foo
+- fyo</pre></div>
+
+ <p>If the regular expression contains groups (parentheses), then
+ you can access them with the <code class="inline-code">groups</code>
+ built-in:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#-- Entire input match -->
+<#assign res = "John Doe"?matches(r"(\w+) (\w+)")>
+<#if res> <#-- Must not try to access groups if there was no match! -->
+ First name: ${res?groups[1]}
+ Second name: ${res?groups[2]}
+</#if>
+
+<#-- Subtring matches -->
+<#assign res = "aa/rx; ab/r;"?matches("(.+?)/*(.+?);")>
+<#list res as m>
+ - "${m}" is "${m?groups[1]}" per "${m?groups[2]}"
+</#list></pre></div>
+
+ <p>This will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output"> First name: John
+ Second name: Doe
+
+ - "aa/rx;" is "a" per "a/rx"
+ - " ab/r;" is " " per "ab/r"</pre></div>
+
+ <p>Notes regarding the behavior of the <code class="inline-code">groups</code>
+ built-in:</p>
+
+ <ul>
+ <li>
+ <p>It works both with substring matches and with the result
+ of entire string matching (as it was shown in the above
+ example)</p>
+ </li>
+
+ <li>
+ <p>The first item in the sequence that
+ <code class="inline-code">groups</code> returns is the whole substring matched
+ by the regular expression. Hence, the index of the first
+ explicit regular expression group (with other words, of the
+ first <code class="inline-code">(<em class="code-color">...</em>)</code> in the
+ regular expression) is 1, and not 0. Also, because of this, the
+ size of the sequence is one more than the number of explicit
+ regular expression groups.</p>
+ </li>
+
+ <li>
+ <p>The size of the sequence returned by
+ <code class="inline-code">groups</code> only depends on the number of explicit
+ groups in the regular expression, and so it will be the same
+ (non-0) even if there was no match found for the regular
+ expression. Attempting to access an item of the sequence (as in
+ <code class="inline-code">res?groups[1]</code>) when there was match will
+ cause an error. Thus, before accessing the groups, you should
+ always check if there was any match (as in <code class="inline-code"><#if
+ res><em class="code-color">access the groups
+ here</em></#if></code>).</p>
+ </li>
+
+ <li>
+ <p>When there's a match for the regular expression, but not
+ for a certain explicit group inside the regular expression, then
+ for that group the sequence will contain a 0 length string. So
+ accessing a group that matches nothing is safe, as far as the
+ containing regular expression has matched something.</p>
+ </li>
+ </ul>
+
+ <p><code class="inline-code">matches</code> accepts an optional 2nd parameter,
+ the <a href="#ref_builtin_string_flags">flags</a>. Note that
+ it doesn't support flag <code class="inline-code">f</code>, and ignores the
+ <code class="inline-code">r</code> flag.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_no_esc">no_esc</h2>
+
+
+ <p></p>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.24.</p>
+ </div>
+
+
+ <p>Prevents the <a href="dgui_misc_autoescaping.html">auto-escaping</a> of a value.
+ For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML">
+<#assign s = "<b>Test</b>">
+${s}
+${s?no_esc}</pre></div>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">&lt;b&gt;Test&lt;/b&gt;
+<b>Test</b></pre></div>
+
+ <p>This works by converting the string value to a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ value</a>, which uses the string as the markup as is, and belongs
+ to the current <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output format</a>
+ at the point of the invocation.</p>
+
+ <p>This built-in can also be applied on markup output values,
+ which it will bypass without change, as far as the input markup
+ output value belongs to current output format. If it doesn't, then
+ the markup has to be converted to the current output format, which
+ currently (as of 2.3.24) will be only successful if that value was
+ created by escaping plain text (usually, with
+ <code class="inline-code">?esc</code>).</p>
+
+ <p>This built-in can't be used where the current output format is
+ a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_nonmarkupof">non-markup
+ output format</a>. An attempt to do so will cause a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>.</p>
+
+ <p>This built-in is not related to the deprecated <a href="ref_directive_escape.html"><code>escape</code> and
+ <code>noescape</code> directives</a>. In fact, the parser
+ will prevent using them on the same place, to prevent
+ confusion.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_number">number</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The string converted to numerical value. The number must be in
+ "computer language" format. That is, it must be in the
+ locale independent form, where the decimal separator is dot, and
+ there's no grouping.</p>
+
+ <p>This built-in recognizes numbers in the format that the
+ FreeMarker template language uses. In additionally, it recognizes
+ scientific notation (e.g. <code class="inline-code">"1.23E6"</code>,
+ <code class="inline-code">"1.5e-8"</code>). Since FreeMarker 2.3.21, it also
+ recognizes all XML Schema number formats, like
+ <code class="inline-code">NaN</code>, <code class="inline-code">INF</code>,
+ <code class="inline-code">-INF</code>, plus the Java-native formats
+ <code class="inline-code">Infinity</code> and <code class="inline-code">-Infinity</code>.</p>
+
+ <p>If the string is not in the appropriate format, an error will
+ abort template processing when you try to access this
+ built-in.</p>
+
+ <p><span class="marked-for-programmers">In fact, the string is parsed by
+ the <code class="inline-code">toNumber</code> method of the current
+ <code class="inline-code">arithmetic_engine</code>, which is configuration
+ setting. However, that method should behave similarly as described
+ above.</span></p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_replace">replace</h2>
+
+
+
+
+ <p>It is used to replace all occurrences of a string in the
+ original string with another string. It does not deal with word
+ boundaries. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"this is a car acarus"?replace("car", "bulldozer")}</pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">this is a bulldozer abulldozerus</pre></div>
+
+ <p>The replacing occurs in left-to-right order. This means that
+ this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"aaaaa"?replace("aaa", "X")}</pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">Xaa</pre></div>
+
+ <p>If the 1st parameter is an empty string, then all occurrences
+ of the empty string will be replaced, like
+ <code class="inline-code">"foo"?replace("","|")</code> will evaluate to
+ <code class="inline-code">"|f|o|o|"</code>.</p>
+
+ <p><code class="inline-code">replace</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
+ 3rd parameter.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_right_pad">right_pad</h2>
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.1. It
+ doesn't exist in 2.3.</p>
+ </div>
+
+
+ <p>This is the same as <a href="#ref_builtin_left_pad"><code>left_pad</code></a>,
+ but it inserts the characters at the end of the string instead of
+ the beginning of the string.</p>
+
+ <p>Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">[${""?right_pad(5)}]
+[${"a"?right_pad(5)}]
+[${"ab"?right_pad(5)}]
+[${"abc"?right_pad(5)}]
+[${"abcd"?right_pad(5)}]
+[${"abcde"?right_pad(5)}]
+[${"abcdef"?right_pad(5)}]
+[${"abcdefg"?right_pad(5)}]
+[${"abcdefgh"?right_pad(5)}]
+
+[${""?right_pad(8, ".oO")}]
+[${"a"?right_pad(8, ".oO")}]
+[${"ab"?right_pad(8, ".oO")}]
+[${"abc"?right_pad(8, ".oO")}]
+[${"abcd"?right_pad(8, ".oO")}]</pre></div>
+
+ <p>This will output this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">[ ]
+[a ]
+[ab ]
+[abc ]
+[abcd ]
+[abcde]
+[abcdef]
+[abcdefg]
+[abcdefgh]
+
+[.oO.oO.o]
+[aoO.oO.o]
+[abO.oO.o]
+[abc.oO.o]
+[abcdoO.o]</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_remove_beginning">remove_beginning</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>Removes the parameter substring from the beginning of the
+ string, or returns the original string if it doesn't start with the
+ parameter substring. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?remove_beginning("abc")}
+${"foobar"?remove_beginning("abc")}</pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">def
+foobar</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_remove_ending">remove_ending</h2>
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>Removes the parameter substring from the ending of the string,
+ or returns the original string if it doesn't end with the parameter
+ substring. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?remove_ending("def")}
+${"foobar"?remove_ending("def")}</pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">abc
+foobar</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_rtf">rtf (deprecated)</h2>
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is <em>deprecated</em> by the
+ <a href="dgui_misc_autoescaping.html">auto-escaping
+ mechanism</a> introduced in 2.3.24. To prevent double escaping
+ and confusion in general, using this built-in on places where
+ auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
+ migration, this built-in silently bypasses RTF <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ values</a> without changing them.</p>
+ </div>
+
+
+
+
+
+
+ <p>The string as Rich text (RTF text). That is, the string with
+ all:</p>
+
+ <ul>
+ <li>
+ <p><code class="inline-code">\</code> replaced with
+ <code class="inline-code">\\</code></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">{</code> replaced with
+ <code class="inline-code">\{</code></p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">}</code> replaced with
+ <code class="inline-code">\}</code></p>
+ </li>
+ </ul>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_split">split</h2>
+
+
+
+
+ <p>It is used to split a string into a sequence of strings along
+ the occurrences of another string. For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#list "someMOOtestMOOtext"?split("MOO") as x>
+- ${x}
+</#list></pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">- some
+- test
+- text</pre></div>
+
+ <p>Note that it is assumed that all occurrences of the separator
+ is before a new item (except with <code class="inline-code">"r"</code> flag - see
+ later), thus:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#list "some,,test,text,"?split(",") as x>
+- "${x}"
+</#list></pre></div>
+
+ <p>will print:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">- "some"
+- ""
+- "test"
+- "text"
+- ""</pre></div>
+
+ <p><code class="inline-code">split</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
+ 2nd parameter. There's a historical glitch with the
+ <code class="inline-code">r</code> (regular expression) flag; it removes the empty
+ elements from the end of the resulting list, so with
+ <code class="inline-code">?split(",", "r")</code> in the last example the last
+ <code class="inline-code">""</code> would be missing from the output.</p>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>To check if a strings ends with something and append it
+ otherwise, use <a href="#ref_builtin_ensure_ends_with">the
+ <code>ensure_ends_with</code> built-in</a>.</p>
+ </div>
+
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_starts_with">starts_with</h2>
+
+
+
+
+ <p>Returns if this string starts with the specified substring.
+ For example <code class="inline-code">"redirect"?starts_with("red")</code> returns
+ boolean <code class="inline-code">true</code>. Also,
+ <code class="inline-code">"red"?starts_with("red")</code> will return
+ <code class="inline-code">true</code>.</p>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>To check if a strings starts with something and prepend it
+ otherwise, use <a href="#ref_builtin_ensure_starts_with">the
+ <code>ensure_starts_with</code> built-in</a>.</p>
+ </div>
+
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_string_for_string">string (when used with a string value)</h2>
+
+
+ <p>Does nothing, just returns the string as-is. The exception is
+ that if the value is a multi-type value (e.g. it is both string and
+ sequence at the same time), then the resulting value will be only a
+ simple string, not a multi-type value. This can be utilized to
+ prevent the artifacts of multi-typing.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_substring">substring (deprecated)</h2>
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is deprecated since FreeMarker 2.3.21 by <a href="dgui_template_exp.html#dgui_template_exp_stringop_slice">slicing
+ expressions</a>, like
+ <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..<<em class="code-color">toExclusive</em>]</code>,
+ <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..]</code>,
+ and
+ <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..*<em class="code-color">maxLength</em>]</code>.</p>
+
+ <p>A warning if you are processing XML: Since slicing
+ expressions work both for sequences and strings, and since XML
+ nodes are typically both sequences and strings at the same time,
+ there the equivalent expression is
+ <code class="inline-code"><em class="code-color">someXmlNode</em>?string[<em class="code-color">from</em>..<<em class="code-color">toExclusive</em>]</code>
+ and
+ <code class="inline-code"><em class="code-color">exp</em>?string[<em class="code-color">from</em>..]</code>,
+ as without <code class="inline-code">?string</code> it would slice the node
+ sequence instead of the text value of the node.</p>
+ </div>
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>Some of the typical use-cases of string slicing is covered
+ by convenient built-ins: <a href="#ref_builtin_remove_beginning"><code>remove_beginning</code></a>,
+ <a href="#ref_builtin_remove_ending"><code>remove_ending</code></a>,
+ <a href="#ref_builtin_keep_before"><code>keep_before</code></a>,
+ <a href="#ref_builtin_keep_after"><code>keep_after</code></a>,
+ <a href="#ref_builtin_keep_before_last"><code>keep_before_last</code></a>,
+ <a href="#ref_builtin_keep_after_last"><code>keep_after_last</code></a></p>
+ </div>
+
+
+ <p>Synopsis:
+ <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>,
+ <em class="code-color">toExclusive</em>)</code>, also callable as
+ <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>)</code></p>
+
+ <p>A substring of the string.
+ <code class="inline-code"><em class="code-color">from</em></code> is the index of
+ the first character. It must be a number that is at least 0 and less
+ than or equal with
+ <code class="inline-code"><em class="code-color">toExclusive</em></code>, or else
+ an error will abort the template processing. The
+ <code class="inline-code"><em class="code-color">toExclusive</em></code> is the
+ index of the character position after the last character of the
+ substring, or with other words, it is one greater than the index of
+ the last character. It must be a number that is at least 0 and less
+ than or equal to the length of the string, or else an error will
+ abort the template processing. If the
+ <code class="inline-code"><em class="code-color">toExclusive</em></code> is
+ omitted, then it defaults to the length of the string. If a
+ parameter is a number that is not an integer, only the integer part
+ of the number will be used.</p>
+
+ <p>Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">- ${'abc'?substring(0)}
+- ${'abc'?substring(1)}
+- ${'abc'?substring(2)}
+- ${'abc'?substring(3)}
+
+- ${'abc'?substring(0, 0)}
+- ${'abc'?substring(0, 1)}
+- ${'abc'?substring(0, 2)}
+- ${'abc'?substring(0, 3)}
+
+- ${'abc'?substring(0, 1)}
+- ${'abc'?substring(1, 2)}
+- ${'abc'?substring(2, 3)}</pre></div>
+
+ <p>The output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">- abc
+- bc
+- c
+-
+
+-
+- a
+- ab
+- abc
+
+- a
+- b
+- c</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_trim">trim</h2>
+
+
+
+
+ <p>The string without leading and trailing white-space.
+ Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template">(${" green mouse "?trim})</pre></div>
+
+ <p>The output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">(green mouse)</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_uncap_first">uncap_first</h2>
+
+
+
+
+ <p>The opposite of <a href="#ref_builtin_cap_first"><code>cap_first</code></a>.
+ The string with the very first word of the string
+ un-capitalized.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_upper_case">upper_case</h2>
+
+
+
+
+ <p>The upper case version of the string. For example
+ <code class="inline-code">"GrEeN MoUsE"</code> will be <code class="inline-code">"GREEN
+ MOUSE"</code>.</p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_url">url</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.1. It
+ doesn't exist in 2.3.</p>
+ </div>
+
+
+ <p>The string after URL escaping. This means that all
+ non-US-ASCII and reserved URL characters will be escaped with
+ <code class="inline-code">%<em class="code-color">XX</em></code>. For
+ example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#assign x = 'a/b c'>
+${x?url}</pre></div>
+
+ <p>The output will be (assuming that the charset used for the
+ escaping is an US-ASCII compatible charset):</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">a%2Fb%20c</pre></div>
+
+ <p>Note that it escapes <em>all</em> reserved URL
+ characters (<code class="inline-code">/</code>, <code class="inline-code">=</code>,
+ <code class="inline-code">&</code>, ...etc), so this encoding can be used for
+ encoding query parameter values, for example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a></pre></div>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>Above no HTML encoding (<code class="inline-code">?html</code>) was
+ needed, because URL escaping escapes all reserved HTML characters
+ anyway. But watch: always quote the attribute value, and always
+ with normal quotation mark (<code class="inline-code">"</code>), never with
+ apostrophe quotation mark (<code class="inline-code">'</code>), because
+ apostrophe quotation mark is not escaped by the URL
+ escaping.</p>
+ </div>
+
+
+ <p>To do URL escaping a <a href="gloss.html#gloss.charset">charset</a> must be chosen that will be
+ used for calculating the escaped parts
+ (<code class="inline-code">%<em class="code-color">XX</em></code>). If you are HTML
+ page author and you don't really understand this, don't worry: the
+ programmers should configure FreeMarker so that it uses the proper
+ charset by default (<span class="marked-for-programmers">programmers: see
+ more below...</span>). If you are a more technical minded user,
+ then you may want to know that the charset used is specified by the
+ <code class="inline-code">url_escaping_charset</code> setting, that can be set in
+ template execution time (or, preferably, earlier by the
+ programmers). For example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#--
+ This will use the charset specified by the programmers
+ before the template execution has started.
+-->
+<a href="foo.cgi?x=${x?url}">foo</a>
+
+<#-- Use UTF-8 charset for URL escaping from now: -->
+<strong><#setting url_escaping_charset="UTF-8"></strong>
+
+<#-- This will surely use UTF-8 charset -->
+<a href="bar.cgi?x=${x?url}">bar</a></pre></div>
+
+ <p>Furthermore, you can explicitly specify a charset for a single
+ URL escaping as the parameter to the built-in:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url<strong>('ISO-8895-2')</strong>}">foo</a></pre></div>
+
+ <p><span class="marked-for-programmers">If the <code class="inline-code">url</code> built-in has no
+ parameter, then it will use the charset specified as the value of
+ the <code class="inline-code">url_escaping_charset</code> setting. This setting
+ should be set by the software that encloses FreeMarker (e.g. a Web
+ application framework), because it is not set
+ (<code class="inline-code">null</code>) by default. If it is not set, then
+ FreeMarker falls back using the value of the
+ <code class="inline-code">output_encoding</code> setting, which is also not set by
+ default, so it is again the task of the enclosing software. If the
+ <code class="inline-code">output_encoding</code> setting is not set either, then
+ the parameterless <code class="inline-code">url</code> built-in can't be executed,
+ and it will cause execution time error. Of course, the
+ <code class="inline-code">url</code> built-in with parameter always
+ works.</span></p>
+
+ <p><span class="marked-for-programmers">It's possible to set
+ <code class="inline-code">url_escaping_charset</code> in the template with the
+ <code class="inline-code">setting</code> directive, but it is bad practice, at
+ least in true MVC applications. The
+ <code class="inline-code">output_encoding</code> setting can't be set with the
+ <code class="inline-code">setting</code> directive, so that's surely the task of
+ the enclosing software. You may find more information regarding this
+ <a href="pgui_misc_charset.html">here...</a></span></p>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_url_path">url_path</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is available since FreeMarker 2.3.21.</p>
+ </div>
+
+
+ <p>This is the same as <a href="#ref_builtin_url">the
+ <code>url</code> built-in</a>, except that it doesn't
+ escape slash (<code class="inline-code">/</code>) characters. This meant to be
+ used for converting paths (like paths coming from the OS or some
+ content repository) that use slash (not backslash!) to a path the
+ can be inserted into an URL. The most common reason why this
+ conversion is needed is that folder names or file names might
+ contain non-US-ASCII letters ("national"
+ characters).</p>
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>Just like with <a href="#ref_builtin_url">the
+ <code>url</code> built-in</a>, the desired URL escaping
+ charset (or as a fall back, the output encoding) must be set in
+ the FreeMarker configuration settings, or else the built-in will
+ give error. Or, you you have to specify the charset like
+ <code class="inline-code">somePath?url_path('utf-8')</code>.</p>
+ </div>
+
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_word_list">word_list</h2>
+
+
+
+
+ <p>A sequence that contains all words of the string in the order
+ as they appear in the string. Words are continual character
+ sequences that contain any character but <a href="gloss.html#gloss.whiteSpace">white-space</a>. Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#assign words = " a bcd, . 1-2-3"?word_list>
+<#list words as word>[${word}]</#list></pre></div>
+
+ <p>will output:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">[a][bcd,][.][1-2-3]</pre></div>
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_xhtml">xhtml (deprecated)</h2>
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is <em>deprecated</em> by the
+ <a href="dgui_misc_autoescaping.html">auto-escaping
+ mechanism</a> introduced in 2.3.24. To prevent double escaping
+ and confusion in general, using this built-in on places where
+ auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
+ migration, this built-in silently bypasses HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ values</a> without changing them.</p>
+ </div>
+
+
+
+
+
+
+ <p>The string as XHTML text. That is, the string with all:</p>
+
+ <ul>
+ <li>
+ <code class="inline-code"><</code> replaced with
+ <code class="inline-code">&lt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">></code> replaced with
+ <code class="inline-code">&gt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">&</code> replaced with
+ <code class="inline-code">&amp;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">"</code> replaced with
+ <code class="inline-code">&quot;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">'</code> replaced with
+ <code class="inline-code">&#39;</code>
+ </li>
+ </ul>
+
+ <p>The only difference between this built-in and the
+ <code class="inline-code">xml</code> built-in is that the <code class="inline-code">xhtml</code>
+ built-in escapes <code class="inline-code">'</code> as
+ <code class="inline-code">&#39;</code> instead of as
+ <code class="inline-code">&apos;</code>, because some older browsers don't
+ know <code class="inline-code">&apos;</code>.</p>
+
+ <div class="callout warning">
+ <strong class="callout-label">Warning!</strong>
+
+ <p>When inserting the value of an attribute, always quote it,
+ or else it can be exploited by attacker! This is WRONG:
+ <code class="inline-code"><input name="user" value=${user?xhtml}/></code>.
+ These are good: <code class="inline-code"><input name="user"
+ value="${user?xhtml}"/></code>, <code class="inline-code"><input
+ name="user" value='${user?xhtml}'/></code>.</p>
+ </div>
+
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_xml">xml (deprecated)</h2>
+
+
+ <div class="callout note">
+ <strong class="callout-label">Note:</strong>
+
+ <p>This built-in is <em>deprecated</em> by the
+ <a href="dgui_misc_autoescaping.html">auto-escaping
+ mechanism</a> introduced in 2.3.24. To prevent double escaping
+ and confusion in general, using this built-in on places where
+ auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
+ migration, this built-in silently bypasses XML and HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
+ values</a> without changing them.</p>
+ </div>
+
+
+
+
+
+
+ <p>The string as XML text. That is, the string with all:</p>
+
+ <ul>
+ <li>
+ <code class="inline-code"><</code> replaced with
+ <code class="inline-code">&lt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">></code> replaced with
+ <code class="inline-code">&gt;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">&</code> replaced with
+ <code class="inline-code">&amp;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">"</code> replaced with
+ <code class="inline-code">&quot;</code>
+ </li>
+
+ <li>
+ <code class="inline-code">'</code> replaced with
+ <code class="inline-code">&apos;</code>
+ </li>
+ </ul>
+
+ <div class="callout warning">
+ <strong class="callout-label">Warning!</strong>
+
+ <p>When inserting the value of an attribute, always quote it,
+ or else it can be exploited by attackers! This is WRONG:
+ <code class="inline-code"><input name="user" value=${user?xml}/></code>.
+ These are good: <code class="inline-code"><input name="user"
+ value="${user?xml}"/></code>, <code class="inline-code"><input name="user"
+ value='${user?xml}'/></code>.</p>
+ </div>
+
+
+
+
+
+
+<h2 class="content-header header-section2" id="ref_builtin_string_flags">Common flags</h2>
+
+
+ <p>Many string built-ins accept an optional string parameter, the
+ so called "flags". In this string, each letter
+ influences a certain aspect of the behavior of the built-in. For
+ example, letter <code class="inline-code">i</code> means that the built-in should
+ not differentiate the lower and upper-case variation of the same
+ letter. The order of the letters in the flags string is not
+ significant.</p>
+
+ <p>This is the complete list of letters (flags):</p>
+
+ <ul>
+ <li>
+ <p><code class="inline-code">i</code>: Case insensitive: do not
+ differentiate the lower and upper-case variation of the same
+ letter.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">f</code>: First only. That is,
+ replace/find/etc. only the first occurrence of something.</p>
+ </li>
+
+ <li>
+ <p> <code class="inline-code">r</code>: The substring to find is a
+ <a href="gloss.html#gloss.regularExpression">regular
+ expression</a>. FreeMarker uses the variation of regular
+ expressions described at <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html</a>
+ (note that the presence of some pattern features depends on the
+ Java version used).</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">m</code>: Multi-line mode for regular
+ expressions. In multi-line mode the expressions
+ <code class="inline-code">^</code> and <code class="inline-code">$</code> match just after
+ or just before, respectively, a line terminator or the end of
+ the string. By default these expressions only match at the
+ beginning and the end of the entire string. Note that
+ <code class="inline-code">^</code> and <code class="inline-code">$</code> doesn't match the
+ line-break character itself.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">s</code>: Enables dot-all mode for regular
+ expressions (same as Perl singe-line mode). In dot-all mode, the
+ expression <code class="inline-code">.</code> matches any character, including
+ a line terminator. By default this expression does not match
+ line terminators.</p>
+ </li>
+
+ <li>
+ <p><code class="inline-code">c</code>: Permits whitespace and comments in
+ regular expressions.</p>
+ </li>
+ </ul>
+
+ <p>Example:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-template"><#assign s = 'foo bAr baar'>
+${s?replace('ba', 'XY')}
+i: ${s?replace('ba', 'XY', 'i')}
+if: ${s?replace('ba', 'XY', 'if')}
+r: ${s?replace('ba*', 'XY', 'r')}
+ri: ${s?replace('ba*', 'XY', 'ri')}
+rif: ${s?replace('ba*', 'XY', 'rif')}</pre></div>
+
+ <p>This outputs this:</p>
+
+
+
+<div class="code-wrapper"><pre class="code-block code-output">foo bAr XYar
+i: foo XYr XYar
+if: foo XYr baar
+r: foo XYAr XYr
+ri: foo XYr XYr
+rif: foo XYr baar</pre></div>
+
+ <p>This
<TRUNCATED>