| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"/> |
| <meta name="Date-Revision-yyyymmdd" content="20140918"/> |
| <meta http-equiv="Content-Language" content="en"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> |
| |
| <title>Freemarker</title> |
| |
| <link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css"> |
| <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet"> |
| <link href="/css/main.css" rel="stylesheet"> |
| <link href="/css/custom.css" rel="stylesheet"> |
| <link href="/css/syntax.css" rel="stylesheet"> |
| |
| <script src="//code.jquery.com/jquery-1.11.0.min.js"></script> |
| <script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script> |
| <script type="text/javascript" src="/js/community.js"></script> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| /* We explicitly disable cookie tracking to avoid privacy issues */ |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="//analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '41']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| </head> |
| <body> |
| |
| <a href="https://github.com/apache/struts" class="github-ribbon"> |
| <img decoding="async" loading="lazy" style="position: absolute; right: 0; border: 0;" width="149" height="149" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_red_aa0000.png?resize=149%2C149" class="attachment-full size-full" alt="Fork me on GitHub" data-recalc-dims="1"> |
| </a> |
| |
| <header> |
| <nav> |
| <div role="navigation" class="navbar navbar-default navbar-fixed-top"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle"> |
| Menu |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a> |
| </div> |
| <div id="struts-menu" class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Home<b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu"> |
| <li><a href="/index.html">Welcome</a></li> |
| <li><a href="/download.cgi">Download</a></li> |
| <li><a href="/releases.html">Releases</a></li> |
| <li><a href="/announce-2024.html">Announcements</a></li> |
| <li><a href="http://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy Policy</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Support<b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu"> |
| <li><a href="/mail.html">User Mailing List</a></li> |
| <li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li> |
| <li><a href="/security.html">Reporting Security Issues</a></li> |
| <li><a href="/commercial-support.html">Commercial Support</a></li> |
| <li class="divider"></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li> |
| <li class="divider"></li> |
| <li><a href="/maven/project-info.html">Maven Project Info</a></li> |
| <li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li> |
| <li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Documentation<b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu"> |
| <li><a href="/birdseye.html">Birds Eye</a></li> |
| <li><a href="/primer.html">Key Technologies</a></li> |
| <li><a href="/kickstart.html">Kickstart FAQ</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li> |
| <li class="divider"></li> |
| <li><a href="/getting-started/">Getting Started</a></li> |
| <li><a href="/security/">Security Guide</a></li> |
| <li><a href="/core-developers/">Core Developers Guide</a></li> |
| <li><a href="/tag-developers/">Tag Developers Guide</a></li> |
| <li><a href="/maven-archetypes/">Maven Archetypes</a></li> |
| <li><a href="/plugins/">Plugins</a></li> |
| <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li> |
| <li><a href="/tag-developers/tag-reference.html">Tag reference</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li> |
| <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Contributing<b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu"> |
| <li><a href="/youatstruts.html">You at Struts</a></li> |
| <li><a href="/helping.html">How to Help FAQ</a></li> |
| <li><a href="/dev-mail.html">Development Lists</a></li> |
| <li class="divider"></li> |
| <li><a href="/submitting-patches.html">Submitting patches</a></li> |
| <li><a href="/builds.html">Source Code and Builds</a></li> |
| <li><a href="/coding-standards.html">Coding standards</a></li> |
| <li><a href="/contributors/">Contributors Guide</a></li> |
| <li class="divider"></li> |
| <li><a href="/release-guidelines.html">Release Guidelines</a></li> |
| <li><a href="/bylaws.html">PMC Charter</a></li> |
| <li><a href="/volunteers.html">Volunteers</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li> |
| <li><a href="/updating-website.html">Updating the website</a></li> |
| </ul> |
| </li> |
| <li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </nav> |
| </header> |
| |
| |
| <article class="container"> |
| <section class="col-md-12"> |
| <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/tag-developers/freemarker.md" title="Edit this page on GitHub">Edit on GitHub</a> |
| |
| <a href="index" title="back to Tag Developers Guide"><< back to Tag Developers Guide</a> |
| |
| <h1 class="no_toc" id="freemarker">FreeMarker</h1> |
| |
| <ul id="markdown-toc"> |
| <li><a href="#getting-started" id="markdown-toc-getting-started">Getting Started</a></li> |
| <li><a href="#servlet--jsp-scoped-objects" id="markdown-toc-servlet--jsp-scoped-objects">Servlet / JSP Scoped Objects</a> <ul> |
| <li><a href="#application-scope-attribute" id="markdown-toc-application-scope-attribute">Application Scope Attribute</a></li> |
| <li><a href="#session-scope-attribute" id="markdown-toc-session-scope-attribute">Session Scope Attribute</a></li> |
| <li><a href="#request-scope-attribute" id="markdown-toc-request-scope-attribute">Request Scope Attribute</a></li> |
| <li><a href="#request-parameter" id="markdown-toc-request-parameter">Request Parameter</a></li> |
| <li><a href="#context-parameter" id="markdown-toc-context-parameter">Context parameter</a></li> |
| </ul> |
| </li> |
| <li><a href="#template-loading" id="markdown-toc-template-loading">Template Loading</a></li> |
| <li><a href="#variable-resolution" id="markdown-toc-variable-resolution">Variable Resolution</a></li> |
| <li><a href="#tag-support" id="markdown-toc-tag-support">Tag Support</a></li> |
| <li><a href="#tips-and-tricks" id="markdown-toc-tips-and-tricks">Tips and Tricks</a> <ul> |
| <li><a href="#type-conversion-and-locales" id="markdown-toc-type-conversion-and-locales">Type Conversion and Locales</a></li> |
| <li><a href="#extending" id="markdown-toc-extending">Extending</a></li> |
| <li><a href="#objectwrapper-settings" id="markdown-toc-objectwrapper-settings">ObjectWrapper Settings</a></li> |
| <li><a href="#syntax-notes" id="markdown-toc-syntax-notes">Syntax Notes</a></li> |
| <li><a href="#cache" id="markdown-toc-cache">Cache</a></li> |
| <li><a href="#incompatible-improvements" id="markdown-toc-incompatible-improvements">Incompatible Improvements</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>FreeMarker is a Java-based template engine that is a great alternative to <a href="jsp">JSP</a>. FreeMarker is ideal for situations |
| where your action results can possibly be loaded from outside a Servlet container. For example, if you wished to support |
| plugins in your application, you might wish to use FreeMarker so that the plugins could provide the entire action class |
| and view in a single jar that is loaded from the classloader.</p> |
| |
| <p>For more information on FreeMarker itself, please visit the <a href="http://freemarker.org/">FreeMarker website</a>.</p> |
| |
| <blockquote> |
| <p>The framework utilizes FreeMarker because the engine includes strong error reporting, built-in internationalization |
| and powerful macro libraries.</p> |
| </blockquote> |
| |
| <blockquote> |
| <p>Support is also included for <a href="velocity">Velocity</a> templates. For a comparison of Velocity vs FreeMarker |
| see <a href="http://freemarker.org/fmVsVel">here</a>.</p> |
| </blockquote> |
| |
| <h2 id="getting-started">Getting Started</h2> |
| |
| <p>Getting started with FreeMarker is as simple as ensuring all the dependencies are included in your project’s classpath. |
| Typically, the only dependency is <code class="language-plaintext highlighter-rouge">freemarker.jar</code>. Other than that, <code class="language-plaintext highlighter-rouge">struts-default.xml</code> already configures |
| the <code class="language-plaintext highlighter-rouge">FreeMarker Result</code> needed to process your application’s templates.</p> |
| |
| <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><action</span> <span class="na">name=</span><span class="s">"test"</span> <span class="na">class=</span><span class="s">"com.acme.TestAction"</span><span class="nt">></span> |
| <span class="nt"><result</span> <span class="na">name=</span><span class="s">"success"</span> <span class="na">type=</span><span class="s">"freemarker"</span><span class="nt">></span>test-success.ftl<span class="nt"></result></span> |
| <span class="nt"></action></span> |
| </code></pre></div></div> |
| |
| <p>Then in <code class="language-plaintext highlighter-rouge">test-success.ftl</code>:</p> |
| |
| <div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><html></span> |
| <span class="nt"><head></span> |
| <span class="nt"><title></span>Hello<span class="nt"></title></span> |
| <span class="nt"></head></span> |
| <span class="nt"><body></span> |
| |
| Hello, ${name} |
| |
| <span class="nt"></body></span> |
| <span class="nt"></html></span> |
| </code></pre></div></div> |
| |
| <p>Where <code class="language-plaintext highlighter-rouge">name</code> is a property on your action. That’s it! Read the rest of this document for details on how templates |
| are loaded, variables are resolved, and tags can be used.</p> |
| |
| <h2 id="servlet--jsp-scoped-objects">Servlet / JSP Scoped Objects</h2> |
| |
| <p>The following are ways to obtained Application scope attributes, Session scope attributes, Request scope attributes, |
| Request parameters, and framework Context scope parameters.</p> |
| |
| <h3 id="application-scope-attribute">Application Scope Attribute</h3> |
| |
| <p>Assuming there’s an attribute with name <code class="language-plaintext highlighter-rouge">myApplicationAttribute</code> in the Application scope.</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><#</span><span class="no">if</span><span class="w"> </span>Application.myApplicationAttribute?exists><span class="w"> |
| </span>$<span class="p">{</span><span class="nb">A</span><span class="no">pplication</span><span class="na">.myApplicationAttribute</span><span class="p">}</span><span class="w"> |
| </span><span class="err"></#</span><span class="no">if</span><span class="err">></span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>or</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.property</span><span class="w"> </span>value="%<span class="p">{</span><span class="err">#</span><span class="no">application</span><span class="na">.myApplicationAttribute</span><span class="p">}</span>" /><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="session-scope-attribute">Session Scope Attribute</h3> |
| |
| <p>Assuming there’s an attribute with name <code class="language-plaintext highlighter-rouge">mySessionAttribute</code> in the Session scope.</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><#</span><span class="no">if</span><span class="w"> </span>Session.mySessionAttribute?exists><span class="w"> |
| </span>$<span class="p">{</span><span class="nb">S</span><span class="no">ession</span><span class="na">.mySessionAttribute</span><span class="p">}</span><span class="w"> |
| </span><span class="err"></#</span><span class="no">if</span><span class="err">></span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>or</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.property</span><span class="w"> </span>value="%<span class="p">{</span><span class="err">#</span><span class="no">session</span><span class="na">.mySessionAttribute</span><span class="p">}</span>" /><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="request-scope-attribute">Request Scope Attribute</h3> |
| |
| <p>Assuming there’s an attribute with name <code class="language-plaintext highlighter-rouge">myRequestAttribute</code> in the Request scope.</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><#</span><span class="no">if</span><span class="w"> </span>Request.myRequestAttribute?exists><span class="w"> |
| </span>$<span class="p">{</span><span class="nb">R</span><span class="no">equest</span><span class="na">.myRequestAttribute</span><span class="p">}</span><span class="w"> |
| </span><span class="err"></#</span><span class="no">if</span><span class="err">></span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>or</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.property</span><span class="w"> </span>value="%<span class="p">{</span><span class="err">#</span><span class="no">request</span><span class="na">.myRequestAttribute</span><span class="p">}</span>" /><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="request-parameter">Request Parameter</h3> |
| |
| <p>Assuming there’s a request parameter <code class="language-plaintext highlighter-rouge">myParameter</code> (eg. [http://host/myApp/myAction.action?myParameter=one]).</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><#</span><span class="no">if</span><span class="w"> </span>Parameters.myParameter?exists><span class="w"> |
| </span>$<span class="p">{</span><span class="nb">P</span><span class="no">arameters</span><span class="na">.myParameter</span><span class="p">}</span><span class="w"> |
| </span><span class="err"></#</span><span class="no">if</span><span class="err">></span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>or</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.property</span><span class="w"> </span>value="%<span class="p">{</span><span class="err">#</span><span class="no">parameters</span><span class="na">.myParameter</span><span class="p">}</span>" /><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h3 id="context-parameter">Context parameter</h3> |
| |
| <p>Assuming there’s a parameter with the name <code class="language-plaintext highlighter-rouge">myContextParam</code> in framework context.</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err">${</span><span class="no">stack</span><span class="na">.findValue</span><span class="err">('#</span><span class="no">myContextParam</span><span class="err">')}</span><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>or</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.property</span><span class="w"> </span>value="%<span class="p">{</span><span class="err">#</span><span class="no">myContextParam</span><span class="p">}</span>" /><span class="w"> |
| </span></code></pre></div></div> |
| |
| <h2 id="template-loading">Template Loading</h2> |
| |
| <p>The framework looks for FreeMarker templates in two locations (in this order):</p> |
| |
| <ol> |
| <li>Web application</li> |
| <li>Class path</li> |
| </ol> |
| |
| <p>This ordering makes it ideal for providing templates inside a fully-built jar, but allowing for overrides of those |
| templates to be defined in your web application. In fact, this is how you can override the default UI tags |
| and <a href="form-tags">Form Tags</a> included with the framework.</p> |
| |
| <p>In addition, you can specify a location (directory on your file system) through the <code class="language-plaintext highlighter-rouge">templatePath</code> or <code class="language-plaintext highlighter-rouge">TemplatePath</code> |
| context variable (in the <code class="language-plaintext highlighter-rouge">web.xml</code>). If a variable is specified, the content of the directory it points to will be |
| searched first.</p> |
| |
| <blockquote> |
| <p>This variable is currently NOT relative to the root of your application.</p> |
| </blockquote> |
| |
| <h2 id="variable-resolution">Variable Resolution</h2> |
| |
| <p>When using FreeMarker with the framework, variables are looked up in several different places, in this order:</p> |
| |
| <ol> |
| <li>Built-in variables</li> |
| <li>Value stack</li> |
| <li>Action context</li> |
| <li>Request scope</li> |
| <li>Session scope</li> |
| <li>Application scope</li> |
| </ol> |
| |
| <p>Note that the action context is looked up after the value stack. This means that you can reference the variable without |
| the typical preceding hash marker (<code class="language-plaintext highlighter-rouge">#</code>) like you would have to when using the JSP <code class="language-plaintext highlighter-rouge">s:property</code> tag. This is a nice |
| convenience, though be careful because there is a small chance it could trip you up.</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><@</span><span class="no">s</span><span class="na">.url</span><span class="w"> </span>id="url" value="http://www.yahoo.com"/><span class="w"> |
| </span><span class="no">Click</span><span class="w"> </span><a href="$<span class="p">{</span><span class="no">url</span><span class="p">}</span>">here</a>!<span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>The built-in variables that Struts-FreeMarker integration provides are:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>stack</td> |
| <td>The value stack itself, useful for calls like <code class="language-plaintext highlighter-rouge">${stack.findString('ognl expr')}</code></td> |
| </tr> |
| <tr> |
| <td>action</td> |
| <td>The action most recently executed</td> |
| </tr> |
| <tr> |
| <td>response</td> |
| <td>The HttpServletResponse</td> |
| </tr> |
| <tr> |
| <td>res</td> |
| <td>Same as response</td> |
| </tr> |
| <tr> |
| <td>request</td> |
| <td>The HttpServletRequest</td> |
| </tr> |
| <tr> |
| <td>req</td> |
| <td>Same as request</td> |
| </tr> |
| <tr> |
| <td>session</td> |
| <td>The HttpSession</td> |
| </tr> |
| <tr> |
| <td>application</td> |
| <td>The ServletContext</td> |
| </tr> |
| <tr> |
| <td>base</td> |
| <td>The request’s context path</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h2 id="tag-support">Tag Support</h2> |
| |
| <p>FreeMarker includes complete tag support. See the <a href="freemarker-tags">FreeMarker Tags</a> documentation for information |
| on how to use the generic <a href="struts-tags">Struts Tags</a> provided by Struts. In addition to this, you can use any JSP tag, |
| like so:</p> |
| |
| <div class="language-ftl highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err"><#</span><span class="no">assign</span><span class="w"> </span>mytag=JspTaglibs["/WEB-INF/mytag.tld"]><span class="w"> |
| </span><span class="err"><@</span><span class="no">mytag</span><span class="na">.tagx</span><span class="w"> </span>attribute1="some $<span class="p">{</span><span class="no">value</span><span class="p">}</span>"/><span class="w"> |
| </span></code></pre></div></div> |
| |
| <p>Where <strong>mytag.tld</strong> is the JSP Tag Library Definition file for your tag library. Note: in order to use this support |
| in FreeMarker, you must enable the <code class="language-plaintext highlighter-rouge">JSPSupportServlet</code> in <code class="language-plaintext highlighter-rouge">web.xml</code>:</p> |
| |
| <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><servlet></span> |
| <span class="nt"><servlet-name></span>JspSupportServlet<span class="nt"></servlet-name></span> |
| <span class="nt"><servlet-class></span>org.apache.struts2.views.JspSupportServlet<span class="nt"></servlet-class></span> |
| <span class="nt"><load-on-startup></span>1<span class="nt"></load-on-startup></span> |
| <span class="nt"></servlet></span> |
| </code></pre></div></div> |
| |
| <h2 id="tips-and-tricks">Tips and Tricks</h2> |
| |
| <p>There are some advanced features that may be useful when building Struts applications with FreeMarker.</p> |
| |
| <h3 id="type-conversion-and-locales">Type Conversion and Locales</h3> |
| |
| <p>FreeMarker has built in support for formatting dates and numbers. The formatting rules are based on the locale associated |
| with the action request, which is by default set in <code class="language-plaintext highlighter-rouge">struts.properties</code> but can be over-ridden using the <code class="language-plaintext highlighter-rouge">I18n Interceptor</code>. |
| This is normally perfect for your needs, but it is important to remember that these formatting rules are handled |
| by FreeMarker and not by the framework’s <em>Type Conversion</em> support.</p> |
| |
| <p>If you want the framework to handle the formatting according to the <em>Type Conversion</em> you have specified, you shouldn’t |
| use the normal <code class="language-plaintext highlighter-rouge">${...}</code> syntax. Instead, you should use the <a href="property-tag">property</a> tag. The difference is that |
| the <code class="language-plaintext highlighter-rouge">property</code> tag is specifically designed to take an <a href="ognl">OGNL</a> expression, evaluate it, and then convert it |
| to a String using any <em>Type Conversion</em> rules you have specified. The normal <code class="language-plaintext highlighter-rouge">${...}</code> syntax will use a FreeMarker |
| expression language, evaluate it, and then convert it to a String using the built in formatting rules.</p> |
| |
| <blockquote> |
| <p>The difference in how type conversion is handled under Freemarker is subtle but important to understand.</p> |
| </blockquote> |
| |
| <h3 id="extending">Extending</h3> |
| |
| <p>Sometimes you may with to extend the framework’s FreeMarker support. For example, you might want to extend the Struts |
| tags that come bundled with the framework.</p> |
| |
| <p>To extend the Freemarker support, develop a class that extends <code class="language-plaintext highlighter-rouge">org.apache.struts2.views.freemarker.FreemarkerManager</code>, |
| overriding methods as needed, and plugin the class through the <code class="language-plaintext highlighter-rouge">struts.xml</code>:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code><constant name="struts.freemarker.manager.classname" value="com.yourcompany.YourFreeMarkerManager" /> |
| </code></pre></div></div> |
| |
| <h3 id="objectwrapper-settings">ObjectWrapper Settings</h3> |
| |
| <p>Once you get familiar with FreeMarker, you will find certain <em>subtleties</em> with it that may become frustrating. |
| The most common thing you’ll likely run in to is the <code class="language-plaintext highlighter-rouge">BeansWrapper</code> provided by FreeMarker. If you don’t know what this |
| is, don’t worry. However, if you do, know this:</p> |
| |
| <p>The <code class="language-plaintext highlighter-rouge">StrutsBeanWrapper</code> extends the default FreeMarker <code class="language-plaintext highlighter-rouge">BeansWrapper</code> and provides almost no change in functionality, |
| <strong>except</strong> for how it handles maps. Normally, FreeMarker has two modes of operation: either support for friendly |
| map built-ins (<code class="language-plaintext highlighter-rouge">?keys</code>, <code class="language-plaintext highlighter-rouge">?values</code>, etc) but only support for String keys; OR no special built-in support (ie: <code class="language-plaintext highlighter-rouge">?keys</code> |
| returns the methods on the map instead of the keys) but support for String and non-String keys alike. Struts |
| provides an alternative implementation that gives us the best of both worlds.</p> |
| |
| <p>It is possible that this special behavior may be confusing or can cause problems. Therefore, you can set the |
| <code class="language-plaintext highlighter-rouge">struts.freemarker.wrapper.altMap</code> property in <code class="language-plaintext highlighter-rouge">struts.xml</code> to false, allowing the normal BeansWrapper |
| logic to take place instead.</p> |
| |
| <h3 id="syntax-notes">Syntax Notes</h3> |
| |
| <p>As of FreeMarker 2.3.4, an alternative syntax is supported. This alternative syntax is great if you find that your IDE |
| (especially IntelliJ IDEA) makes it difficult to work with the default syntax. You can read more about this syntax |
| <a href="http://freemarker.org/docs/dgui_misc_alternativesyntax">here</a>.</p> |
| |
| <h3 id="cache">Cache</h3> |
| |
| <p>You can enable FreeMarker cache mechanism by specifying below options in <code class="language-plaintext highlighter-rouge">struts.xml</code>:</p> |
| |
| <ul> |
| <li><code class="language-plaintext highlighter-rouge"><constant name="struts.freemarker.mru.max.strong.size" value="250" /></code> - this option will be used |
| by <a href="http://freemarker.org/docs/api/freemarker/cache/MruCacheStorage">freemarker.cache.MruCacheStorage</a></li> |
| <li><code class="language-plaintext highlighter-rouge"><constant name="struts.freemarker.templatesCache.updateDelay" value="1800" /></code> - default update cache interval (5 seconds) |
| -<code class="language-plaintext highlighter-rouge"><constant name="struts.freemarker.templatesCache" value="true" /></code> - *<strong>DEPRECATED</strong>* this option will use a internal |
| ConcurrentHashMap in FreemarkerTemplateEngine but not freemarker native cache</li> |
| </ul> |
| |
| <p>Setting <code class="language-plaintext highlighter-rouge">devMode</code> to <code class="language-plaintext highlighter-rouge">true</code> will disable cache and updateDelay immediately, but you can explicit specify these constants |
| to enable cache even in <code class="language-plaintext highlighter-rouge">devMode</code>, see <a href="../core-developers/development-mode">devMode</a>.</p> |
| |
| <h3 id="incompatible-improvements">Incompatible Improvements</h3> |
| |
| <p>By default Struts is using FreeMarker in way to be backward compatible as much as possible but if you need to enable new |
| features you can do it via <code class="language-plaintext highlighter-rouge">freemarker.properties</code> by defining |
| <a href="http://freemarker.org/docs/pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set">incompatible improvements</a> |
| settings, ie.:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>incompatible_improvements=2.3.22 |
| </code></pre></div></div> |
| |
| <p>You can also pass this setting via <code class="language-plaintext highlighter-rouge">ServletContext</code> setting <code class="language-plaintext highlighter-rouge"><init-param/></code> (since Struts 2.5.13):</p> |
| |
| <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><init-param></span> |
| <span class="nt"><param-name></span>freemarker.incompatible_improvements<span class="nt"></param-name></span> |
| <span class="nt"><param-value></span>2.3.22<span class="nt"></param-value></span> |
| <span class="nt"></init-param></span> |
| </code></pre></div></div> |
| |
| <p>This can impact your freemarker powered pages and Struts tags as well, so please careful test this change.</p> |
| |
| </section> |
| </article> |
| |
| |
| <footer class="container"> |
| <div class="col-md-12"> |
| Copyright © 2000-2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are |
| trademarks of The Apache Software Foundation. All Rights Reserved. |
| </div> |
| <div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div> |
| </footer> |
| |
| <script>!function (d, s, id) { |
| var js, fjs = d.getElementsByTagName(s)[0]; |
| if (!d.getElementById(id)) { |
| js = d.createElement(s); |
| js.id = id; |
| js.src = "//platform.twitter.com/widgets.js"; |
| fjs.parentNode.insertBefore(js, fjs); |
| } |
| }(document, "script", "twitter-wjs");</script> |
| <script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script> |
| |
| <div id="fb-root"></div> |
| |
| <script>(function (d, s, id) { |
| var js, fjs = d.getElementsByTagName(s)[0]; |
| if (d.getElementById(id)) return; |
| js = d.createElement(s); |
| js.id = id; |
| js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1"; |
| fjs.parentNode.insertBefore(js, fjs); |
| }(document, 'script', 'facebook-jssdk'));</script> |
| |
| |
| </body> |
| </html> |
