http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a4004324/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 deleted file mode 100644 index 6ebdd42..0000000 --- a/builds/2.3.26-nightly/ref_builtins_string.html +++ /dev/null @@ -1,2374 +0,0 @@ -<!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>
<TRUNCATED>
