| <!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>Seldom used and expert built-ins - 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="Seldom used and expert built-ins"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/ref_builtins_expert.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/ref_builtins_expert.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_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_expert.html"><span itemprop="name">Seldom used and expert built-ins</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker Manual","Template Language Reference","Built-in Reference","Seldom used and expert built-ins"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_builtins_type_independent.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directives.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_builtins_expert" itemprop="headline">Seldom used and expert built-ins</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_absolute_template_name" data-menu-target="ref_builtin_absolute_template_name">absolute_template_name</a></li><li><a class="page-menu-link" href="#ref_buitin_api_and_has_api" data-menu-target="ref_buitin_api_and_has_api">api, has_api</a></li><li><a class="page-menu-link" href="#ref_builtin_numType" data-menu-target="ref_builtin_numType">byte, double, float, int, long, short</a></li><li><a class="page-menu-link" href="#ref_builtin_eval" data-menu-target="ref_builtin_eval">eval</a></li><li><a class="page-menu-link" href="#ref_builtin_eval_json" data-menu-target="ref_builtin_eval_json">eval_json</a></li><li><a class="page-menu-link" href="#ref_builtin_has_content" data-menu-target="ref_builtin_has_content">has_content</a></li><li><a class="page-menu-link" href="#ref_builtin_interpret" data-menu-target="ref_builtin_interpret">interpret</a></li><li><a class="page-menu-link" href="#ref_builtin_isType" data-menu-target="ref_builtin_isType">is_...</a></li><li><a class="page-menu-link" href="#ref_builtin_markup_string" data-menu-target="ref_builtin_markup_string">markup_string</a></li><li><a class="page-menu-link" href="#ref_builtin_namespace" data-menu-target="ref_builtin_namespace">namespace</a></li><li><a class="page-menu-link" href="#ref_builtin_new" data-menu-target="ref_builtin_new">new</a></li><li><a class="page-menu-link" href="#ref_builtin_numToDate" data-menu-target="ref_builtin_numToDate">number_to_date, number_to_time, number_to_datetime</a></li><li><a class="page-menu-link" href="#ref_builtin_sequence" data-menu-target="ref_builtin_sequence">sequence</a></li><li><a class="page-menu-link" href="#ref_builtin_with_args" data-menu-target="ref_builtin_with_args">with_args</a></li><li><a class="page-menu-link" href="#ref_builtin_with_args_last" data-menu-target="ref_builtin_with_args_last">with_args_last</a></li></ul> </div><p>These are the built-ins that normally you should not use, but in |
| exceptional situations (debugging, advanced macros) they can be |
| useful. If you need to use these in your normal page templates, you |
| may revisit the data-model so you don't need to use these.</p> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_absolute_template_name">absolute_template_name</h2> |
| |
| |
| |
| |
| <p>Converts a template name to an absolute name, which can be |
| safely passed to <code class="inline-code"><#include |
| <em class="code-color">name</em>></code> or |
| <code class="inline-code"><#import <em class="code-color">name</em> as |
| <em class="code-color">ns</em>></code> or |
| <code class="inline-code">.get_optional_template(<em class="code-color">name</em>)</code> |
| and such in <em>another</em> template, as it won't be |
| misinterpreted to be relative to the directory of the template that |
| contains the <code class="inline-code">include</code>, <code class="inline-code">import</code>, |
| etc. For example, if you are in template |
| <code class="inline-code">"dir/here.ftl"</code>, then |
| <code class="inline-code">"target.ftl"</code> is converted to |
| <code class="inline-code">"/dir/target.ftl"</code> (note the initial |
| <code class="inline-code">/</code>). If now you pass this value to a template in |
| <code class="inline-code">"other-dir/there.ftl"</code>, where it's passed to the |
| <code class="inline-code">include</code> directive, then it won't be |
| misinterpreted as <code class="inline-code">"other-dir/target.ftl"</code>, like |
| <code class="inline-code">"target.ftl"</code> would have been.</p> |
| |
| <p>Optionally, you can specify a root based name (a name that's |
| either relative to the template root directory, or is absolute) that |
| will be used instead of the name of the current template, like |
| <code class="inline-code"><em class="code-color">pathToConver</em>?absolute_template_name(<em class="code-color">otherTemplateName</em>)</code>.</p> |
| |
| <p>Example of an application (also uses <a href="ref_specvar.html#ref_specvar_caller_template_name"><code>.caller_template_name</code></a> |
| and <a href="ref_specvar.html#ref_specvar_get_optional_template"><code>.get_optional_template</code></a>):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#-- |
| <@smileyInclude name /> behaves like <#include name>, but prints a "(:" before the |
| template, or prints "):" instead if the template is missing. |
| |
| Note that just like with #include, if name is relative, it's resolved based on the |
| directory of the caller template, not of the template that defines this macro. As |
| .get_optional_template resolves relative names based on the current template, we |
| had to convert the name to an absolute name based on the caller template before |
| passing it to it. |
| --> |
| <#macro smileyInclude name> |
| <#local t = .get_optional_template( |
| name<strong>?absolute_template_name</strong>(.caller_template_name))> |
| <#if t.exists> |
| (: |
| <@t.include /> |
| <#else> |
| ): |
| </#if> |
| </#macro></pre> </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_buitin_api_and_has_api">api, has_api</h2> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>These built-ins exists since FreeMarker 2.3.22</p> |
| </div> |
| |
| |
| <p><code class="inline-code"><em class="code-color">value</em>?api</code> |
| provides access to the API (usually, the Java API) of |
| <code class="inline-code"><em class="code-color">value</em></code>, like |
| <code class="inline-code"><em class="code-color">value</em>?api.<em class="code-color">someJavaMethod()</em></code> |
| or |
| <code class="inline-code"><em class="code-color">value</em>?api.<em class="code-color">someBeanProperty</em></code>, |
| if the value itself supports exposing its API. This meant to be used |
| rarely, when you need to call a Java method of an object, but the |
| by-design simplistic view of the value that FreeMarker exposes to |
| the templates hides that, and there's no equivalent built-in either. |
| For example, when you put a <code class="inline-code">Map</code> into the |
| data-model (and you are using the default object wrapper), |
| <code class="inline-code">myMap.myMethod()</code> in a template basically |
| translates to <code class="inline-code">((Method) |
| myMap.get("myMethod")).invoke(...)</code> in Java, thus you can't |
| call <code class="inline-code">myMethod</code>. If, however, you write |
| <code class="inline-code">myMap?api.myMethod()</code> instead, that means |
| <code class="inline-code">myMap.myMethod()</code> in Java. Similarly, |
| <code class="inline-code">myMap?api.myProperty</code> translates to |
| <code class="inline-code">myMap.getMyProperty()</code> in Java, instead of to |
| <code class="inline-code">myMap.get("myProperty")</code>.</p> |
| |
| <p><em>You should avoid using <code class="inline-code">api</code>, and |
| rely on the capabilities of the FTL types and the related built-ins |
| as far as possible.</em> For example, don't use |
| <code class="inline-code">users?api.size()</code>, but |
| <code class="inline-code">users?size</code>. The variation that uses |
| <code class="inline-code">?api</code> is more verbose, slower, more easily breaks |
| when FreeMarker configuration settings are changed, and most |
| importantly, more prone to break as the technical details of the |
| data-model change. For example, if <code class="inline-code">users</code> is |
| changed from a <code class="inline-code">List</code> to an array, |
| <code class="inline-code">users?size</code> will keep working, while |
| <code class="inline-code">users?api.size()</code> will break.</p> |
| |
| <p>Avoid calling methods that <em>modify</em> an |
| object (especially <code class="inline-code">Map</code>-s and |
| <code class="inline-code">Collection</code>-s) or that aren't thread safe from |
| other reasons. Templates usually aren't expected to modify the |
| objects exposed to them, just to display them. Thus the application |
| may passes some objects to multiple (possibly concurrent) template |
| processings.</p> |
| |
| <p>The <code class="inline-code">api</code> built-in is not everywhere |
| available, some requirements has to be met:</p> |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">api_builtin_enabled</code> configuration |
| setting must be set to <code class="inline-code">true</code>. Its default is |
| <code class="inline-code">false</code> (at least as of 2.3.22) for not |
| lowering the security of existing applications.</p> |
| </li> |
| |
| <li> |
| <p>The value itself has to support it. We are talking about |
| the value as the template sees it, which is created from the |
| original object (that's coming from the data-model or from a |
| Java method return value) value via <a href="pgui_datamodel_objectWrapper.html">object wrapping</a>. |
| Hence, this depends on the <code class="inline-code">object_wrapper</code> |
| FreeMarker configuration setting, and on the class of the |
| wrapped (the original) object:</p> |
| |
| <ul> |
| <li> |
| <p>When the object wrapper is a |
| <code class="inline-code">DefaultObjectWrapper</code> with its |
| <code class="inline-code">incompatibleImprovements</code> set to 2.3.22 or |
| higher (<a href="pgui_datamodel_objectWrapper.html#topic.defaultObjectWrapperIcI">see |
| how to set it here</a>), FTL values made from |
| <code class="inline-code">Map</code>-s and <code class="inline-code">List</code>-s |
| support <code class="inline-code">?api</code>. (Actually, what matters is |
| that its <code class="inline-code">useAdaptersForContainer</code> property |
| is set to <code class="inline-code">true</code>, but that's the default |
| with said <code class="inline-code">incompatibleImprovements</code>.) |
| Other <code class="inline-code">java.util.Collections</code> (such as |
| <code class="inline-code">Set</code>-s) only support |
| <code class="inline-code">?api</code> if |
| <code class="inline-code">DefaultObjectWrapper</code>'s |
| <code class="inline-code">forceLegacyNonListCollections</code> property is |
| set to <code class="inline-code">false</code> (the default is |
| <code class="inline-code">true</code> for better out-of-the-box backward |
| compatibility).</p> |
| </li> |
| |
| <li> |
| <p>When wrapped with pure |
| <code class="inline-code">BeansWrapper</code>, all values support |
| <code class="inline-code">?api</code>.</p> |
| </li> |
| |
| <li> |
| <p>Custom <code class="inline-code">TemplateModel</code>-s can support |
| <code class="inline-code">?api</code> by implementing the |
| <code class="inline-code">freemarker.template.TemplateModelWithAPISupport</code> |
| interface.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>Using <code class="inline-code">?api</code> when it's not allowed in the |
| configuration or when the value doesn't support it will abort |
| template processing with error.</p> |
| |
| <p>Whether a value supports <code class="inline-code">?api</code> can be |
| checked like |
| <code class="inline-code"><em class="code-color">value</em>?has_api</code>, which |
| returns a boolean value. Note that the result of |
| <code class="inline-code">?has_api</code> isn't influenced by the |
| <code class="inline-code">api_builtin_enabled</code> setting.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_numType">byte, double, float, int, long, short</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Returns a <code class="inline-code">SimpleNumber</code> which contains the |
| same value as the original variable, but uses |
| <code class="inline-code">java.lang.<em class="code-color">Type</em></code> for the |
| internal representation of the value. This is useful if a method is |
| overloaded, or if a <code class="inline-code">TemplateModel</code> unwrapper has |
| problem with automatically choosing the suitable |
| <code class="inline-code">java.lang.*</code> type. Note that since version 2.3.9 |
| the unwrapper has been improved substantially, so you will hardly |
| ever need to use these built-ins to convert between numerical types, |
| except for resolving ambiguity in overloaded method |
| invocation.</p> |
| |
| <p>The <code class="inline-code">long</code> built-in can also be used with |
| date, time and date-time values to get the value as |
| <code class="inline-code">java.util.Date.getTime()</code> would return. This is |
| useful if you have to call a Java methods that expect a timestamp as |
| a <code class="inline-code">long</code>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_eval">eval</h2> |
| |
| |
| |
| |
| |
| |
| <p>This built-in evaluates a string as an FTL |
| <em>expression</em>. For example |
| <code class="inline-code">"1+2"?eval</code> returns the number 3. (To render a |
| template that's stored in a string, use the <a href="#ref_builtin_interpret"><code>interpret</code> |
| built-in</a> instead.)</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>Do not use this to evaluate JSON! For that use the <a href="#ref_builtin_eval_json"><code>eval_json</code> |
| built-in</a> instead. While FTL expression language looks |
| similar to JSON, not all JSON is valid FTL expression. Also, FTL |
| expressions can access variables, and call Java methods on them, |
| so if you <code class="inline-code">?eval</code> strings coming from untrusted |
| source, it can become an attack vector.</p> |
| </div> |
| |
| |
| <p>The evaluated expression sees the same variables (such as |
| locals) that are visible at the place of the invocation of |
| <code class="inline-code">eval</code>. That is, it behaves similarly as if in |
| place of <code class="inline-code"><em class="code-color">s</em>?eval</code> you |
| had the <em>value of</em> |
| <code class="inline-code"><em class="code-color">s</em></code> there. Except, it |
| can't use <a href="ref_builtins_loop_var.html">loop variable |
| built-ins</a> that refer to a loop variable that was created |
| outside <code class="inline-code"><em class="code-color">s</em></code>.</p> |
| |
| <p>Regarding the configuration settings that affect the parsing |
| (like syntax) and evaluation the rules are the same as with the |
| <a href="#ref_builtin_interpret"><code>interpret</code> |
| built-in</a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_eval_json">eval_json</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.31.</p> |
| </div> |
| |
| |
| <p>This built-in evaluates a string as a JSON |
| <em>expression</em>, so that you can extract data from |
| inside it. For example, if you receive data in the |
| <code class="inline-code">dataJson</code> variable, but it's unfortunately just a |
| flat string that contains <code class="inline-code">{"name": "foo", "ids": [11, |
| 22]}</code>, then you can extract data from it like this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign data = dataJson<strong>?eval_json</strong>> |
| <p>Name: ${data.name} |
| <p>Ids: |
| <ul> |
| <#list data.ids as id> |
| <li>${id} |
| </#list> |
| </ul></pre> </div> |
| |
| |
| <p>Ideally, you shouldn't need <code class="inline-code">eval_json</code>, |
| since the template should receive data already parsed (to |
| <code class="inline-code">List</code>-s, <code class="inline-code">Map</code>-s, Java beans, |
| etc.). This built-in is there as a workaround, if you can't improve |
| the data-model.</p> |
| |
| <p>The evaluated JSON expression doesn't have to be a JSON object |
| (key-value pairs), it can be any kind of JSON value, like JSON |
| array, JSON number, etc.</p> |
| |
| <p>The syntax understood by this built-in is a superset of |
| JSON:</p> |
| |
| <ul> |
| <li> |
| <p>Java-style comments are supported |
| (<code class="inline-code">/*<em class="code-color">...</em>*/</code> and |
| <code class="inline-code">//<em class="code-color">...</em></code>)</p> |
| </li> |
| |
| <li> |
| <p>BOM (byte order mark) and non-breaking space |
| ("nbsp") are treated as whitespace (in a stricter |
| JSON parser they are errors of occurring around tokens).</p> |
| </li> |
| </ul> |
| |
| <p>No other non-JSON extras are implemented, notably, it's |
| impossible to refer to variables (unlike in the <a href="#ref_builtin_eval"><code>eval</code> built-in</a>). |
| This is important for safety, when receiving JSON from untrusted |
| sources.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_has_content">has_content</h2> |
| |
| |
| |
| |
| <p>It is <code class="inline-code">true</code> if the variable exists (and |
| isn't Java <code class="inline-code">null</code>) and is not "empty", |
| otherwise it is <code class="inline-code">false</code>. The meaning of |
| "empty" depends on the concrete case. This follows |
| intuitive common-sense ideas. The following are empty: a string with |
| 0 length, a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup |
| output value</a> with 0 length markup, a sequence or hash with no |
| sub variables, a collection which has passed the last element. If |
| the value is not of any of these types, then it counts as non-empty |
| if it's a number or a date or a boolean (e.g. <code class="inline-code">0</code> |
| and <code class="inline-code">false</code> are not empty), otherwise it counts as |
| empty. Note that when your data-model implements multiple template |
| model interfaces you may get unexpected results. However, when in |
| doubt you can use always use <code class="inline-code">expr!?size > 0</code> or |
| <code class="inline-code">expr!?length > 0</code> instead of |
| <code class="inline-code">expr?has_content</code>.</p> |
| |
| <p>This buit-in is exceptional in that you can use the |
| parentheses trick like with the <a href="dgui_template_exp.html#dgui_template_exp_missing_default">default value |
| operator</a>. That is, you can write both |
| <code class="inline-code">product.color?has_content</code> and |
| <code class="inline-code">(product.color)?has_content</code>. The first doesn't |
| handle the case when <code class="inline-code">product</code> is missing, the last |
| does.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_interpret">interpret</h2> |
| |
| |
| |
| |
| <p>This built-in parses a string as an FTL template, and returns |
| an user-defined directive that executes that template, just as if a |
| template with that content were <a href="ref_directive_include.html"><code>include</code>-d</a> |
| at that point. Example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign x=["a", "b", "c"]> |
| <#assign templateSource = r"<#list x as y>${y}</#list>"> |
| <#-- Note: That r was needed so that the ${y} is not interpreted above --> |
| <#assign inlineTemplate = templateSource?interpret> |
| <@inlineTemplate /></pre> </div> |
| |
| |
| <p>The output:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">abc</pre> </div> |
| |
| |
| <p>As you can see, <code class="inline-code">inlineTemplate</code> is a |
| user-defined directive that, when executed, runs the template whose |
| content is the value of <code class="inline-code">templateSource</code>.</p> |
| |
| <p>The name of the template created by |
| <code class="inline-code">interpret</code> is the name of the template that calls |
| <code class="inline-code">interpret</code>, plus |
| <code class="inline-code">"->anonymous_interpreted"</code>. For example, if the |
| template that calls the built-in is |
| <code class="inline-code">"foo/bar.ftl"</code>, then the name of the resulting |
| template is |
| <code class="inline-code">"foo/bar.ftl->anonymous_interpreted"</code>. Thus, |
| relative paths inside the interpreted template are relative to this |
| path (i.e., the base directory will be <code class="inline-code">"foo"</code>), |
| and errors inside the interpreted template will point to this |
| generated template name.</p> |
| |
| <p>For more helpful error messages, you can override the template |
| name part after the <code class="inline-code">"->"</code>. For example, let's |
| say <code class="inline-code">mailTemplateSource</code> comes from the |
| <code class="inline-code">mail_template</code> database table, and in the case of |
| error, you want the error log to contain the database ID of the |
| failing template:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign inlineTemplate = [mailTemplateSource, "mail_templates id=${mailTemplateId}"]?interpret></pre> </div> |
| |
| |
| <p>As you can see, <code class="inline-code">interpret</code> can be applied on |
| a sequence of two items, in which case the first item is the FTL |
| string to interpret, and the second items is the template name used |
| after the <code class="inline-code">"->"</code>.</p> |
| |
| <p>The configuration settings that affect the interpreted |
| template are the same as of the surrounding template, except that |
| parser settings specified in the <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code> directive</a> |
| or was established via tag syntax or naming convention |
| auto-detection are instead coming from the |
| <code class="inline-code">Configuration</code> object (or naturally, from the |
| <a href="pgui_config_templateconfigurations.html"><code>TemplateConfiguration</code></a>, |
| if there's any). Thus the tag syntax, naming convention, whitespace |
| handling, etc. of the interpreted template is independent of that |
| established <em>inside</em> the surrounding template. An |
| important exception from this rule is that the <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output format</a> |
| and auto-escaping policy is inherited from the lexical context where |
| <code class="inline-code">interpret</code> is called from. For example in a |
| template that has <code class="inline-code"><#ftl |
| output_format="XML"></code> header (or if you are inside a |
| <code class="inline-code"><#output_format |
| "XML"><em class="code-color">...</em></#output_format></code> |
| block), <code class="inline-code">interpret</code> calls in it will produce |
| directives with XML output format.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_isType">is_...</h2> |
| |
| |
| |
| |
| |
| |
| <p>These built-ins check the type of a variable, and returns |
| <code class="inline-code">true</code> or <code class="inline-code">false</code> depending on the |
| type. The list of |
| <code class="inline-code">is_<em class="code-color">...</em></code> |
| built-ins:</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Built-in</th> |
| |
| |
| <th>Returns <code class="inline-code">true</code> if the value is a ...</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">is_string</code></td> |
| |
| |
| <td>string</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_number</code></td> |
| |
| |
| <td>number</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_boolean</code></td> |
| |
| |
| <td>boolean</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_date</code></td> |
| |
| |
| <td>Don't use it! Same as <code class="inline-code">is_date_like</code>, use |
| that instead. Later may changes meaning to |
| <code class="inline-code">date_only</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_date_like</code></td> |
| |
| |
| <td>date-like, means either date, time or date-time, or |
| date-like with unknown precise type (since FreeMarker |
| 2.3.21)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_date_only</code></td> |
| |
| |
| <td>date (no time of the day part) (since FreeMarker |
| 2.3.21)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_time</code></td> |
| |
| |
| <td>time (no year-month-day part) (since FreeMarker |
| 2.3.21)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_datetime</code></td> |
| |
| |
| <td>date-time (contains both year-month-day and time of the |
| day)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_unknown_date_like</code></td> |
| |
| |
| <td>date-like where we don't know if it's a date or a time or |
| a date-time</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_method</code></td> |
| |
| |
| <td>method</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_transform</code></td> |
| |
| |
| <td>transform</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_macro</code></td> |
| |
| |
| <td>macro or function (yes, also for function; a historical |
| glitch)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_hash</code></td> |
| |
| |
| <td>hash (including extended hash)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_hash_ex</code></td> |
| |
| |
| <td>extended hash (supports <code class="inline-code">?keys</code> and |
| <code class="inline-code">?values</code>)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_sequence</code></td> |
| |
| |
| <td>sequence (Historical quirk: Before <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set"><code>incompatible_improvements</code></a> |
| 2.3.24 it returns <code class="inline-code">true</code> for Java methods as |
| they implement the |
| <code class="inline-code">[<em class="code-color">index</em>]</code> |
| operator, however, they fail on |
| <code class="inline-code">?size</code>.)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_collection</code></td> |
| |
| |
| <td>collection (including extended collection)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_collection_ex</code></td> |
| |
| |
| <td>extended collection (supports |
| <code class="inline-code">?size</code>)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_enumerable</code></td> |
| |
| |
| <td>sequence or collection</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_indexable</code></td> |
| |
| |
| <td>sequence (Historical quirk: it returns |
| <code class="inline-code">true</code> for Java methods as they implement the |
| <code class="inline-code">[<em class="code-color">index</em>]</code> |
| operator.)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_directive</code></td> |
| |
| |
| <td>Whatever kind of directive (for example a macro, <span class="marked-for-programmers">or |
| <code class="inline-code">TemplateDirectiveModel</code>, |
| <code class="inline-code">TemplateTransformModel</code>, etc.</span>), or |
| function (a historical glitch)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_node</code></td> |
| |
| |
| <td>node</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_markup_output</code></td> |
| |
| |
| <td>markup output (a value that won't be <a href="dgui_misc_autoescaping.html">auto-escaped</a>)</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_markup_string">markup_string</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>Returns the markup stored inside a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output value</a> |
| as string. This is useful if the value has to be passed to a Java |
| method for a <code class="inline-code">String</code> parameter, or if we want to |
| manipulate the markup directly in the template. Note that the |
| resulting string can be converted back to markup output value with |
| <a href="ref_builtins_string.html#ref_builtin_no_esc"><code>?no_esc</code></a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_namespace">namespace</h2> |
| |
| |
| |
| |
| <p>This built-in returns the namespace (i.e. the |
| "gate" hash to the namespace) associated with a macro |
| or function variable. You can use it with macros and functions |
| only.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_new">new</h2> |
| |
| |
| |
| |
| |
| |
| <p>This is to create a variable of a certain |
| <code class="inline-code">TemplateModel</code> implementation.</p> |
| |
| <p>On the left side of <code class="inline-code">?</code> you specify a string, |
| the full-qualified class name of a <code class="inline-code">TemplateModel</code> |
| implementation. The result is a method variable that calls the |
| constructor, and returns the new variable.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#-- Creates an user-defined directive be calling the parameterless constructor of the class --> |
| <#assign word_wrapp = "com.acmee.freemarker.WordWrapperDirective"?new()> |
| <#-- Creates an user-defined directive be calling the constructor with one numerical argument --> |
| <#assign word_wrapp_narrow = "com.acmee.freemarker.WordWrapperDirective"?new(40)></pre> </div> |
| |
| |
| <p>For more information about how the constructor parameters are |
| unwrapped and how overloaded constructor is chosen, read: <a href="pgui_misc_beanwrapper.html">Programmer's Guide/Miscellaneous/Bean wrapper</a></p> |
| |
| <p>This built-in can be a security concern because the template |
| author can create arbitrary Java objects and then use them, as far |
| as they implement <code class="inline-code">TemplateModel</code>. Also the |
| template author can trigger static initialization for classes that |
| don't even implement <code class="inline-code">TemplateModel</code>. You can |
| (since 2.3.17) restrict the classes accessible with this built-in |
| using |
| <code class="inline-code">Configuration.setNewBuiltinClassResolver(TemplateClassResolver)</code> |
| or the <code class="inline-code">new_builtin_class_resolver</code> setting. See |
| the Java API docs for more information. If you are allowing |
| not-so-much-trusted users to upload templates then you should |
| definitely look into this topic.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_numToDate">number_to_date, number_to_time, number_to_datetime</h2> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>These are used to convert a number (usually a Java |
| <code class="inline-code">long</code>) to a date, time or date-time, respectively. |
| This does them same as <code class="inline-code">new java.util.Date(long)</code> |
| in Java, that is, the number is interpreted as the milliseconds |
| passed since the epoch. The number can be anything and of any type |
| as far as its value fits into a <code class="inline-code">long</code>. If the |
| number isn't a whole number, it will be rounded to whole with |
| half-up rule.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">${1305575275540?number_to_datetime} |
| ${1305575275540?number_to_date} |
| ${1305575275540?number_to_time}</pre> </div> |
| |
| |
| <p>The output will be something like this (depending on the |
| current locale and time zone):</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">May 16, 2011 3:47:55 PM |
| May 16, 2011 |
| 3:47:55 PM</pre> </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_sequence">sequence</h2> |
| |
| |
| |
| |
| <p>This built-in is used to convert a listable value (one that |
| you can iterate through with the <a href="ref_directive_list.html#ref.directive.list"><code>list</code> |
| directive</a>) to a more capable <a href="dgui_datamodel_types.html#dgui_datamodel_container">sequence</a> value. Sequences |
| support operations like <code class="inline-code">xs[index]</code> and |
| <code class="inline-code">xs?size</code>. Also, the resulting value is listable |
| for multiple times, even if the original value was backed by a |
| <code class="inline-code">java.util.Iterator</code> (which gives error when you |
| try to list it for the 2nd time). This built-in is typically used to |
| work around data-model problems, in case you can't fix the |
| data-model itself. If you can, always fix the data-model instead |
| (give a <code class="inline-code">java.util.List</code> or array to the template |
| instead of a more restricted object, like a |
| non-<code class="inline-code">List</code> <code class="inline-code">java.util.Collection</code>, |
| or a <code class="inline-code">java.util.Iterator</code>).</p> |
| |
| <p>If the value is already a sequence, then this built-in just |
| returns that as is. If the value is not something that the <a href="ref_directive_list.html#ref.directive.list"><code>list</code> |
| directive</a> could list, then template processing will be |
| aborted with error. Otherwise, it usually fetches all the values, |
| and stores them into a sequence. Be careful if you can have a huge |
| number of items, as all of them will be held in memory on the same |
| time. However, in some special cases fetching and/or storing all |
| elements is avoided; see about the <a href="#ref_builtin_sequence_optimizations">optimizations</a> |
| later.</p> |
| |
| <p>You should convert a value with <code class="inline-code">sequence</code> |
| only once. If you need the resulting sequence at multiple places, |
| always assign the result to a variable, because if the value you |
| convert is only listable once, converting it for the second time |
| will result in error or an empty sequence. Also the conversion is |
| somewhat costly for big collections, so it's better to do it only |
| once.</p> |
| |
| <p>Example: Let's say you find that <code class="inline-code">users</code> is |
| only listable once (because it's a |
| <code class="inline-code">java.util.Iterator</code>), but you need to list it for |
| multiple times in the template, and you can't fix the data-model. |
| Then you could do this:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#-- Collect all the users into a sequence: --> |
| <#assign usersSeq = users?sequence> |
| |
| <#list usersSeq as user>...</#list> |
| Again: |
| <#list usersSeq as user>...</#list></pre> </div> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-simplesect" id="ref_builtin_sequence_optimizations">Optimizations</h3> |
| |
| |
| <p>Since version 2.3.29, if the result of the |
| <code class="inline-code">sequence</code> built-in is directly the input of to |
| the <a href="dgui_template_exp.html#dgui_template_exp_var_sequence"><code>[<em>index</em>]</code></a> |
| or <a href="dgui_template_exp.html#dgui_template_exp_seqenceop_slice"><code>[<em>range</em>]</code></a> |
| operator, or of <code class="inline-code">?size</code>, or of |
| <code class="inline-code">?first</code>, or a chain of these operations, then |
| the elements will not be collected into the memory, and only as |
| many elements as strictly necessary will be fetched. For example |
| <code class="inline-code">anIterator?sequence[1]</code> will just fetch the |
| first 2 items (instead of building a sequence that contains all |
| the elements, and then getting the 2nd element from that). Or, if |
| you write <code class="inline-code">anIterator?sequence?size</code>, it will |
| just skip through all elements to count them, but won't store them |
| in memory.</p> |
| |
| <p>The optimizations will only work within the same chain of |
| built-in calls, so for example in <code class="inline-code"><#assign seq = |
| anIterator?sequence>${seq[1]}</code> the |
| <code class="inline-code">?sequence</code> step will collect all the elements |
| into the memory, as <code class="inline-code">anIterator?sequence</code> and |
| <code class="inline-code">seq[1]</code> are separated. On the other hand, the |
| optimizations will work in |
| <code class="inline-code">anIterator?sequence[10..]?size</code>, as both |
| <code class="inline-code">[<em class="code-color">range</em>]</code> and |
| <code class="inline-code">?size</code> supports it, and they are directly |
| chained together.</p> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_with_args">with_args</h2> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since 2.3.30</p> |
| </div> |
| |
| |
| <p>The goal of this built-in is to add parameters |
| <em>dynamically</em> to the call of a directive (like a |
| macro), function or method. Dynamically means that parameters are |
| added based on a hash value (like <code class="inline-code">{'a': 1, 'b': 2, 'c': |
| 3}</code> or a Java <code class="inline-code">Map</code>), or a sequence value |
| (like <code class="inline-code">[1, 2, 3]</code> or a Java |
| <code class="inline-code">List</code>), whose actual content is might only known |
| at the moment when the call happens.</p> |
| |
| <p>For example, we have this macro <code class="inline-code">m</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m a b c>a=${a}, b=${b}, c=${c}</#macro></pre> </div> |
| |
| |
| <p>Normally you call it like:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><@m a=1 b=2 c=3 /></pre> </div> |
| |
| |
| <p>Below call does the same, assuming <code class="inline-code">dynArgs</code> |
| is the hash <code class="inline-code">{'a': 1, 'b': 2, 'c': 3}</code>:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><@m?with_args(dynArgs) /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">a=1, b=1, c=1</pre> </div> |
| |
| |
| <p>Below call also does the same, but combines dynamic arguments |
| from <code class="inline-code">dynArgsAB</code>, assumed to be <code class="inline-code">{'a': 1, |
| 'b': 2}</code>, and argument <code class="inline-code">c</code> specified |
| directly:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><@m?with_args(dynArgsAB) c=3 /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">a=1, b=1, c=1</pre> </div> |
| |
| |
| <p>To understand why this works, you need to realize that macros, |
| custom directives, functions, and methods in FreeMarker are just |
| values, just like numbers, strings, etc. <code class="inline-code"><#macro m |
| <em class="code-color">...</em>></code> just creates a value |
| that's a macro (as opposed to a number, or string, etc.), and then |
| assigns it to variable <code class="inline-code">m</code>. Thus, |
| <code class="inline-code">m</code> in itself is a valid expression, which |
| evaluates to the macro (but it doesn't <em>call</em> the |
| macro). <code class="inline-code"><@m <em class="code-color">...</em> |
| /></code> evaluates the expression <code class="inline-code">m</code> (and |
| you can use arbitrarily complex expressions there too, like |
| <code class="inline-code">m?with_args(<em class="code-color">...</em>)</code>), and |
| then <em>calls</em> the resulting macro. |
| <code class="inline-code">m?with_args(<em class="code-color">dynArgs</em>)</code> |
| returns a macro that's very similar to the original macro (that's |
| stored in <code class="inline-code">m</code>), but its arguments |
| <em>default</em> to the values specified in |
| <code class="inline-code"><em class="code-color">dynArgs</em></code>. So the result |
| of <code class="inline-code">m?with_args({'b': 22, 'c': 33})</code> is similar to |
| a modified macro that was created as <code class="inline-code"><#macro |
| <em class="code-color">unspefiedName</em> a b=22 c=33></code>. |
| With an example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#assign mWithDefs = m?with_args({'b': 22, 'c': 33})> |
| <@myWithDefs a=1 c='overridden'/></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">a=1, b=22, c=overridden</pre> </div> |
| |
| |
| <p>Above we have created a new macro based on the value of |
| <code class="inline-code">m</code>, stored it in variable |
| <code class="inline-code">mWithDefs</code>, and then later we called it with |
| <code class="inline-code"><@myWithDefs <em class="code-color">...</em> |
| /></code>.</p> |
| |
| <p><code class="inline-code">with_args</code> can also be applied on functions |
| (crated with <code class="inline-code"><#function |
| <em class="code-color">...</em>></code>) and Java methods |
| (usually get from the data-model, like |
| <code class="inline-code">myObject.myMethod</code>). But because functions and |
| methods can only be called with positional arguments (like |
| <code class="inline-code">f(1, 2, 3)</code>, and <em>not</em> as |
| <code class="inline-code">f(a=1, b=2, c=3)</code>), the argument to |
| <code class="inline-code">with_args</code> must be a sequence instead of a hash. |
| Other than that, the same tricks work as with macros:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#function f(a, b, c)><#return "a=${a}, b=${b}, c=${c}"></#function> |
| <#assign dynArgs=[1, 2, 3]> |
| |
| ${f(1, 2, 3)} |
| Same as: |
| ${f?with_args(dynArgs)()} |
| or as: |
| ${f?with_args([1, 2])(3)} |
| or as: |
| ${f?with_args([1])(2, 3)} |
| |
| <#assign fWithOneAsFirstArg = f?with_args([1])> |
| ${fWithOneAsFirstArg(2, 3)} <#-- same as f(1, 2, 3) --></pre> </div> |
| |
| |
| <p>Note the double application of |
| <code class="inline-code">(<em class="code-color">...</em>)</code> above, like in |
| <code class="inline-code">f?with_args(<em class="code-color">dynArgs</em>)()</code>. |
| That's because |
| <code class="inline-code">f?with_args(<em class="code-color">dynArgs</em>)</code> |
| just returns a new function (which is just a value), but doesn't |
| call it. So if you want to call that new function immediately (as |
| opposed to assigning it to a variable for example), you need the |
| second <code class="inline-code">()</code>.</p> |
| |
| <p>Because macro calls support both named and positional |
| arguments, the <code class="inline-code">with_args</code> argument can be a |
| sequence for macros as well (though using a hash is usually a better |
| practice):</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m a b c>a=${a}, b=${b}, c=${c}</#macro> |
| |
| <#-- Called with named parameters: --> |
| <@m a=1 b=2 c=3 /> |
| Same as: |
| <#-- Called with positional parameters: --> |
| <@m 1 2 3 /> |
| Same as: |
| <@m?with_args([1, 2, 3]) /> |
| Same as: |
| <#-- Sequence with_args with positional c parameter: --> |
| <@m?with_args([1, 2]) 3 /> |
| Same as: |
| <#-- Sequence with_args with named c parameter: --> |
| <@m?with_args([1, 2]) c=3 /></pre> </div> |
| |
| |
| <p>To summarize, depending on the type of the value |
| <code class="inline-code">with_args</code> is applied on, the type of argument to |
| <code class="inline-code">with_args</code> can be:</p> |
| |
| <ul> |
| <li> |
| <p>Function or method: sequence. Note that WRONG |
| <code class="inline-code">f?with_args(1, 2)</code> is WRONG, the correct form |
| is <code class="inline-code">f?with_args([1, 2])</code>.</p> |
| </li> |
| |
| <li> |
| <p>Macro: hash or sequence</p> |
| </li> |
| |
| <li> |
| <p>Directive (user defined): hash</p> |
| </li> |
| </ul> |
| |
| <p>The return type of <code class="inline-code">with_args</code> is the same as |
| the type of value it was applied on, like if it's applied on a |
| method (like <code class="inline-code">myObj.myMethod?with_args(dynArgs)</code>), |
| then it returns a method.</p> |
| |
| <p>Note that it's not possible to apply |
| <code class="inline-code">with_args</code> on built-in directives, like |
| <code class="inline-code"><#if <em class="code-color">...</em>></code>, |
| <code class="inline-code"><#list <em class="code-color">...</em>></code>, |
| etc., because they aren't available as values.</p> |
| |
| <p>This built-in is often used together with the <a href="ref_specvar.html#specvar.args"><code>.args</code> special |
| variable</a>. For example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m1 a b c> |
| m1 does things with ${a}, ${b}, ${c} |
| </#macro> |
| |
| <#macro m2 a b c> |
| m2 does things with ${a}, ${b}, ${c} |
| Delegate to m1: |
| <@m1?with_args(.args) /> |
| </#macro> |
| |
| <@m2 a=1 b=2 c=3 /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body"> m2 does things with 1, 2, 3 |
| Delegate to m1: |
| m1 does things with 1, 2, 3</pre> </div> |
| |
| |
| <p>FreeMarker syntax allows using the name before the |
| <code class="inline-code">?with_args(<em class="code-color">...</em>)</code> in the |
| end-tag, just as if the |
| <code class="inline-code">?with_args(<em class="code-color">...</em>)</code> wasn't |
| there:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><@myMacro?with_args({'a': 1})>...</<strong>@myMacro</strong>></pre> </div> |
| |
| |
| <p>Note that as far as the order of arguments is concerned, |
| arguments coming from |
| <code class="inline-code">with_args(<em class="code-color">...</em>)</code> are |
| added before the arguments specified in the call to the returned |
| directive/function/method. In some use cases it's more desirable to |
| add them at the end instead, in which case use the <a href="#ref_builtin_with_args_last"><code>with_args_last</code> |
| built-in</a>.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="ref_builtin_with_args_last">with_args_last</h2> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since 2.3.30</p> |
| </div> |
| |
| |
| <p>Same as <a href="#ref_builtin_with_args"><code>with_args</code></a>, |
| but if the order of the arguments in resulting final argument list |
| may differs (but not the values in it). This only matters if you |
| pass parameters by position (typically, when calling functions or |
| methods), or when there's catch-all argument.</p> |
| |
| <p>A typical example with positional arguments is when you want |
| to add the dynamic argument to the end of the parameter list:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#function f a b c d> |
| <#return "a=${a}, b=${b}, c=${c}, d=${d}"> |
| </#function> |
| |
| <#assign dynamicArgs=[3, 4]> |
| |
| with_args: |
| ${f?with_args(dynamicArgs)(1, 2)} |
| |
| with_args_last: |
| ${f?with_args_last(dynamicArgs)(1, 2)}</pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">with_args: |
| a=3, b=4, c=1, d=2 |
| |
| with_args_last: |
| a=1, b=2, c=3, d=4</pre> </div> |
| |
| |
| <p>In the case of name arguments, while the primary mean of |
| identifying an argument is the its name, catch-all arguments |
| (<code class="inline-code">others...</code> below) still have an order:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m a b others...> |
| a=${a} |
| b=${b} |
| others: |
| <#list others as k, v> |
| ${k} = ${v} |
| </#list> |
| </#macro> |
| |
| <#assign dynamicArgs={'e': 5, 'f': 6}> |
| |
| with_args: |
| <@m?with_args(dynamicArgs) a=1 b=2 c=3 d=4 /> |
| |
| with_args_last: |
| <@m?with_args_last(dynamicArgs) a=1 b=2 c=3 d=4 /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">with_args: |
| a=1 |
| b=2 |
| others: |
| e = 5 |
| f = 6 |
| c = 3 |
| d = 4 |
| |
| with_args_last: |
| a=1 |
| b=2 |
| others: |
| c = 3 |
| d = 4 |
| e = 5 |
| f = 6</pre> </div> |
| |
| |
| <p>If you specify a named parameter that are not catch-all, so |
| they are declared in the <code class="inline-code">macro</code> tag (as |
| <code class="inline-code">a</code> and <code class="inline-code">b</code> below), then |
| <code class="inline-code">with_args</code> and <code class="inline-code">with_args_last</code> |
| are no different, since the argument order is specified by the macro |
| definition, not the macro call:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m a=0 b=0> |
| <#-- We use .args to demonstrate the ordering of a and b: --> |
| <#list .args as k, v> |
| ${k} = ${v} |
| </#list> |
| </#macro> |
| |
| <#assign dynamicArgs={'b': 1}> |
| |
| with_args: |
| <@m?with_args(dynamicArgs) a=1 /> |
| |
| with_args_last: |
| <@m?with_args_last(dynamicArgs) a=1 /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">with_args: |
| a = 1 |
| b = 1 |
| |
| with_args_last: |
| a = 1 |
| b = 1</pre> </div> |
| |
| |
| <p>If both the macro or directive call, and the |
| <code class="inline-code">with_args_last</code> argument specifies named catch-all |
| argument with the same name (like <code class="inline-code">b</code> below), then |
| the placement of those parameters is decide by the macro/directive |
| call:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body"><#macro m others...> |
| <#list others as k, v> |
| ${k} = ${v} |
| </#list> |
| </#macro> |
| |
| <#assign dynamicArgs={'b': 0, 'd': 4}> |
| |
| with_args: |
| <@m?with_args(dynamicArgs) a=1 b=2 c=3 /> |
| |
| with_args_last: |
| <@m?with_args_last(dynamicArgs) a=1 b=2 c=3 /></pre> </div> |
| |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">with_args: |
| <strong> b = 2 |
| d = 4 |
| </strong> a = 1 |
| c = 3 |
| |
| with_args_last: |
| a = 1 |
| <strong> b = 2 |
| </strong> c = 3 |
| <strong> d = 4</strong></pre> </div> |
| |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_builtins_type_independent.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directives.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
