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>
