| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-book"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>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="FreeMarker Manual"> |
| <meta property="og:title" content="FreeMarker Manual"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="http://example.com/index.html"> |
| <link rel="canonical" href="http://example.com/index.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338515428"> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="http://example.com/"> |
| <meta itemprop="name" content="FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> |
| <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo"> |
| </a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="#alphaidx">Index</a></li><li><a href="#gloss">Glossary</a></li><li><a href="#ref">Reference</a></li><li><a href="#app_faq">FAQ</a></li><li><a href="#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</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 = [];</script> |
| <script src="toc.js?1594338515428"></script> |
| <script src="docgen-resources/main.min.js?1594338515428"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="title-wrapper"> |
| <h1 class="content-header header-book" id="autoid_1" itemprop="headline">FreeMarker Manual <span class="subtitle">For FreeMarker 2.3.16</span> |
| </h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#preface" data-menu-target="preface">Preface</a><ul><li><a class="page-menu-link" href="#autoid_2" data-menu-target="autoid_2">What is FreeMarker?</a></li><li><a class="page-menu-link" href="#autoid_3" data-menu-target="autoid_3">What should I read?</a></li><li><a class="page-menu-link" href="#autoid_4" data-menu-target="autoid_4">Document conventions</a></li><li><a class="page-menu-link" href="#autoid_5" data-menu-target="autoid_5">Contact</a></li><li><a class="page-menu-link" href="#autoid_6" data-menu-target="autoid_6">About this document</a></li></ul></li><li><a class="page-menu-link" href="#dgui" data-menu-target="dgui">Template Author's Guide</a><ul><li><a class="page-menu-link" href="#dgui_quickstart" data-menu-target="dgui_quickstart">Getting Started</a><ul><li><a class="page-menu-link" href="#dgui_quickstart_basics" data-menu-target="dgui_quickstart_basics">Template + data-model = output</a></li><li><a class="page-menu-link" href="#dgui_quickstart_datamodel" data-menu-target="dgui_quickstart_datamodel">The data-model at a glance</a></li><li><a class="page-menu-link" href="#dgui_quickstart_template" data-menu-target="dgui_quickstart_template">The template at a glance</a><ul><li><a class="page-menu-link" href="#autoid_7" data-menu-target="autoid_7">Examples of directives</a><ul><li><a class="page-menu-link" href="#autoid_8" data-menu-target="autoid_8">The if directive</a></li><li><a class="page-menu-link" href="#autoid_9" data-menu-target="autoid_9">The list directive</a></li><li><a class="page-menu-link" href="#autoid_10" data-menu-target="autoid_10">The include directive</a></li></ul></li><li><a class="page-menu-link" href="#autoid_11" data-menu-target="autoid_11">Using directives together</a></li><li><a class="page-menu-link" href="#autoid_12" data-menu-target="autoid_12">Dealing with missing variables</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#dgui_datamodel" data-menu-target="dgui_datamodel">Values, Types</a><ul><li><a class="page-menu-link" href="#dgui_datamodel_basics" data-menu-target="dgui_datamodel_basics">Basics</a><ul><li><a class="page-menu-link" href="#topic.value" data-menu-target="topic.value">What is a value?</a></li><li><a class="page-menu-link" href="#autoid_13" data-menu-target="autoid_13">What is type?</a></li><li><a class="page-menu-link" href="#autoid_14" data-menu-target="autoid_14">The data-model is a hash</a></li></ul></li><li><a class="page-menu-link" href="#dgui_datamodel_types" data-menu-target="dgui_datamodel_types">The types</a><ul><li><a class="page-menu-link" href="#dgui_datamodel_scalar" data-menu-target="dgui_datamodel_scalar">Scalars</a></li><li><a class="page-menu-link" href="#dgui_datamodel_container" data-menu-target="dgui_datamodel_container">Containers</a></li><li><a class="page-menu-link" href="#autoid_15" data-menu-target="autoid_15">Subroutines</a><ul><li><a class="page-menu-link" href="#dgui_datamodel_method" data-menu-target="dgui_datamodel_method">Methods and functions</a></li><li><a class="page-menu-link" href="#dgui_datamodel_userdefdir" data-menu-target="dgui_datamodel_userdefdir">User-defined directives</a></li><li><a class="page-menu-link" href="#autoid_16" data-menu-target="autoid_16">Function/method versus user-defined directive</a></li></ul></li><li><a class="page-menu-link" href="#autoid_17" data-menu-target="autoid_17">Miscellaneous</a><ul><li><a class="page-menu-link" href="#dgui_datamodel_node" data-menu-target="dgui_datamodel_node">Nodes</a></li></ul></li></ul></li></ul></li><li><a class="page-menu-link" href="#dgui_template" data-menu-target="dgui_template">The Template</a><ul><li><a class="page-menu-link" href="#dgui_template_overallstructure" data-menu-target="dgui_template_overallstructure">Overall structure</a></li><li><a class="page-menu-link" href="#dgui_template_directives" data-menu-target="dgui_template_directives">Directives</a></li><li><a class="page-menu-link" href="#dgui_template_exp" data-menu-target="dgui_template_exp">Expressions</a><ul><li><a class="page-menu-link" href="#exp_cheatsheet" data-menu-target="exp_cheatsheet">Quick overview (cheat sheet)</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct" data-menu-target="dgui_template_exp_direct">Specify values directly</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_direct_string" data-menu-target="dgui_template_exp_direct_string">Strings</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_number" data-menu-target="dgui_template_exp_direct_number">Numbers</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_boolean" data-menu-target="dgui_template_exp_direct_boolean">Booleans</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_seuqence" data-menu-target="dgui_template_exp_direct_seuqence">Sequences</a></li><li><a class="page-menu-link" href="#dgui_template_exp_direct_hash" data-menu-target="dgui_template_exp_direct_hash">Hashes</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_var" data-menu-target="dgui_template_exp_var">Retrieving variables</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_var_toplevel" data-menu-target="dgui_template_exp_var_toplevel">Top-level variables</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_hash" data-menu-target="dgui_template_exp_var_hash">Retrieving data from a hash</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_sequence" data-menu-target="dgui_template_exp_var_sequence">Retrieving data from a sequence</a></li><li><a class="page-menu-link" href="#dgui_template_exp_var_special" data-menu-target="dgui_template_exp_var_special">Special variables</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_stringop" data-menu-target="dgui_template_exp_stringop">String operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_stringop_interpolation" data-menu-target="dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a></li><li><a class="page-menu-link" href="#dgui_template_exp_get_character" data-menu-target="dgui_template_exp_get_character">Getting a character</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_sequenceop" data-menu-target="dgui_template_exp_sequenceop">Sequence operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_sequenceop_cat" data-menu-target="dgui_template_exp_sequenceop_cat">Concatenation</a></li><li><a class="page-menu-link" href="#dgui_template_exp_seqenceop_slice" data-menu-target="dgui_template_exp_seqenceop_slice">Sequence slice</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_hashop" data-menu-target="dgui_template_exp_hashop">Hash operations</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_hashop_cat" data-menu-target="dgui_template_exp_hashop_cat">Concatenation</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_arit" data-menu-target="dgui_template_exp_arit">Arithmetical calculations</a></li><li><a class="page-menu-link" href="#dgui_template_exp_comparison" data-menu-target="dgui_template_exp_comparison">Comparison</a></li><li><a class="page-menu-link" href="#dgui_template_exp_logicalop" data-menu-target="dgui_template_exp_logicalop">Logical operations</a></li><li><a class="page-menu-link" href="#dgui_template_exp_builtin" data-menu-target="dgui_template_exp_builtin">Built-ins</a></li><li><a class="page-menu-link" href="#dgui_template_exp_methodcall" data-menu-target="dgui_template_exp_methodcall">Method call</a></li><li><a class="page-menu-link" href="#dgui_template_exp_missing" data-menu-target="dgui_template_exp_missing">Handling missing values</a><ul><li><a class="page-menu-link" href="#dgui_template_exp_missing_default" data-menu-target="dgui_template_exp_missing_default">Default value operator</a></li><li><a class="page-menu-link" href="#dgui_template_exp_missing_test" data-menu-target="dgui_template_exp_missing_test">Missing value test operator</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_exp_parentheses" data-menu-target="dgui_template_exp_parentheses">Parentheses</a></li><li><a class="page-menu-link" href="#dgui_template_exp_whitespace" data-menu-target="dgui_template_exp_whitespace">White-space in expressions</a></li><li><a class="page-menu-link" href="#dgui_template_exp_precedence" data-menu-target="dgui_template_exp_precedence">Operator precedence</a></li></ul></li><li><a class="page-menu-link" href="#dgui_template_valueinsertion" data-menu-target="dgui_template_valueinsertion">Interpolations</a></li></ul></li><li><a class="page-menu-link" href="#dgui_misc" data-menu-target="dgui_misc">Miscellaneous</a><ul><li><a class="page-menu-link" href="#dgui_misc_userdefdir" data-menu-target="dgui_misc_userdefdir">Defining your own directives</a><ul><li><a class="page-menu-link" href="#autoid_21" data-menu-target="autoid_21">Basics</a></li><li><a class="page-menu-link" href="#autoid_22" data-menu-target="autoid_22">Parameters</a></li><li><a class="page-menu-link" href="#autoid_23" data-menu-target="autoid_23">Nested content</a></li><li><a class="page-menu-link" href="#dgui_misc_userdefdir_loopvar" data-menu-target="dgui_misc_userdefdir_loopvar">Macros with loop variables</a></li><li><a class="page-menu-link" href="#autoid_24" data-menu-target="autoid_24">More about user-defined directives and macros</a></li></ul></li><li><a class="page-menu-link" href="#dgui_misc_var" data-menu-target="dgui_misc_var">Defining variables in the template</a></li><li><a class="page-menu-link" href="#dgui_misc_namespace" data-menu-target="dgui_misc_namespace">Namespaces</a><ul><li><a class="page-menu-link" href="#autoid_25" data-menu-target="autoid_25">Creating a library</a></li><li><a class="page-menu-link" href="#autoid_26" data-menu-target="autoid_26">Writing the variables of imported namespaces</a></li><li><a class="page-menu-link" href="#autoid_27" data-menu-target="autoid_27">Namespaces and data-model</a></li><li><a class="page-menu-link" href="#autoid_28" data-menu-target="autoid_28">The life-cycle of namespaces</a></li><li><a class="page-menu-link" href="#autoid_29" data-menu-target="autoid_29">Writing libraries for other people</a></li></ul></li><li><a class="page-menu-link" href="#dgui_misc_whitespace" data-menu-target="dgui_misc_whitespace">White-space handling</a><ul><li><a class="page-menu-link" href="#dgui_misc_whitespace_stripping" data-menu-target="dgui_misc_whitespace_stripping">White-space stripping</a></li><li><a class="page-menu-link" href="#autoid_30" data-menu-target="autoid_30">Using compress directive</a></li></ul></li><li><a class="page-menu-link" href="#dgui_misc_alternativesyntax" data-menu-target="dgui_misc_alternativesyntax">Alternative (square bracket) syntax</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#pgui" data-menu-target="pgui">Programmer's Guide</a><ul><li><a class="page-menu-link" href="#pgui_quickstart" data-menu-target="pgui_quickstart">Getting Started</a><ul><li><a class="page-menu-link" href="#pgui_quickstart_createconfiguration" data-menu-target="pgui_quickstart_createconfiguration">Create a configuration instance</a></li><li><a class="page-menu-link" href="#pgui_quickstart_createdatamodel" data-menu-target="pgui_quickstart_createdatamodel">Create a data-model</a></li><li><a class="page-menu-link" href="#pgui_quickstart_gettemplate" data-menu-target="pgui_quickstart_gettemplate">Get the template</a></li><li><a class="page-menu-link" href="#pgui_quickstart_merge" data-menu-target="pgui_quickstart_merge">Merging the template with the data-model</a></li><li><a class="page-menu-link" href="#pgui_quickstart_all" data-menu-target="pgui_quickstart_all">Putting all together</a></li></ul></li><li><a class="page-menu-link" href="#pgui_datamodel" data-menu-target="pgui_datamodel">The Data Model</a><ul><li><a class="page-menu-link" href="#pgui_datamodel_basics" data-menu-target="pgui_datamodel_basics">Basics</a></li><li><a class="page-menu-link" href="#pgui_datamodel_scalar" data-menu-target="pgui_datamodel_scalar">Scalars</a><ul><li><a class="page-menu-link" href="#autoid_31" data-menu-target="autoid_31">Difficulties with the date type</a></li></ul></li><li><a class="page-menu-link" href="#pgui_datamodel_parent" data-menu-target="pgui_datamodel_parent">Containers</a><ul><li><a class="page-menu-link" href="#autoid_32" data-menu-target="autoid_32">Hashes</a></li><li><a class="page-menu-link" href="#autoid_33" data-menu-target="autoid_33">Sequences</a></li><li><a class="page-menu-link" href="#autoid_34" data-menu-target="autoid_34">Collections</a></li></ul></li><li><a class="page-menu-link" href="#pgui_datamodel_method" data-menu-target="pgui_datamodel_method">Methods</a></li><li><a class="page-menu-link" href="#pgui_datamodel_directive" data-menu-target="pgui_datamodel_directive">Directives</a><ul><li><a class="page-menu-link" href="#autoid_35" data-menu-target="autoid_35">Example 1</a></li><li><a class="page-menu-link" href="#autoid_36" data-menu-target="autoid_36">Example 2</a></li><li><a class="page-menu-link" href="#autoid_37" data-menu-target="autoid_37">Notices</a></li></ul></li><li><a class="page-menu-link" href="#pgui_datamodel_node" data-menu-target="pgui_datamodel_node">Node variables</a></li><li><a class="page-menu-link" href="#pgui_datamodel_objectWrapper" data-menu-target="pgui_datamodel_objectWrapper">Object wrappers</a></li></ul></li><li><a class="page-menu-link" href="#pgui_config" data-menu-target="pgui_config">The Configuration</a><ul><li><a class="page-menu-link" href="#pgui_config_basics" data-menu-target="pgui_config_basics">Basics</a></li><li><a class="page-menu-link" href="#pgui_config_sharedvariables" data-menu-target="pgui_config_sharedvariables">Shared variables</a></li><li><a class="page-menu-link" href="#pgui_config_settings" data-menu-target="pgui_config_settings">Settings</a></li><li><a class="page-menu-link" href="#pgui_config_templateloading" data-menu-target="pgui_config_templateloading">Template loading</a><ul><li><a class="page-menu-link" href="#autoid_38" data-menu-target="autoid_38">Template loaders</a><ul><li><a class="page-menu-link" href="#autoid_39" data-menu-target="autoid_39">Built-in template loaders</a></li><li><a class="page-menu-link" href="#autoid_40" data-menu-target="autoid_40">Loading templates from multiple locations</a></li><li><a class="page-menu-link" href="#autoid_41" data-menu-target="autoid_41">Loading templates from other sources</a></li><li><a class="page-menu-link" href="#autoid_42" data-menu-target="autoid_42">The template path</a></li></ul></li><li><a class="page-menu-link" href="#pgui_config_templateloading_caching" data-menu-target="pgui_config_templateloading_caching">Template caching</a></li></ul></li><li><a class="page-menu-link" href="#pgui_config_errorhandling" data-menu-target="pgui_config_errorhandling">Error handling</a><ul><li><a class="page-menu-link" href="#autoid_43" data-menu-target="autoid_43">The possible exceptions</a></li><li><a class="page-menu-link" href="#autoid_44" data-menu-target="autoid_44">Customizing the behavior regarding TemplatException-s</a></li><li><a class="page-menu-link" href="#autoid_45" data-menu-target="autoid_45">Explicit error handling in templates</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#pgui_misc" data-menu-target="pgui_misc">Miscellaneous</a><ul><li><a class="page-menu-link" href="#pgui_misc_var" data-menu-target="pgui_misc_var">Variables</a></li><li><a class="page-menu-link" href="#pgui_misc_charset" data-menu-target="pgui_misc_charset">Charset issues</a><ul><li><a class="page-menu-link" href="#autoid_46" data-menu-target="autoid_46">The charset of the input</a></li><li><a class="page-menu-link" href="#autoid_47" data-menu-target="autoid_47">The charset of the output</a></li></ul></li><li><a class="page-menu-link" href="#pgui_misc_multithreading" data-menu-target="pgui_misc_multithreading">Multithreading</a></li><li><a class="page-menu-link" href="#pgui_misc_beanwrapper" data-menu-target="pgui_misc_beanwrapper">Bean wrapper</a><ul><li><a class="page-menu-link" href="#beanswrapper_hash" data-menu-target="beanswrapper_hash">TemplateHashModel functionality</a></li><li><a class="page-menu-link" href="#autoid_48" data-menu-target="autoid_48">A word on security</a></li><li><a class="page-menu-link" href="#autoid_49" data-menu-target="autoid_49">TemplateScalarModel functionality</a></li><li><a class="page-menu-link" href="#autoid_50" data-menu-target="autoid_50">TemplateNumberModel functionality</a></li><li><a class="page-menu-link" href="#autoid_51" data-menu-target="autoid_51">TemplateCollectionModel functionality</a></li><li><a class="page-menu-link" href="#autoid_52" data-menu-target="autoid_52">TemplateSequenceModel functionality</a></li><li><a class="page-menu-link" href="#beanswrapper_method" data-menu-target="beanswrapper_method">TemplateMethodModel functionality</a></li><li><a class="page-menu-link" href="#autoid_53" data-menu-target="autoid_53">Unwrapping rules</a></li><li><a class="page-menu-link" href="#autoid_54" data-menu-target="autoid_54">Accessing static methods</a></li><li><a class="page-menu-link" href="#jdk_15_enums" data-menu-target="jdk_15_enums">Accessing enums</a></li></ul></li><li><a class="page-menu-link" href="#pgui_misc_logging" data-menu-target="pgui_misc_logging">Logging</a></li><li><a class="page-menu-link" href="#pgui_misc_servlet" data-menu-target="pgui_misc_servlet">Using FreeMarker with servlets</a><ul><li><a class="page-menu-link" href="#pgui_misc_servlet_model2" data-menu-target="pgui_misc_servlet_model2">Using FreeMarker for ``Model 2''</a></li><li><a class="page-menu-link" href="#pgui_misc_servlet_include" data-menu-target="pgui_misc_servlet_include">Including content from other web application |
| resources</a></li><li><a class="page-menu-link" href="#autoid_55" data-menu-target="autoid_55">Using JSP custom tags in FTL</a></li><li><a class="page-menu-link" href="#autoid_56" data-menu-target="autoid_56">Embed FTL into JSP pages</a></li></ul></li><li><a class="page-menu-link" href="#pgui_misc_secureenv" data-menu-target="pgui_misc_secureenv">Configuring security policy for FreeMarker</a></li><li><a class="page-menu-link" href="#pgui_misc_xml_legacy" data-menu-target="pgui_misc_xml_legacy">Legacy XML wrapper implementation</a><ul><li><a class="page-menu-link" href="#autoid_57" data-menu-target="autoid_57">TemplateScalarModel</a></li><li><a class="page-menu-link" href="#autoid_58" data-menu-target="autoid_58">TemplateCollectionModel</a></li><li><a class="page-menu-link" href="#autoid_59" data-menu-target="autoid_59">TemplateSequenceModel</a></li><li><a class="page-menu-link" href="#autoid_60" data-menu-target="autoid_60">TemplateHashModel</a></li><li><a class="page-menu-link" href="#autoid_61" data-menu-target="autoid_61">TemplateMethodModel</a></li><li><a class="page-menu-link" href="#autoid_62" data-menu-target="autoid_62">Namespace handling</a></li></ul></li><li><a class="page-menu-link" href="#pgui_misc_ant" data-menu-target="pgui_misc_ant">Using FreeMarker with Ant</a></li><li><a class="page-menu-link" href="#pgui_misc_jythonwrapper" data-menu-target="pgui_misc_jythonwrapper">Jython wrapper</a><ul><li><a class="page-menu-link" href="#autoid_63" data-menu-target="autoid_63">TemplateHashModel functionality</a></li><li><a class="page-menu-link" href="#autoid_64" data-menu-target="autoid_64">TemplateScalarModel functionality</a></li><li><a class="page-menu-link" href="#autoid_65" data-menu-target="autoid_65">TemplateBooleanModel functionality</a></li><li><a class="page-menu-link" href="#autoid_66" data-menu-target="autoid_66">TemplateNumberModel functionality</a></li><li><a class="page-menu-link" href="#autoid_67" data-menu-target="autoid_67">TemplateSequenceModel functionality</a></li></ul></li></ul></li></ul></li><li><a class="page-menu-link" href="#xgui" data-menu-target="xgui">XML Processing Guide</a><ul><li><a class="page-menu-link" href="#xgui_preface" data-menu-target="xgui_preface">Preface</a></li><li><a class="page-menu-link" href="#xgui_expose" data-menu-target="xgui_expose">Exposing XML documents</a><ul><li><a class="page-menu-link" href="#xgui_expose_dom" data-menu-target="xgui_expose_dom">The DOM tree</a></li><li><a class="page-menu-link" href="#xgui_expose_put" data-menu-target="xgui_expose_put">Putting the XML into the data-model</a></li></ul></li><li><a class="page-menu-link" href="#xgui_imperative" data-menu-target="xgui_imperative">Imperative XML processing</a><ul><li><a class="page-menu-link" href="#xgui_imperative_learn" data-menu-target="xgui_imperative_learn">Learning by example</a><ul><li><a class="page-menu-link" href="#autoid_68" data-menu-target="autoid_68">Accessing elements by name</a></li><li><a class="page-menu-link" href="#autoid_69" data-menu-target="autoid_69">Accessing attributes</a></li><li><a class="page-menu-link" href="#autoid_70" data-menu-target="autoid_70">Exploring the tree</a></li><li><a class="page-menu-link" href="#autoid_71" data-menu-target="autoid_71">Using XPath expressions</a></li><li><a class="page-menu-link" href="#autoid_72" data-menu-target="autoid_72">XML namespaces</a></li><li><a class="page-menu-link" href="#autoid_73" data-menu-target="autoid_73">Don't forget escaping!</a></li></ul></li><li><a class="page-menu-link" href="#xgui_imperative_formal" data-menu-target="xgui_imperative_formal">Formal description</a><ul><li><a class="page-menu-link" href="#autoid_74" data-menu-target="autoid_74">Node sequences</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#xgui_declarative" data-menu-target="xgui_declarative">Declarative XML Processing</a><ul><li><a class="page-menu-link" href="#xgui_declarative_basics" data-menu-target="xgui_declarative_basics">Basics</a></li><li><a class="page-menu-link" href="#xgui_declarative_details" data-menu-target="xgui_declarative_details">Details</a><ul><li><a class="page-menu-link" href="#autoid_75" data-menu-target="autoid_75">Default handlers</a></li><li><a class="page-menu-link" href="#autoid_76" data-menu-target="autoid_76">Visiting a single node</a></li><li><a class="page-menu-link" href="#autoid_77" data-menu-target="autoid_77">XML namespaces</a></li></ul></li></ul></li></ul></li><li><a class="page-menu-link" href="#ref" data-menu-target="ref">Reference</a><ul><li><a class="page-menu-link" href="#ref_builtins" data-menu-target="ref_builtins">Built-in Reference</a><ul><li><a class="page-menu-link" href="#ref_builtins_string" data-menu-target="ref_builtins_string">Built-ins for strings</a><ul><li><a class="page-menu-link" href="#ref_builtin_substring" data-menu-target="ref_builtin_substring">substring</a></li><li><a class="page-menu-link" href="#ref_builtin_cap_first" data-menu-target="ref_builtin_cap_first">cap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_uncap_first" data-menu-target="ref_builtin_uncap_first">uncap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_capitalize" data-menu-target="ref_builtin_capitalize">capitalize</a></li><li><a class="page-menu-link" href="#ref_builtin_chop_linebreak" data-menu-target="ref_builtin_chop_linebreak">chop_linebreak</a></li><li><a class="page-menu-link" href="#ref_builtin_string_date" data-menu-target="ref_builtin_string_date">date, time, datetime</a></li><li><a class="page-menu-link" href="#ref_builtin_ends_with" data-menu-target="ref_builtin_ends_with">ends_with</a></li><li><a class="page-menu-link" href="#ref_builtin_html" data-menu-target="ref_builtin_html">html</a></li><li><a class="page-menu-link" href="#ref_builtin_groups" data-menu-target="ref_builtin_groups">groups</a></li><li><a class="page-menu-link" href="#ref_builtin_index_of" data-menu-target="ref_builtin_index_of">index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_j_string" data-menu-target="ref_builtin_j_string">j_string</a></li><li><a class="page-menu-link" href="#ref_builtin_js_string" data-menu-target="ref_builtin_js_string">js_string</a></li><li><a class="page-menu-link" href="#ref_builtin_last_index_of" data-menu-target="ref_builtin_last_index_of">last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_length" data-menu-target="ref_builtin_length">length</a></li><li><a class="page-menu-link" href="#ref_builtin_lower_case" data-menu-target="ref_builtin_lower_case">lower_case</a></li><li><a class="page-menu-link" href="#ref_builtin_left_pad" data-menu-target="ref_builtin_left_pad">left_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_right_pad" data-menu-target="ref_builtin_right_pad">right_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_contains" data-menu-target="ref_builtin_contains">contains</a></li><li><a class="page-menu-link" href="#ref_builtin_matches" data-menu-target="ref_builtin_matches">matches</a></li><li><a class="page-menu-link" href="#ref_builtin_number" data-menu-target="ref_builtin_number">number</a></li><li><a class="page-menu-link" href="#ref_builtin_replace" data-menu-target="ref_builtin_replace">replace</a></li><li><a class="page-menu-link" href="#ref_builtin_rtf" data-menu-target="ref_builtin_rtf">rtf</a></li><li><a class="page-menu-link" href="#ref_builtin_url" data-menu-target="ref_builtin_url">url</a></li><li><a class="page-menu-link" href="#ref_builtin_split" data-menu-target="ref_builtin_split">split</a></li><li><a class="page-menu-link" href="#ref_builtin_starts_with" data-menu-target="ref_builtin_starts_with">starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_string" data-menu-target="ref_builtin_string_for_string">string (when used with a string value)</a></li><li><a class="page-menu-link" href="#ref_builtin_trim" data-menu-target="ref_builtin_trim">trim</a></li><li><a class="page-menu-link" href="#ref_builtin_upper_case" data-menu-target="ref_builtin_upper_case">upper_case</a></li><li><a class="page-menu-link" href="#ref_builtin_word_list" data-menu-target="ref_builtin_word_list">word_list</a></li><li><a class="page-menu-link" href="#ref_builtin_xhtml" data-menu-target="ref_builtin_xhtml">xhtml</a></li><li><a class="page-menu-link" href="#ref_builtin_xml" data-menu-target="ref_builtin_xml">xml</a></li><li><a class="page-menu-link" href="#ref_builtin_string_flags" data-menu-target="ref_builtin_string_flags">Common flags</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_number" data-menu-target="ref_builtins_number">Built-ins for numbers</a><ul><li><a class="page-menu-link" href="#ref_builtin_c" data-menu-target="ref_builtin_c">c</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_number" data-menu-target="ref_builtin_string_for_number">string (when used with a numerical value)</a></li><li><a class="page-menu-link" href="#ref_builtin_rounding" data-menu-target="ref_builtin_rounding">round, floor, ceiling</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_date" data-menu-target="ref_builtins_date">Built-ins for dates</a><ul><li><a class="page-menu-link" href="#ref_builtin_string_for_date" data-menu-target="ref_builtin_string_for_date">string (when used with a date value)</a></li><li><a class="page-menu-link" href="#ref_builtin_date_datetype" data-menu-target="ref_builtin_date_datetype">date, time, datetime</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_boolean" data-menu-target="ref_builtins_boolean">Built-ins for booleans</a><ul><li><a class="page-menu-link" href="#ref_builtin_string_for_boolean" data-menu-target="ref_builtin_string_for_boolean">string (when used with a boolean value)</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_sequence" data-menu-target="ref_builtins_sequence">Built-ins for sequences</a><ul><li><a class="page-menu-link" href="#ref_builtin_first" data-menu-target="ref_builtin_first">first</a></li><li><a class="page-menu-link" href="#ref_builtin_last" data-menu-target="ref_builtin_last">last</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_contains" data-menu-target="ref_builtin_seq_contains">seq_contains</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_index_of" data-menu-target="ref_builtin_seq_index_of">seq_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_seq_last_index_of" data-menu-target="ref_builtin_seq_last_index_of">seq_last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_reverse" data-menu-target="ref_builtin_reverse">reverse</a></li><li><a class="page-menu-link" href="#ref_builtin_size" data-menu-target="ref_builtin_size">size</a></li><li><a class="page-menu-link" href="#ref_builtin_sort" data-menu-target="ref_builtin_sort">sort</a></li><li><a class="page-menu-link" href="#ref_builtin_sort_by" data-menu-target="ref_builtin_sort_by">sort_by</a></li><li><a class="page-menu-link" href="#ref_builtin_chunk" data-menu-target="ref_builtin_chunk">chunk</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_hash" data-menu-target="ref_builtins_hash">Built-ins for hashes</a><ul><li><a class="page-menu-link" href="#ref_builtin_keys" data-menu-target="ref_builtin_keys">keys</a></li><li><a class="page-menu-link" href="#ref_builtin_values" data-menu-target="ref_builtin_values">values</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_node" data-menu-target="ref_builtins_node">Built-ins for nodes (for XML)</a><ul><li><a class="page-menu-link" href="#ref_builtin_children" data-menu-target="ref_builtin_children">children</a></li><li><a class="page-menu-link" href="#ref_builtin_parent" data-menu-target="ref_builtin_parent">parent</a></li><li><a class="page-menu-link" href="#ref_builtin_root" data-menu-target="ref_builtin_root">root</a></li><li><a class="page-menu-link" href="#ref_builtin_ancestors" data-menu-target="ref_builtin_ancestors">ancestors</a></li><li><a class="page-menu-link" href="#ref_builtin_node_name" data-menu-target="ref_builtin_node_name">node_name</a></li><li><a class="page-menu-link" href="#ref_builtin_node_type" data-menu-target="ref_builtin_node_type">node_type</a></li><li><a class="page-menu-link" href="#ref_builtin_node_namespace" data-menu-target="ref_builtin_node_namespace">node_namespace</a></li></ul></li><li><a class="page-menu-link" href="#ref_builtins_expert" data-menu-target="ref_builtins_expert">Seldom used and expert built-ins</a><ul><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_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_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></ul></li></ul></li><li><a class="page-menu-link" href="#ref_directives" data-menu-target="ref_directives">Directive Reference</a><ul><li><a class="page-menu-link" href="#ref_directive_if" data-menu-target="ref_directive_if">if, else, elseif</a><ul><li><a class="page-menu-link" href="#autoid_78" data-menu-target="autoid_78">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_79" data-menu-target="autoid_79">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_switch" data-menu-target="ref_directive_switch">switch, case, default, break</a><ul><li><a class="page-menu-link" href="#autoid_80" data-menu-target="autoid_80">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_81" data-menu-target="autoid_81">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_list" data-menu-target="ref_directive_list">list, break</a><ul><li><a class="page-menu-link" href="#autoid_82" data-menu-target="autoid_82">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_83" data-menu-target="autoid_83">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_include" data-menu-target="ref_directive_include">include</a><ul><li><a class="page-menu-link" href="#autoid_84" data-menu-target="autoid_84">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_85" data-menu-target="autoid_85">Description</a><ul><li><a class="page-menu-link" href="#ref_directive_include_acquisition" data-menu-target="ref_directive_include_acquisition">Using acquisition</a></li><li><a class="page-menu-link" href="#ref_directive_include_localized" data-menu-target="ref_directive_include_localized">Localized lookup</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#ref_directive_import" data-menu-target="ref_directive_import">import</a><ul><li><a class="page-menu-link" href="#autoid_86" data-menu-target="autoid_86">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_87" data-menu-target="autoid_87">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_noparse" data-menu-target="ref_directive_noparse">noparse</a><ul><li><a class="page-menu-link" href="#autoid_88" data-menu-target="autoid_88">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_89" data-menu-target="autoid_89">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_compress" data-menu-target="ref_directive_compress">compress</a><ul><li><a class="page-menu-link" href="#autoid_90" data-menu-target="autoid_90">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_91" data-menu-target="autoid_91">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_escape" data-menu-target="ref_directive_escape">escape, noescape</a><ul><li><a class="page-menu-link" href="#autoid_92" data-menu-target="autoid_92">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_93" data-menu-target="autoid_93">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_assign" data-menu-target="ref_directive_assign">assign</a><ul><li><a class="page-menu-link" href="#autoid_94" data-menu-target="autoid_94">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_95" data-menu-target="autoid_95">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_global" data-menu-target="ref_directive_global">global</a><ul><li><a class="page-menu-link" href="#autoid_96" data-menu-target="autoid_96">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_97" data-menu-target="autoid_97">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_local" data-menu-target="ref_directive_local">local</a><ul><li><a class="page-menu-link" href="#autoid_98" data-menu-target="autoid_98">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_99" data-menu-target="autoid_99">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_setting" data-menu-target="ref_directive_setting">setting</a><ul><li><a class="page-menu-link" href="#autoid_100" data-menu-target="autoid_100">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_101" data-menu-target="autoid_101">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_userDefined" data-menu-target="ref_directive_userDefined">User-defined directive (<@...>)</a><ul><li><a class="page-menu-link" href="#autoid_102" data-menu-target="autoid_102">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_103" data-menu-target="autoid_103">Description</a><ul><li><a class="page-menu-link" href="#ref_directive_userDefined_entTag" data-menu-target="ref_directive_userDefined_entTag">End-tag</a></li><li><a class="page-menu-link" href="#ref_directive_userDefined_loopVar" data-menu-target="ref_directive_userDefined_loopVar">Loop variables</a></li><li><a class="page-menu-link" href="#ref_directive_userDefined_positionalParam" data-menu-target="ref_directive_userDefined_positionalParam">Positional parameter passing</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#ref_directive_macro" data-menu-target="ref_directive_macro">macro, nested, return</a><ul><li><a class="page-menu-link" href="#autoid_104" data-menu-target="autoid_104">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_105" data-menu-target="autoid_105">Description</a><ul><li><a class="page-menu-link" href="#autoid_106" data-menu-target="autoid_106">nested</a></li><li><a class="page-menu-link" href="#autoid_107" data-menu-target="autoid_107">return</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#ref_directive_function" data-menu-target="ref_directive_function">function, return</a><ul><li><a class="page-menu-link" href="#autoid_108" data-menu-target="autoid_108">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_109" data-menu-target="autoid_109">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_flush" data-menu-target="ref_directive_flush">flush</a><ul><li><a class="page-menu-link" href="#autoid_110" data-menu-target="autoid_110">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_111" data-menu-target="autoid_111">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_stop" data-menu-target="ref_directive_stop">stop</a><ul><li><a class="page-menu-link" href="#autoid_112" data-menu-target="autoid_112">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_113" data-menu-target="autoid_113">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_ftl" data-menu-target="ref_directive_ftl">ftl</a><ul><li><a class="page-menu-link" href="#autoid_114" data-menu-target="autoid_114">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_115" data-menu-target="autoid_115">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_t" data-menu-target="ref_directive_t">t, lt, rt</a><ul><li><a class="page-menu-link" href="#autoid_116" data-menu-target="autoid_116">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_117" data-menu-target="autoid_117">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_nt" data-menu-target="ref_directive_nt">nt</a><ul><li><a class="page-menu-link" href="#autoid_118" data-menu-target="autoid_118">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_119" data-menu-target="autoid_119">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_attempt" data-menu-target="ref_directive_attempt">attempt, recover</a><ul><li><a class="page-menu-link" href="#autoid_120" data-menu-target="autoid_120">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_121" data-menu-target="autoid_121">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_directive_visit" data-menu-target="ref_directive_visit">visit, recurse, fallback</a><ul><li><a class="page-menu-link" href="#autoid_122" data-menu-target="autoid_122">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_123" data-menu-target="autoid_123">Description</a><ul><li><a class="page-menu-link" href="#autoid_124" data-menu-target="autoid_124">Visit</a></li><li><a class="page-menu-link" href="#autoid_125" data-menu-target="autoid_125">Recurse</a></li><li><a class="page-menu-link" href="#autoid_126" data-menu-target="autoid_126">Fallback</a></li></ul></li></ul></li></ul></li><li><a class="page-menu-link" href="#ref_specvar" data-menu-target="ref_specvar">Special Variable Reference</a></li><li><a class="page-menu-link" href="#ref_reservednames" data-menu-target="ref_reservednames">Reserved names in FTL</a></li><li><a class="page-menu-link" href="#ref_deprecated" data-menu-target="ref_deprecated">Deprecated FTL constructs</a><ul><li><a class="page-menu-link" href="#ref_depr_directive" data-menu-target="ref_depr_directive">List of deprecated directives</a></li><li><a class="page-menu-link" href="#ref_depr_builtin" data-menu-target="ref_depr_builtin">List of deprecated built-ins</a></li><li><a class="page-menu-link" href="#ref_depr_oldmacro" data-menu-target="ref_depr_oldmacro">Old-style macro and call directives</a><ul><li><a class="page-menu-link" href="#autoid_127" data-menu-target="autoid_127">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_128" data-menu-target="autoid_128">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_depr_transform" data-menu-target="ref_depr_transform">Transform directive</a><ul><li><a class="page-menu-link" href="#autoid_129" data-menu-target="autoid_129">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_130" data-menu-target="autoid_130">Description</a></li></ul></li><li><a class="page-menu-link" href="#ref_depr_oldsyntax" data-menu-target="ref_depr_oldsyntax">Old FTL syntax</a></li><li><a class="page-menu-link" href="#ref_depr_numerical_interpolation" data-menu-target="ref_depr_numerical_interpolation">#{...}: Numerical interpolation</a><ul><li><a class="page-menu-link" href="#autoid_131" data-menu-target="autoid_131">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_132" data-menu-target="autoid_132">Description</a></li></ul></li></ul></li></ul></li><li><a class="page-menu-link" href="#app" data-menu-target="app">Appendixes</a><ul><li><a class="page-menu-link" href="#app_faq" data-menu-target="app_faq">FAQ</a></li><li><a class="page-menu-link" href="#app_install" data-menu-target="app_install">Installing FreeMarker</a></li><li><a class="page-menu-link" href="#app_build" data-menu-target="app_build">Building FreeMarker</a></li><li><a class="page-menu-link" href="#app_versions" data-menu-target="app_versions">Versions</a><ul><li><a class="page-menu-link" href="#versions_2_3_16" data-menu-target="versions_2_3_16">2.3.16</a></li><li><a class="page-menu-link" href="#versions_2_3_15" data-menu-target="versions_2_3_15">2.3.15</a><ul><li><a class="page-menu-link" href="#autoid_133" data-menu-target="autoid_133">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_134" data-menu-target="autoid_134">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_135" data-menu-target="autoid_135">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_14" data-menu-target="versions_2_3_14">2.3.14</a><ul><li><a class="page-menu-link" href="#autoid_136" data-menu-target="autoid_136">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_137" data-menu-target="autoid_137">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_13" data-menu-target="versions_2_3_13">2.3.13</a><ul><li><a class="page-menu-link" href="#autoid_138" data-menu-target="autoid_138">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_139" data-menu-target="autoid_139">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_12" data-menu-target="versions_2_3_12">2.3.12</a><ul><li><a class="page-menu-link" href="#autoid_140" data-menu-target="autoid_140">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_11" data-menu-target="versions_2_3_11">2.3.11</a><ul><li><a class="page-menu-link" href="#autoid_141" data-menu-target="autoid_141">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_142" data-menu-target="autoid_142">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_143" data-menu-target="autoid_143">Documentation changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_10" data-menu-target="versions_2_3_10">2.3.10</a><ul><li><a class="page-menu-link" href="#autoid_144" data-menu-target="autoid_144">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_145" data-menu-target="autoid_145">Changes on the FTL side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_9" data-menu-target="versions_2_3_9">2.3.9</a><ul><li><a class="page-menu-link" href="#autoid_146" data-menu-target="autoid_146">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_8" data-menu-target="versions_2_3_8">2.3.8</a><ul><li><a class="page-menu-link" href="#autoid_147" data-menu-target="autoid_147">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_7" data-menu-target="versions_2_3_7">2.3.7</a><ul><li><a class="page-menu-link" href="#autoid_148" data-menu-target="autoid_148">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_149" data-menu-target="autoid_149">Changes on the FTL side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_7rc1" data-menu-target="versions_2_3_7rc1">2.3.7 RC1</a><ul><li><a class="page-menu-link" href="#autoid_150" data-menu-target="autoid_150">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_151" data-menu-target="autoid_151">Changes on the FTL side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_6" data-menu-target="versions_2_3_6">2.3.6</a><ul><li><a class="page-menu-link" href="#autoid_152" data-menu-target="autoid_152">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_5" data-menu-target="versions_2_3_5">2.3.5</a><ul><li><a class="page-menu-link" href="#autoid_153" data-menu-target="autoid_153">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_154" data-menu-target="autoid_154">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_4" data-menu-target="versions_2_3_4">2.3.4</a><ul><li><a class="page-menu-link" href="#autoid_155" data-menu-target="autoid_155">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_156" data-menu-target="autoid_156">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_157" data-menu-target="autoid_157">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_3" data-menu-target="versions_2_3_3">2.3.3</a><ul><li><a class="page-menu-link" href="#autoid_158" data-menu-target="autoid_158">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_159" data-menu-target="autoid_159">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_160" data-menu-target="autoid_160">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_2" data-menu-target="versions_2_3_2">2.3.2</a><ul><li><a class="page-menu-link" href="#autoid_161" data-menu-target="autoid_161">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_3_1" data-menu-target="versions_2_3_1">2.3.1</a><ul><li><a class="page-menu-link" href="#autoid_162" data-menu-target="autoid_162">Possible backward compatibility issue</a></li><li><a class="page-menu-link" href="#autoid_163" data-menu-target="autoid_163">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_164" data-menu-target="autoid_164">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_165" data-menu-target="autoid_165">Other changes</a></li><li><a class="page-menu-link" href="#autoid_166" data-menu-target="autoid_166">The history of the releases before the final version</a><ul><li><a class="page-menu-link" href="#autoid_167" data-menu-target="autoid_167">Differences between the preview release and final |
| release</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#versions_2_3" data-menu-target="versions_2_3">2.3</a><ul><li><a class="page-menu-link" href="#autoid_168" data-menu-target="autoid_168">Non backward-compatible changes!</a></li><li><a class="page-menu-link" href="#autoid_169" data-menu-target="autoid_169">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_170" data-menu-target="autoid_170">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_171" data-menu-target="autoid_171">Other changes</a></li><li><a class="page-menu-link" href="#autoid_172" data-menu-target="autoid_172">The history of the releases before the final version</a><ul><li><a class="page-menu-link" href="#autoid_173" data-menu-target="autoid_173">Differences between the final release and Release Candidate |
| 4</a></li><li><a class="page-menu-link" href="#autoid_174" data-menu-target="autoid_174">Differences between the Release Candidate 4 and Release |
| Candidate 3</a></li><li><a class="page-menu-link" href="#autoid_175" data-menu-target="autoid_175">Differences between the Release Candidate 3 and Release |
| Candidate 2</a></li><li><a class="page-menu-link" href="#autoid_176" data-menu-target="autoid_176">Differences between the Release Candidate 2 and Release |
| Candidate 1</a></li><li><a class="page-menu-link" href="#autoid_177" data-menu-target="autoid_177">Differences between the Release Candidate 1 and Preview 16 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_178" data-menu-target="autoid_178">Differences between the Preview 16 and Preview 15 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_179" data-menu-target="autoid_179">Differences between the Preview 15 and Preview 14 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_180" data-menu-target="autoid_180">Differences between the Preview 14 and Preview 13 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_181" data-menu-target="autoid_181">Differences between the Preview 13 and Preview 12 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_182" data-menu-target="autoid_182">Differences between the Preview 12 and Preview 11 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_183" data-menu-target="autoid_183">Differences between the Preview 11 and Preview 10 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_184" data-menu-target="autoid_184">Differences between the Preview 10 and Preview 9 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_185" data-menu-target="autoid_185">Differences between the Preview 9 and Preview 8 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_186" data-menu-target="autoid_186">Differences between the Preview 8 and Preview 7 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_187" data-menu-target="autoid_187">Differences between the Preview 7 and Preview 6 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_188" data-menu-target="autoid_188">Differences between the Preview 6 and Preview 5 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_189" data-menu-target="autoid_189">Differences between the Preview 5 and Preview 4 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_190" data-menu-target="autoid_190">Differences between the Preview 4 and Preview 3 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_191" data-menu-target="autoid_191">Differences between the Preview 3 and Preview 2 |
| releases</a></li><li><a class="page-menu-link" href="#autoid_192" data-menu-target="autoid_192">Differences between the Preview 2 and Preview 1 |
| releases</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_8" data-menu-target="versions_2_2_8">2.2.8</a><ul><li><a class="page-menu-link" href="#autoid_193" data-menu-target="autoid_193">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_194" data-menu-target="autoid_194">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_195" data-menu-target="autoid_195">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_7" data-menu-target="versions_2_2_7">2.2.7</a><ul><li><a class="page-menu-link" href="#autoid_196" data-menu-target="autoid_196">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_6" data-menu-target="versions_2_2_6">2.2.6</a><ul><li><a class="page-menu-link" href="#autoid_197" data-menu-target="autoid_197">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_198" data-menu-target="autoid_198">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_199" data-menu-target="autoid_199">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_5" data-menu-target="versions_2_2_5">2.2.5</a><ul><li><a class="page-menu-link" href="#autoid_200" data-menu-target="autoid_200">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_4" data-menu-target="versions_2_2_4">2.2.4</a><ul><li><a class="page-menu-link" href="#autoid_201" data-menu-target="autoid_201">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_202" data-menu-target="autoid_202">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_3" data-menu-target="versions_2_2_3">2.2.3</a><ul><li><a class="page-menu-link" href="#autoid_203" data-menu-target="autoid_203">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_204" data-menu-target="autoid_204">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_2" data-menu-target="versions_2_2_2">2.2.2</a><ul><li><a class="page-menu-link" href="#autoid_205" data-menu-target="autoid_205">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2_1" data-menu-target="versions_2_2_1">2.2.1</a><ul><li><a class="page-menu-link" href="#autoid_206" data-menu-target="autoid_206">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_207" data-menu-target="autoid_207">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_2" data-menu-target="versions_2_2">2.2</a><ul><li><a class="page-menu-link" href="#autoid_208" data-menu-target="autoid_208">Non backward-compatible changes!</a></li><li><a class="page-menu-link" href="#autoid_209" data-menu-target="autoid_209">Changes in FTL (FreeMarker Template Language)</a></li><li><a class="page-menu-link" href="#autoid_210" data-menu-target="autoid_210">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_211" data-menu-target="autoid_211">Other changes</a></li><li><a class="page-menu-link" href="#autoid_212" data-menu-target="autoid_212">The history of the releases before the final version</a><ul><li><a class="page-menu-link" href="#autoid_213" data-menu-target="autoid_213">Differences between the final and RC2 releases</a></li><li><a class="page-menu-link" href="#autoid_214" data-menu-target="autoid_214">Differences between the RC2 and RC1 releases</a></li><li><a class="page-menu-link" href="#autoid_215" data-menu-target="autoid_215">Differences between the Preview 2 and RC1 releases</a></li><li><a class="page-menu-link" href="#autoid_216" data-menu-target="autoid_216">Differences between the Preview 1 and Preview 2 |
| releases</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#versions_2_1_5" data-menu-target="versions_2_1_5">2.1.5</a><ul><li><a class="page-menu-link" href="#autoid_217" data-menu-target="autoid_217">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_1_4" data-menu-target="versions_2_1_4">2.1.4</a><ul><li><a class="page-menu-link" href="#autoid_218" data-menu-target="autoid_218">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_1_3" data-menu-target="versions_2_1_3">2.1.3</a><ul><li><a class="page-menu-link" href="#autoid_219" data-menu-target="autoid_219">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_220" data-menu-target="autoid_220">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_1_2" data-menu-target="versions_2_1_2">2.1.2</a><ul><li><a class="page-menu-link" href="#autoid_221" data-menu-target="autoid_221">Changes in FTL (FreeMarker Template Language)</a></li><li><a class="page-menu-link" href="#autoid_222" data-menu-target="autoid_222">Other changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_1_1" data-menu-target="versions_2_1_1">2.1.1</a><ul><li><a class="page-menu-link" href="#autoid_223" data-menu-target="autoid_223">Changes in FTL (FreeMarker Template Language)</a></li><li><a class="page-menu-link" href="#autoid_224" data-menu-target="autoid_224">Changes on the Java side</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_1" data-menu-target="versions_2_1">2.1</a><ul><li><a class="page-menu-link" href="#autoid_225" data-menu-target="autoid_225">Changes in FTL (FreeMarker Template Language)</a></li><li><a class="page-menu-link" href="#autoid_226" data-menu-target="autoid_226">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_227" data-menu-target="autoid_227">Other changes</a></li><li><a class="page-menu-link" href="#autoid_228" data-menu-target="autoid_228">Differences between the RC1 and final release</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_01" data-menu-target="versions_2_01">2.01</a></li><li><a class="page-menu-link" href="#versions_2_0" data-menu-target="versions_2_0">2.0</a><ul><li><a class="page-menu-link" href="#autoid_229" data-menu-target="autoid_229">Bugfixes</a></li><li><a class="page-menu-link" href="#autoid_230" data-menu-target="autoid_230">Changes to the Template language</a></li><li><a class="page-menu-link" href="#autoid_231" data-menu-target="autoid_231">Changes to the API</a></li><li><a class="page-menu-link" href="#autoid_232" data-menu-target="autoid_232">Miscellany</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_0RC3" data-menu-target="versions_2_0RC3">2.0 RC3</a><ul><li><a class="page-menu-link" href="#autoid_233" data-menu-target="autoid_233">Bug Fixes</a></li><li><a class="page-menu-link" href="#autoid_234" data-menu-target="autoid_234">Changes to the Template Language</a></li><li><a class="page-menu-link" href="#autoid_235" data-menu-target="autoid_235">API changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_0RC2" data-menu-target="versions_2_0RC2">2.0 RC2</a><ul><li><a class="page-menu-link" href="#autoid_236" data-menu-target="autoid_236">Changes to Template Language</a></li><li><a class="page-menu-link" href="#autoid_237" data-menu-target="autoid_237">API Changes</a></li></ul></li><li><a class="page-menu-link" href="#versions_2_0RC1" data-menu-target="versions_2_0RC1">2.0 RC1</a><ul><li><a class="page-menu-link" href="#autoid_238" data-menu-target="autoid_238">Support for Numerical operations, both arithmetic and |
| boolean, as well as numerical ranges.</a></li><li><a class="page-menu-link" href="#autoid_239" data-menu-target="autoid_239">API Changes</a></li><li><a class="page-menu-link" href="#autoid_240" data-menu-target="autoid_240">Syntactical Miscellany</a></li></ul></li></ul></li><li><a class="page-menu-link" href="#app_license" data-menu-target="app_license">License</a></li></ul></li><li><a class="page-menu-link" href="#gloss" data-menu-target="gloss">Glossary</a></li><li><a class="page-menu-link" href="#alphaidx" data-menu-target="alphaidx">Alphabetical Index</a></li></ul> </div> |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="preface">Preface</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section1" id="autoid_2">What is FreeMarker?</h3> |
| |
| |
| <p>FreeMarker is a <em>template engine</em>: a generic |
| tool to generate text output (anything from HTML to autogenerated source |
| code) based on templates. It's a Java package, a class library for Java |
| programmers. It's not an application for end-users in itself, but |
| something that programmers can embed into their products.</p> |
| |
| <p>FreeMarker is designed to be practical for the generation of |
| <em>HTML Web pages</em>, particularly by servlet-based |
| applications following the <a href="#gloss.MVC">MVC (Model View |
| Controller) pattern</a>. The idea behind using the MVC pattern for |
| dynamic Web pages is that you separate the designers (HTML authors) from |
| the programmers. Everybody works on what they are good at. Designers can |
| change the appearance of a page without programmers having to change or |
| recompile code, because the application logic (Java programs) and page |
| design (FreeMarker templates) are separated. Templates do not become |
| polluted with complex program fragments. This separation is useful even |
| for projects where the programmer and the HTML page author is the same |
| person, since it helps to keep the application clear and easily |
| maintainable.</p> |
| |
| <p>Although FreeMarker has some programming capabilities, it is |
| <em>not</em> a full-blown programming language like PHP. |
| Instead, Java programs prepare the data to be displayed (like issue SQL |
| queries), and FreeMarker just generates textual pages that display the |
| prepared data using templates.</p> |
| |
| <p class="center-img"> <img src="figures/overview.png" alt="Figure"> </p> |
| |
| |
| <p>FreeMarker is <em>not</em> a Web application |
| framework. It is suitable as a component in a Web application framework, |
| but the FreeMarker engine itself knows nothing about HTTP or servlets. |
| It simply generates text. As such, it is perfectly usable in non-web |
| application environments as well. Note, however, that we provide |
| out-of-the-box solutions for using FreeMarker as the view component of |
| Model 2 frameworks such as Struts.</p> |
| |
| <p>FreeMarker is <a href="http://www.fsf.org/philosophy/free-sw.html">Free</a>, |
| released under a BSD-style license. It is <a href="http://www.opensource.org/">OSI Certified Open Source |
| Software</a>. OSI Certified is a certification mark of the Open |
| Source Initiative.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section1" id="autoid_3">What should I read?</h3> |
| |
| |
| <p>If you are a ...</p> |
| |
| <ul> |
| <li> |
| <p>designer, then you should read the <a href="#dgui">Template Author's Guide</a> and |
| then you can look into the <a href="#ref">Reference</a> on an as-needed |
| basis for more specific details.</p> |
| </li> |
| |
| <li> |
| <p>programmer, then you should read the <a href="#dgui">Template Author's Guide</a> |
| guide first, then the <a href="#pgui">Programmer's Guide</a> and then you can look |
| into the <a href="#ref">Reference</a> on an as-needed basis for more |
| specific details.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section1" id="autoid_4">Document conventions</h3> |
| |
| |
| <p>Variable names, template fragments, Java class names, etc. are |
| written like this: <code class="inline-code">foo</code>.</p> |
| |
| <p>If something should be replaced with a concrete value then it is |
| written in italics, as follows: <code class="inline-code">Hello |
| <em class="code-color">yourName</em>!</code>.</p> |
| |
| <p>Template examples are written like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">something</pre></div> |
| |
| <p>Data-model examples are written like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">something</pre></div> |
| |
| <p>Output examples are written like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">something</pre></div> |
| |
| <p>Program examples are written like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">something</pre></div> |
| |
| |
| |
| <p>In chapters written for both designers and programmers fragments |
| addressed to programmers are written like this: <span class="marked-for-programmers">This is for programmers only.</span></p> |
| |
| <p>New terms are emphasized like this: <strong>some new |
| term</strong></p> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section1" id="autoid_5">Contact</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>For the latest version of FreeMarker and to subscribe to the |
| <em>mailing lists</em> visit the FreeMarker homepage: <a href="http://freemarker.org/">http://freemarker.org</a></p> |
| |
| <p class="center-img"><a name="test_target"></a> <img src="bat.jpg" alt="Figure"> </p> |
| |
| |
| <p>If you <em>need help</em> or you have |
| <em>suggestions</em>, use the mailing lists (mail archives |
| can be searched without subscription) or the Web based forums. If you |
| want to <em>report a bug</em>, use the Web based bug |
| tracker, or the mailing lists. To find all of these visit <a href="http://freemarker.org/">http://freemarker.org</a>. Also, |
| note that we have a <a href="#app_faq">FAQ</a> and <a href="#alphaidx">index</a>; use them.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-section1" id="autoid_6">About this document</h3> |
| |
| |
| <p>If you find <em>any mistakes</em> (including |
| <em>grammatical mistakes</em>, <em>typos</em>, |
| typographical mistakes) or you find something <em>misleading or |
| confusing</em> in the documentation, or you have other |
| suggestions, please let me know! Email: ddekany at |
| users.sourceforge.net</p> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="dgui">Template Author's Guide</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="dgui_quickstart">Getting Started</h3> |
| |
| |
| <p>This chapter is a very rough introduction to FreeMarker. The |
| chapters after this will go over things in much greater detail. |
| Nonetheless, once you have read this chapter, you will be able to write |
| simple but useful FreeMarker templates.</p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_quickstart_basics">Template + data-model = output</h4> |
| |
| |
| <p>Assume you need a HTML page in an e-shop application, similar to |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><html> |
| <head> |
| <title>Welcome!</title> |
| </head> |
| <body> |
| <h1>Welcome <strong>Big Joe</strong>!</h1> |
| <p>Our latest product: |
| <a href="<strong>products/greenmouse.html</strong>"><strong>green mouse</strong></a>! |
| </body> |
| </html></pre></div> |
| |
| <p>Let's say that the user name ("Big Joe" above) should depend on |
| who the logged in Web page visitor is, and the latest product should |
| come from a database and thus it potentially changes at any moment. In |
| this situation you can't just enter the user name nor the URL and name |
| of the latest product into the HTML, you can't use static HTML.</p> |
| |
| <p>FreeMarker's solution for this problem is using a <strong>template</strong> instead of the static HTML. The |
| template is the same as the static HTML, except that it contains some |
| instructions to FreeMarker that makes it dynamic:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a name="example.first"></a><html> |
| <head> |
| <title>Welcome!</title> |
| </head> |
| <body> |
| <h1>Welcome <strong>${user}</strong>!</h1> |
| <p>Our latest product: |
| <a href="<strong>${latestProduct.url}</strong>"><strong>${latestProduct.name}</strong></a>! |
| </body> |
| </html></pre></div> |
| |
| <p>The template is stored on the Web server, usually just like the |
| static HTML page would be. But whenever someone visits this page, |
| FreeMarker will step in and transform the template on-the-fly to plain |
| HTML by replacing the |
| <code class="inline-code">${<em class="code-color">...</em>}</code>-s with up-to-date |
| content (e.g., replacing <code class="inline-code">${user}</code> with Big Joe or |
| whoever the visitor is) and send the result to the visitor's Web |
| browser. So the visitor's Web browser will receive something like the |
| first example HTML (i.e., plain HTML without FreeMarker instructions), |
| and it will not perceive that FreeMarker is used on the server. The |
| template file itself (which is, again, stored on the Web server) is |
| not changed during this, so the transformation will happen again and |
| again for each visiting. This ensures that the displayed information |
| is always up-to-date.</p> |
| |
| <p>Now, you may already noticed that the template contains no |
| instructions regarding how to find out who the current visitor is, or |
| how to query the database to find out what the latest product is. It |
| seems it just already know these values. And indeed that's the case. |
| An important idea behind FreeMarker (actually, behind Web MVC) is that |
| presentation logic and "business logic" should be separated. In the |
| template you only deal with presentation issues, that is, visual |
| design issues, formatting issues. The data that will be displayed |
| (such as the user name and so on) is prepared outside FreeMarker, |
| usually by routines written in Java language or other general purpose |
| language. So the template author doesn't have to know how these values |
| are calculated. In fact, the way these values are calculated can be |
| completely changed while the templates can remain the same, and also, |
| the look of the page can be completely changed without touching |
| anything but the template. This separation can be especially useful |
| when the template authors (designers) and the programmers are |
| different individuals.</p> |
| |
| <p>While for FreeMarker (and for the template author) it's |
| not interesting <em>how</em> the data was calculated, |
| FreeMarker still have to know <em>what</em> the actual |
| data is. All the data that the template can use is packed into the so |
| called <strong>data-model</strong>. It's created by |
| the already mentioned routines that calculate the data. As far as the |
| template author is concerned, the data-model is a tree-like structure |
| (like folders and files on your hard disk), that in this case could be |
| visualized as:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- <strong>user</strong> = "Big Joe" |
| | |
| +- <strong>latestProduct</strong> |
| | |
| +- <strong>url</strong> = "products/greenmouse.html" |
| | |
| +- <strong>name</strong> = "green mouse"</pre></div> |
| |
| <p>(To prevent misunderstandings: The data-model is not a text |
| file, the above is just a visualization of a data-model for you. It's |
| from Java objects, but let that be the problem of the Java |
| programmers.)</p> |
| |
| <p>Compare this with what you seen in the template earlier: |
| <code class="inline-code">${user}</code> and |
| <code class="inline-code">${latestProduct.name}</code>. As an analogy, the data |
| model is something like the file system of computers: the root and |
| <code class="inline-code">latestProduct</code> correspond to directories (folders) |
| and the <code class="inline-code">user</code>, <code class="inline-code">url</code> and |
| <code class="inline-code">name</code> correspond to files. <code class="inline-code">url</code> |
| and <code class="inline-code">name</code> are in the |
| <code class="inline-code">latestProduct</code> directory. So |
| <code class="inline-code">latestProduct.name</code> is like saying |
| <code class="inline-code">name</code> in the <code class="inline-code">latestProduct</code> |
| directory. But as I said, it was just a simile; there are no files or |
| directories here.</p> |
| |
| <p>To recapitulate, a template and a data-model is needed for |
| FreeMarker to generate the output (like the HTML shown first):</p> |
| |
| <p><span class="marked-template">Template</span> + <span class="marked-data-model">data-model</span> = <span class="marked-output">output</span></p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_quickstart_datamodel">The data-model at a glance</h4> |
| |
| |
| <p>As you have seen, the data-model is basically a tree. This tree |
| can be arbitrarily complicated and deep, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model"><a name="example.qStart.dataModelWithHashes"></a>(root) |
| | |
| +- animals |
| | | |
| | +- mouse |
| | | | |
| | | +- size = "small" |
| | | | |
| | | +- price = 50 |
| | | |
| | +- elephant |
| | | | |
| | | +- size = "large" |
| | | | |
| | | +- price = 5000 |
| | | |
| | +- python |
| | | |
| | +- size = "medium" |
| | | |
| | +- price = 4999 |
| | |
| +- test = "It is a test" |
| | |
| +- whatnot |
| | |
| +- because = "don't know"</pre></div> |
| |
| <p>The variables that act as directories (the root, |
| <code class="inline-code">animals</code>, <code class="inline-code">mouse</code>, |
| <code class="inline-code">elephant</code>, <code class="inline-code">python</code>, |
| <code class="inline-code">whatnot</code>) are called <strong>hashes</strong>. Hashes store other variables (the so |
| called <a name="topic.dataModel.subVar"></a><em>subvariables</em>) |
| by a lookup name (e.g., "animals", "mouse" or "price").</p> |
| |
| <p>The variables that store a single value |
| (<code class="inline-code">size</code>, <code class="inline-code">price</code>, |
| <code class="inline-code">test</code> and <code class="inline-code">because</code>) are called |
| <strong>scalars</strong>.</p> |
| |
| <p><a name="topic.qStart.accessVariables"></a>When you want to |
| use a subvariable in a template, you specify its path from the root, |
| and separate the steps with dots. To access the |
| <code class="inline-code">price</code> of a <code class="inline-code">mouse</code>, you start from |
| the root and go into <code class="inline-code">animals</code>, and then go into |
| <code class="inline-code">mouse</code> then go into <code class="inline-code">price</code>. So you |
| write <code class="inline-code">animals.mouse.price</code>. When you put the special |
| <code class="inline-code">${<em class="code-color">...</em>}</code> codes around an |
| expression like this, you are telling FreeMarker to output the |
| corresponding text at that point.</p> |
| |
| <p>There is one more important kind of variable: <strong>sequences</strong>. They are similar to hashes, but they |
| don't store names for the variables they contain. Instead, they store |
| the subvariables sequentially, and you can access them with a |
| numerical index. For example, in this data-model, |
| <code class="inline-code">animals</code> and <code class="inline-code">whatnot.fruits</code> are |
| sequences:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model"><a name="example.qStart.dataModelWithSequences"></a>(root) |
| | |
| +- animals |
| | | |
| | +- (1st) |
| | | | |
| | | +- name = "mouse" |
| | | | |
| | | +- size = "small" |
| | | | |
| | | +- price = 50 |
| | | |
| | +- (2nd) |
| | | | |
| | | +- name = "elephant" |
| | | | |
| | | +- size = "large" |
| | | | |
| | | +- price = 5000 |
| | | |
| | +- (3rd) |
| | | |
| | +- name = "python" |
| | | |
| | +- size = "medium" |
| | | |
| | +- price = 4999 |
| | |
| +- whatnot |
| | |
| +- fruits |
| | |
| +- (1st) = "orange" |
| | |
| +- (2nd) = "banana"</pre></div> |
| |
| <p>To access a subvariable of a sequence you use a numerical index |
| in square brackets. Indexes start from 0 (it's a programmer tradition |
| to start with 0), thus the index of the first item is 0, the index of |
| the second item is 1, and so on. So to get the name of the first |
| animal you write <code class="inline-code">animals[0].name</code>. To get the second |
| item in <code class="inline-code">whatnot.fruits</code> (which is the string |
| <code class="inline-code">"banana"</code>) you write |
| <code class="inline-code">whatnot.fruits[1]</code>.</p> |
| |
| <p>Scalars can further divided into these categories:</p> |
| |
| <ul> |
| <li> |
| <p>String: Text, that is, an arbitrary sequence of characters |
| such as ''m'', ''o'', ''u'', ''s'', ''e'' above. For example the |
| <code class="inline-code">name</code>-s and <code class="inline-code">size</code>-s are |
| strings above.</p> |
| </li> |
| |
| <li> |
| <p>Number: It's a numerical value, like the |
| <code class="inline-code">price</code>-s above. The string |
| <code class="inline-code">"50"</code> and the number <code class="inline-code">50</code> are |
| two totally different things in FreeMarker. The former is just a |
| sequence of two characters (which happens to be readable as a |
| number for humans), while the latter is a numerical value that you |
| can use, say, in arithmetical calculations.</p> |
| </li> |
| |
| <li> |
| <p>Date/time: A date or time. Like the date an animal were |
| captured, or the time the shop opens.</p> |
| </li> |
| |
| <li> |
| <p>Boolean: A true/false (yes/no, on/off, etc.) thing. Like |
| animals could have a <code class="inline-code">protected</code> subvariable, |
| which store if the animal is protected or not.</p> |
| </li> |
| </ul> |
| |
| <p>Summary:</p> |
| |
| <ul> |
| <li> |
| <p>The data-model can be visualized as a tree.</p> |
| </li> |
| |
| <li> |
| <p>Scalars store a single value. The value can be a string or a |
| number or a date/time or a boolean.</p> |
| </li> |
| |
| <li> |
| <p>Hashes are containers that store other variables and |
| associate them with a unique lookup name.</p> |
| </li> |
| |
| <li> |
| <p>Sequences are containers that store other variables in an |
| ordered sequence. The stored variables can be retrieved via their |
| numerical index, starting from 0.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_quickstart_template">The template at a glance</h4> |
| |
| |
| <p>The simplest template is a plain HTML file (or whatever text |
| file -- FreeMarker is not confined to HTML). When the client visits |
| that page, FreeMarker will send that HTML to the client as is. However |
| if you want that page to be more dynamic then you begin to put special |
| parts into the HTML which will be understood by FreeMarker:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">${<em class="code-color">...</em>}</code>: |
| FreeMarker will replace it in the output with the actual value of |
| the thing inside the curly brackets. They are called <strong>interpolation</strong>s. As an example see <a href="#example.first">the very first example</a>.</p> |
| </li> |
| |
| <li> |
| <p><strong>FTL tags</strong> (for FreeMarker |
| Template Language tags): FTL tags are a bit similar to HTML tags, |
| but they are instructions to FreeMarker and will not be printed to |
| the output. The name of these tags start with |
| <code class="inline-code">#</code>. (User-defined FTL tags use |
| <code class="inline-code">@</code> instead of <code class="inline-code">#</code>, but they are |
| an advanced topic.)</p> |
| </li> |
| |
| <li> |
| <p><strong>Comments:</strong> Comments are |
| similar to HTML comments, but they are delimited by |
| <code class="inline-code"><#--</code> and <code class="inline-code">--></code>. Anything |
| between these delimiters and the delimiter itself will be ignored |
| by FreeMarker, and will not be written to the output.</p> |
| </li> |
| </ul> |
| |
| <p>Anything not an FTL tag or an interpolation or comment is |
| considered as static text, and will not be interpreted by FreeMarker; |
| it is just printed to the output as is.</p> |
| |
| <p>With FTL tags you refer to so-called <strong>directives</strong>. This is the same kind of |
| relationship as between HTML tags (e.g.: |
| <code class="inline-code"><table></code> and |
| <code class="inline-code"></table></code>) and HTML elements (e.g., the |
| <code class="inline-code">table</code> element) to which you refer to with the HTML |
| tags. (If you don't feel this difference then just take "FTL tag" and |
| "directive" as synonyms.)</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_7">Examples of directives</h5> |
| |
| |
| <p>Though FreeMarker has far more directives, in this quick |
| overview we will only look at three of the most commonly used |
| ones.</p> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_8">The if directive</h6> |
| |
| |
| <p>With the <code class="inline-code">if</code> directive you can |
| conditionally skip a section of the template. For example, assume |
| that in the <a href="#example.first">very first |
| example</a> you want to greet your boss, Big Joe, differently |
| from other users:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><html> |
| <head> |
| <title>Welcome!</title> |
| </head> |
| <body> |
| <h1> |
| Welcome ${user}<strong><#if user == "Big Joe"></strong>, our beloved leader<strong></#if></strong>! |
| </h1> |
| <p>Our latest product: |
| <a href="${latestProduct.url}">${latestProduct.name}</a>! |
| </body> |
| </html></pre></div> |
| |
| <p>Here you have told FreeMarker that the '', our beloved |
| leader'' should be there only if the value of the variable |
| <code class="inline-code">user</code> is equal to the string <code class="inline-code">"Big |
| Joe"</code>. In general, things between <code class="inline-code"><#if |
| <em class="code-color">condition</em>></code> and |
| <code class="inline-code"></#if></code> tags are skipped if |
| <code class="inline-code"><em class="code-color">condition</em></code> is false |
| (the boolean value).</p> |
| |
| <p>Let's detail the |
| <code class="inline-code"><em class="code-color">condition</em></code> used here: |
| The <code class="inline-code">==</code> is an operator that tests if the values |
| at its left and right side are equivalent, and the results is a |
| boolean value, true or false accordingly. On the left side of |
| <code class="inline-code">==</code> I have <a href="#topic.qStart.accessVariables">referenced a |
| variable</a> with the syntax that should be already familiar; |
| this will be replaced with the value of the variable. In general, |
| unquoted words inside directives or interpolations are treated as |
| references to variables. On the right side I have specified a |
| literal string. Literal strings in templates must |
| <em>always</em> be put inside quotation marks.</p> |
| |
| <p>This will print "Pythons are free today!" if their price is |
| 0:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if animals.python.price == <strong>0</strong>> |
| Pythons are free today! |
| </#if></pre></div> |
| |
| <p>Similarly as earlier when a string was specified directly, |
| here a number is specified directly (<code class="inline-code">0</code>). Note |
| that the number is <em>not</em> quoted. If you quoted |
| it (<code class="inline-code">"0"</code>), FreeMarker were misinterpret it as a |
| string literal.</p> |
| |
| <p>This will print "Pythons are not free today!" if their price |
| is not 0:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if animals.python.price <strong>!=</strong> 0> |
| Pythons are not free today! |
| </#if></pre></div> |
| |
| <p>As you may have guessed, <code class="inline-code">!=</code> means not |
| equivalent.</p> |
| |
| <p>You can write things like this too (using <a href="#example.qStart.dataModelWithHashes">the data-model used |
| to demonstrate hashes</a>):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if <strong>animals.python.price < animals.elephant.price</strong>> |
| Pythons are cheaper than elephants today. |
| </#if></pre></div> |
| |
| <p>With the <code class="inline-code"><#else></code> tag you can |
| specify what to do if the condition is false. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if animals.python.price < animals.elephant.price> |
| Pythons are cheaper than elephants today. |
| <strong><#else></strong> |
| Pythons are not cheaper than elephants today. |
| </#if></pre></div> |
| |
| <p>This prints ''Pythons are cheaper than elephants today.'' if |
| the price of python is less than the price of elephant, or else it |
| prints ''Pythons are not cheaper than elephants today.''</p> |
| |
| <p>If you have a variable with boolean value (a true/false |
| thing) then you can use it directly as the |
| <code class="inline-code"><em class="code-color">condition</em></code> of |
| <code class="inline-code">if</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if animals.python.protected> |
| Warning! Pythons are protected animals! |
| </#if></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_9">The list directive</h6> |
| |
| |
| <p>This is useful when you want to list something. For example |
| if you merge this template with the <a href="#example.qStart.dataModelWithSequences">data-model I used |
| earlier to demonstrate sequences</a>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><p>We have these animals: |
| <table border=1> |
| <tr><th>Name<th>Price |
| <strong><#list animals as being></strong> |
| <tr><td>${<strong>being</strong>.name}<td>${<strong>being</strong>.price} Euros |
| <strong></#list></strong> |
| </table></pre></div> |
| |
| <p>then the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><p>We have these animals: |
| <table border=1> |
| <tr><th>Name<th>Price |
| <strong><tr><td>mouse<td>50 Euros |
| <tr><td>elephant<td>5000 Euros |
| <tr><td>python<td>4999 Euros</strong> |
| </table></pre></div> |
| |
| <p>The generic format of the <code class="inline-code">list</code> directive |
| is:</p> |
| |
| <p><code class="inline-code"><#list <em class="code-color">sequence</em> as |
| <em class="code-color">loopVariable</em>><em class="code-color">repeatThis</em></#list></code></p> |
| |
| <p>The <code class="inline-code"><em class="code-color">repeatThis</em></code> |
| part will be repeated for each item in the sequence that you have |
| given with <code class="inline-code"><em class="code-color">sequence</em></code>, |
| one after the other, starting from the first item. In all |
| repetitions |
| <code class="inline-code"><em class="code-color">loopVariable</em></code> will |
| hold the value of the current item. This variable exists only |
| between the <code class="inline-code"><#list ...></code> and |
| <code class="inline-code"></#list></code> tags.</p> |
| |
| <p>As another example, we list the fruits of that example data |
| model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><p>And BTW we have these fruits: |
| <ul> |
| <strong><#list whatnot.fruits as fruit></strong> |
| <li>${fruit} |
| <strong></#list></strong> |
| <ul></pre></div> |
| |
| <p>The <code class="inline-code">whatnot.fruits</code> expression should be |
| familiar to you; it <a href="#topic.qStart.accessVariables">references a variable in |
| the data-model</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_10">The include directive</h6> |
| |
| |
| <p>With the <code class="inline-code">include</code> directive you can insert |
| the content of another file into the template.</p> |
| |
| <p>Suppose you have to show the same copyright notice on |
| several pages. You can create a file that contains the copyright |
| notice only, and insert that file everywhere where you need that |
| copyright notice. Say, you store this copyright notice in |
| <code class="inline-code">copyright_footer.html</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><hr> |
| <i> |
| Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>, |
| <br> |
| All Rights Reserved. |
| </i></pre></div> |
| |
| <p>Whenever you need that file you simply insert it with the |
| <code class="inline-code">include</code> directive:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><html> |
| <head> |
| <title>Test page</title> |
| </head> |
| <body> |
| <h1>Test page</h1> |
| <p>Blah blah... |
| <strong><#include "/copyright_footer.html"></strong> |
| </body> |
| </html></pre></div> |
| |
| <p>and the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><html> |
| <head> |
| <title>Test page</title> |
| </head> |
| <body> |
| <h1>Test page</h1> |
| <p>Blah blah... |
| <strong><hr> |
| <i> |
| Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>, |
| <br> |
| All Rights Reserved. |
| </i></strong> |
| </body> |
| </html></pre></div> |
| |
| <p>If you change the <code class="inline-code">copyright_footer.html</code>, |
| then the visitor will see the new copyright notice on all |
| pages.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_11">Using directives together</h5> |
| |
| |
| <p>You can use directives as many times on a page as you want, |
| and you can nest directives into each other similarly as you can |
| nest HTML elements into each other. For example this will list the |
| animals and print the name of large animals with bigger font:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><p>We have these animals: |
| <table border=1> |
| <tr><th>Name<th>Price |
| <strong><#list animals as being></strong> |
| <tr> |
| <td> |
| <strong><#if being.size == "large"></strong><font size="+1"><strong></#if></strong> |
| ${being.name} |
| <strong><#if being.size == "large"></strong></font><strong></#if></strong> |
| <td>${being.price} Euros |
| <strong></#list></strong> |
| </table></pre></div> |
| |
| <p>Note that since FreeMarker does not interpret text outside FTL |
| tags, interpolations and comments, it doesn't see the above |
| <code class="inline-code">font</code> tags as badly nested ones.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_12">Dealing with missing variables</h5> |
| |
| |
| <p>In practice the data-model often has variables that are |
| optional (i.e., sometimes missing). To spot some typical human |
| mistakes, FreeMarker doesn't tolerate the referring to missing |
| variables unless you tell them explicitly what to do if the variable |
| is missing. Here we will show the two most typical ways of doing |
| that.</p> |
| |
| <p><span class="marked-for-programmers">Note for programmers: A |
| non-existent variable and a variable with <code class="inline-code">null</code> |
| value is the same for FreeMarker, so the "missing" term used here |
| covers both cases.</span></p> |
| |
| <p>Wherever you refer to a variable, you can specify a default |
| value for the case the variable is missing, by followin the variable |
| name with a <code class="inline-code">!</code> and the default value. Like in the |
| following example, when <code class="inline-code">user</code> is missing from data |
| model, the template will behave like if <code class="inline-code">user</code>'s |
| value were the string <code class="inline-code">"Anonymous"</code>. (When |
| <code class="inline-code">user</code> isn't missing, this template behaves exactly |
| like if <code class="inline-code">!"Anonymous"</code> were not there):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><h1>Welcome ${user<strong>!"Anonymous"</strong>}!</h1></pre></div> |
| |
| <p>You can ask whether a variable isn't missing by putting |
| <code class="inline-code">??</code> after its name. Combining this with the |
| already introduced <code class="inline-code">if</code> directive you can skip the |
| whole greeting if the <code class="inline-code">user</code> variable is |
| missing:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if <strong>user??</strong>><h1>Welcome ${user}!</h1></#if></pre></div> |
| |
| <p>Regarding variable accessing with multiple steps, like |
| <code class="inline-code">animals.python.price</code>, writing |
| <code class="inline-code">animals.python.price!0</code> is correct only if |
| <code class="inline-code">animals.python</code> is never missing and only the last |
| subvariable, <code class="inline-code">price</code>, is possibly missing (in which |
| case here we assume it's <code class="inline-code">0</code>). If |
| <code class="inline-code">animals</code> or <code class="inline-code">python</code> is missing, |
| the template processing will stop with an "undefined variable" |
| error. To prevent that, you have to write |
| <code class="inline-code">(animals.python.price)!0</code>. In that case the |
| expression will be <code class="inline-code">0</code> even if |
| <code class="inline-code">animals</code> or <code class="inline-code">python</code> is missing. |
| Same logic goes for <code class="inline-code">??</code>; |
| <code class="inline-code">animals.python.price??</code> versus |
| <code class="inline-code">(animals.python.price)??</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="dgui_datamodel">Values, Types</h3> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_datamodel_basics">Basics</h4> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>It is assumed that you have already read the <a href="#dgui_quickstart">Getting Started</a> chapter.</p> |
| </div> |
| |
| |
| <p>Understanding the concept of values and types is crucial for the |
| understanding of data-models. However, the concept of values and types |
| is not confined to data-models, as you will see.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="topic.value">What is a value?</h5> |
| |
| |
| |
| |
| <p><span class="marked-for-programmers">Real programmers can safely skip |
| this section.</span></p> |
| |
| <p>Examples of <em>values</em> as you know the term |
| from the everyday math are 16, 0.5, and so on, i.e. numbers. In the |
| case of computer languages the value term has a wider meaning, as a |
| value needn't be a number. For example, take this data-model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model"><a name="example.stdDataModel"></a>(root) |
| | |
| +- user = "Big Joe" |
| | |
| +- today = Jul 6, 2007 |
| | |
| +- todayHoliday = false |
| | |
| +- lotteryNumbers |
| | | |
| | +- (1st) = 20 |
| | | |
| | +- (2st) = 14 |
| | | |
| | +- (3rd) = 42 |
| | | |
| | +- (4th) = 8 |
| | | |
| | +- (5th) = 15 |
| | |
| +- cargo |
| | |
| +- name = "coal" |
| | |
| +- weight = 40</pre></div> |
| |
| <p>We say that the <em>value</em> of the the |
| <code class="inline-code">user</code> variable is "Big Joe" (a string), the |
| <em>value</em> of <code class="inline-code">today</code> is Jul 6, |
| 2007 (a date), the <em>value</em> of |
| <code class="inline-code">todayHoliday</code> is false (a boolean, ie. a yes/no |
| thing). The <em>value</em> of |
| <code class="inline-code">lotteryNumbers</code> is the sequence that contains 20, |
| 14, 42, 8, 15. Surely <code class="inline-code">lotteryNumbers</code> is multiple |
| values in the sense that it <em>contains</em> multiple |
| values (for example, the 2nd item in it is a the |
| <em>value</em> 14), but still, |
| <code class="inline-code">lotteryNumbers</code> itself is a single value. It's |
| like a box that contains many other items; the whole box can be seen |
| as a single item. Last not least we also have the |
| <em>value</em> of <code class="inline-code">cargo</code>, which is a |
| hash (a box-like thing again).So, a value is something that can be |
| stored in a variable (e.g., in <code class="inline-code">user</code> or |
| <code class="inline-code">cargo</code> or <code class="inline-code">cargo.name</code>). But a |
| value need not be stored in a variable to be called a value, for |
| example we have the value 100 here:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if cargo.weight < <strong>100</strong>>Light cargo</#if></pre></div> |
| |
| <p>Or the temporaly result of a calculations are also called |
| values, like 20 and 120 when this template is executed (it will |
| print 120):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${cargo.weight / 2 + 100}</pre></div> |
| |
| <p>Explanation for this last: As the result of dividing the two |
| values, 40 (the weight of the cargo) and 2, a new value 20 is |
| created. Then 100 is addted to it, so the value 120 is created. Then |
| 120 is printed |
| (<code class="inline-code">${<em class="code-color">...</em>}</code>), and the |
| template execution goes on and all these values gone.</p> |
| |
| <p>Certainly now you feel what the value term means.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_13">What is type?</h5> |
| |
| |
| <p>Values have an important aspect, their type. For example the |
| type of the value of the <code class="inline-code">user</code> variable is string, |
| and the type of the value of the <code class="inline-code">lotteryNumbers</code> |
| variable is sequence. The type of a value is important because it |
| determines to a large extent how and where you can use the value. |
| Like <code class="inline-code">${user / 2}</code> is an error, but |
| <code class="inline-code">${cargo.weight / 2}</code> works and prints 20, since |
| division only does make sense for a number, but not for a string. |
| Or, using dot like in <code class="inline-code">cargo.name</code> does make sense |
| only if <code class="inline-code">cargo</code> is a hash. Or, you can list with |
| <code class="inline-code"><#list <em class="code-color">...</em>></code> |
| sequences only. Or, the condition of <code class="inline-code"><#if |
| ...></code> must be a boolean. And so on.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>A little terminology... Saying "a boolean" or "a boolean |
| value" or "a value of type boolean" are all the same.</p> |
| </div> |
| |
| |
| <p><a name="topic.multitype"></a>A value can have multiple types at the same time, |
| although it's rarely utilized. For example in the data-model below |
| <code class="inline-code">mouse</code> is both a string and a hash:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- mouse = "Yerri" |
| | |
| +- age = 12 |
| | |
| +- color = "brown"</pre></div> |
| |
| <p>If you merge this template with the above data-model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${mouse} <#-- uses mouse as a string --> |
| ${mouse.age} <#-- uses mouse as a hash --> |
| ${mouse.color} <#-- uses mouse as a hash --></pre></div> |
| |
| <p>the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Yerri |
| 12 |
| brown</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_14">The data-model is a hash</h5> |
| |
| |
| <p>Looking at the various data-model examples you may already |
| realized: the thing marked as "(root)" is just a value of type hash. |
| When you write something like <code class="inline-code">user</code>, that means |
| that you want the "user" variable stored in the root hash. Like if |
| you were writing <code class="inline-code">root.user</code>, except that there is |
| no variable called "root" so that wouldn't work.</p> |
| |
| <p>Some may get confused by the fact that our example data-model, |
| that is, the root hash, contains further hashes and sequences |
| (<code class="inline-code">lotteryNumbers</code> and <code class="inline-code">cargo</code>). |
| There is nothing special in that. A hash contains other variables, |
| and those variables have a value, which can be a string, a number, |
| etc., and of course it can be a hash or sequence as well. Because, |
| as it was explained earlier, a sequence or a hash is just a value, |
| like a string or a number is.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_datamodel_types">The types</h4> |
| |
| |
| <p>The suppored types are:</p> |
| |
| <ul> |
| <li> |
| <a href="#dgui_datamodel_scalar">Scalars:</a> |
| |
| <ul> |
| <li> |
| String |
| </li> |
| |
| <li> |
| Number |
| </li> |
| |
| <li> |
| Boolean |
| </li> |
| |
| <li> |
| Date |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_datamodel_container">Containers:</a> |
| |
| <ul> |
| <li> |
| Hash |
| </li> |
| |
| <li> |
| Sequence |
| </li> |
| |
| <li> |
| Collection |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| Subroutines: |
| |
| <ul> |
| <li> |
| <a href="#dgui_datamodel_method">Methods and |
| functions</a> |
| </li> |
| |
| <li> |
| <a href="#dgui_datamodel_userdefdir">User-defined |
| directives</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| Miscellaneous/seldom used: |
| |
| <ul> |
| <li> |
| <a href="#dgui_datamodel_node">Node</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_datamodel_scalar">Scalars</h5> |
| |
| |
| <a name="topic.designer.scalarVariable"></a> |
| |
| <p>These are the basic, simple kind of values. They can |
| be:</p> |
| |
| <ul> |
| <li> |
| <p>String: It is simple text, e.g., the name of a |
| product.</p> |
| |
| <p>If you want to give a string value directly in the |
| template, rather than use a variable that comes from the data |
| model, you write the text between quotation marks, e.g., |
| <code class="inline-code">"green mouse"</code> or <code class="inline-code">'green |
| mouse'</code>. (More details regarding the syntax can be |
| found <a href="#dgui_template_exp_direct_string">later</a>.)</p> |
| </li> |
| |
| <li> |
| <p>Number: For example the price of a product. |
| <span class="marked-for-programmers">Whole numbers and non-whole |
| numbers are not distinguished; there is only a single number |
| type. So for example 3/2 will be always 1.5, and never 1. Just |
| like if you are using a calculator.</span></p> |
| |
| <p>If you want to give a numerical value directly in the |
| template, then you write for example: <code class="inline-code">150</code> or |
| <code class="inline-code">-90.05</code> or <code class="inline-code">0.001</code>. (More |
| details regarding the syntax can be found <a href="#dgui_template_exp_direct_number">later</a>.)</p> |
| </li> |
| |
| <li> |
| <p>Boolean: A boolean value represents a logical true |
| or false (yes or no). For example, if a the visitor has been |
| logged in or not. Typically you use booleans as the condition of |
| the <code class="inline-code">if</code> directive, like <code class="inline-code"><#if |
| loggedIn |
| ><em class="code-color">...</em></#if></code> or |
| <code class="inline-code"><#if price == |
| 0><em class="code-color">...</em></#if></code>; in |
| the last case the result of the <code class="inline-code">price == 0</code> |
| part is a boolean value.</p> |
| |
| <p>In the templates you can directly specify a boolean with |
| the reserved words <code class="inline-code">true</code> and |
| <code class="inline-code">false</code>.</p> |
| </li> |
| |
| <li> |
| <p>Date: A date variable stores date/time related |
| data. It has three variations:</p> |
| |
| <ul> |
| <li> |
| <p>A date with day precision (often referred simply as |
| "date") as April 4, 2003</p> |
| </li> |
| |
| <li> |
| <p>Time of day (without the date part), as 10:19:18 PM. |
| Time is stored with millisecond precision.</p> |
| </li> |
| |
| <li> |
| <p>Date-time (sometimes called "time stamp") as April 4, |
| 2003 10:19:18 PM. The time part is stored with millisecond |
| precision.</p> |
| </li> |
| </ul> |
| |
| <p>Unfortunately, because of the limitations of the Java |
| platform, FreeMarker sometimes can't decide which parts of the |
| date are in use (i.e., if it is date-time, or a time of day, |
| etc.). The solution for this problem is an advanced topic that |
| will be discussed <a href="#ref_builtin_date_datetype">later</a>.</p> |
| |
| <p>It is possible to define date values directly in |
| templates, but this is an advanced topic that will be explained |
| <a href="#ref_builtin_string_date">later</a>.</p> |
| </li> |
| </ul> |
| |
| <p>Bear in mind that FreeMarker distinguishes strings from |
| numbers and booleans, so the string <code class="inline-code">"150"</code> and the |
| number <code class="inline-code">150</code> are totally different. A number holds |
| a numerical value. A boolean holds a logical true or false. A string |
| holds an arbitrary sequence of characters.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_datamodel_container">Containers</h5> |
| |
| |
| |
| |
| <p>These are the values whose purpose is to contain other |
| variables; they are just containers. The contained variables are |
| often referred as <em>subvariables</em>. The container |
| types are:</p> |
| |
| <ul> |
| <li> |
| <p>Hash: Associates a unique lookup name with each of |
| its subvariables. The name is an unrestricted string. A hash |
| <em>doesn't define an ordering</em> for the |
| subvariables in it. That is, there is no such thing as the first |
| subvariable, and the second subvariable, etc.; the variables are |
| just accessed by name.</p> |
| </li> |
| |
| <li> |
| <p>Sequence: Associates an integer number with each |
| of its subvariables. The first subvariable is associated with 0, |
| the second with 1, the third to 2, and so on; the subvariables |
| are ordered. These numbers are often called the |
| <em>indexes</em> of the subvariables. Sequences are |
| usually dense, i.e., all indexes up to the index of the last |
| subvariable have an associated subvariable, but it's not |
| strictly necessary. The type of the subvariable values need not |
| be the same.</p> |
| </li> |
| |
| <li> |
| <p>Collection: A collection, from the viewpoint of |
| the template author, is a restricted sequence. You cannot access |
| its size or retrieve its subvariables by index, but they can be |
| still listed with the <a href="#ref.directive.list"><code>list</code> |
| directive</a>.</p> |
| </li> |
| </ul> |
| |
| <p>Note that since <a href="#topic.multitype">a value can |
| have multiple types</a>, it is possible for a value to be both a |
| hash and a sequence, in which case it would support index-based |
| access as well as access by lookup name. However, typically a |
| container will be either a hash or a sequence, not both.</p> |
| |
| <p>As the value of the variables stored in hashes and sequences |
| (and collections) can be anything, it can be a hash or sequence (or |
| collection) as well. This way you can build arbitrarily deep |
| structures.</p> |
| |
| <p>The data-model itself (or better said the root of it) is a |
| hash.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_15">Subroutines</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_datamodel_method">Methods and functions</h6> |
| |
| |
| <a name="topic.designer.methodVariable"></a> |
| |
| |
| |
| <p>A value that is a method or a function is used to calculate |
| another value, influenced by the parameters you give to it.</p> |
| |
| <p><span class="marked-for-programmers">For programmer types: |
| Methods/functions are first-class values, just like in functional |
| programming languages. This means that functions/methods can be |
| the parameters or return values of other functions/methods, you |
| can assign them to variables, and so on.</span></p> |
| |
| <p>Suppose that programmers have put the method variable |
| <code class="inline-code">avg</code> in the data-model that can be used to |
| calculate the average of numbers. If you give the 3 and 5 as |
| parameters when you access <code class="inline-code">avg</code>, then you get |
| the value 4.</p> |
| |
| <p>The usage of methods will be explained <a href="#dgui_template_exp_methodcall">later</a>, but perhaps |
| this example helps to understand what methods are:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">The average of 3 and 5 is: ${avg(3, 5)} |
| The average of 6 and 10 and 20 is: ${avg(6, 10, 20)} |
| The average of the price of a python and an elephant is: |
| ${avg(animals.python.price, animals.elephant.price)}</pre></div> |
| |
| <p>this will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">The average of 3 and 5 is: 4 |
| The average of 6 and 10 and 20 is: 12 |
| The average of the price of a python and an elephant is: |
| 4999.5</pre></div> |
| |
| <p>What is the difference between a method and a function? As |
| far as the template author is concerned, nothing. Well not really |
| nothing, as methods typically come from the data-model (<span class="marked-for-programmers">as they reflect the methods of Java |
| objects</span>), and functions are defined in templates (with |
| the <a href="#ref.directive.function"><code>function</code> |
| directive</a> -- an advanced topic), but both can be used on |
| the same way.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_datamodel_userdefdir">User-defined directives</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>A value of this type can be used as user-defined directive |
| (with other words, as FreeMarker tag). An user-defined directive |
| is a subroutine, something like a little reusable template |
| fragment. But this is an advanced topic that will be explained |
| <a href="#dgui_misc_userdefdir">later</a> in its own |
| chapter.</p> |
| |
| <p><span class="marked-for-programmers">For programmer types: |
| user-defined directives (such as macros), are first-class values |
| too, just like functions/methods are.</span></p> |
| |
| <p>Just to get an idea about user-defined directives (so just |
| ignore this if you won't understand), assume we have a variable, |
| <code class="inline-code">box</code>, whose value is a user-defined directive |
| that prints some kind of fancy HTML message box with a title bar |
| and a message in it. The <code class="inline-code">box</code> variable could be |
| used in the template like this (for example):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@<strong>box</strong> title="Attention!"> |
| Too much copy-pasting may leads to |
| maintenance headaches. |
| </@<strong>box</strong>></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_16">Function/method versus user-defined directive</h6> |
| |
| |
| <p>This is for advanced users again (so ignore it if you don't |
| understand). It's a frequent dilemma if you should use a |
| function/method or an user-defined directive to implement |
| something. The rule of thumb is: Implement the facility as |
| user-defined directive instead of as function/method if:</p> |
| |
| <ul> |
| <li> |
| <p>... the output (the return value) is markup (HTML, XML, |
| etc.). The main reason is that the result of functions are |
| subject to automatic XML-escaping (due to the nature of |
| <code class="inline-code">${<em class="code-color">...</em>}</code>), while |
| the output of user-defined directives are not (due to the |
| nature of |
| <code class="inline-code"><@<em class="code-color">...</em>></code>; |
| its output is assumed to be markup, and hence already |
| escaped).</p> |
| </li> |
| |
| <li> |
| <p>... it's the side-effect that is important and not the |
| return value. For example, a directive whose purpose is to add |
| an entry to the server log is like that. (In fact you can't |
| have a return value for a user-defined directive, but some |
| kind of feedback is still possible by setting non-local |
| variables.)</p> |
| </li> |
| |
| <li> |
| <p>... it will do flow control (like for example |
| <code class="inline-code">list</code> or <code class="inline-code">if</code> directives |
| do). You just can't do that with a function/method |
| anyway.</p> |
| </li> |
| </ul> |
| |
| <p>The Java methods of FreeMarker-unaware Java objects are |
| normally visible as methods in templates, regardless of the nature |
| of the Java method. That said, you have no choice there.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_17">Miscellaneous</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_datamodel_node">Nodes</h6> |
| |
| |
| |
| |
| <p>Node variables represent a node in a tree structure, and are |
| used mostly with <a href="#xgui">XML processing</a>, which |
| is an advanced, and specialized topic.</p> |
| |
| <p>Still, a quick overview <em>for advanced |
| users</em>: A node is similar to a sequence that stores |
| other nodes, which are often referred as the children nodes. A |
| node stores a reference to its container node, which is often |
| referred as the parent node. The main point of being a node is the |
| topological information; other data must be stored by utilizing |
| that a value can have multiple types. Like, a value may be both a |
| node and a number, in which case it can store a number as the |
| "pay-load". Apart from the topological information, a node can |
| store some metainformation as well: a node name, a node type |
| (string), and a node namespace (string). For example, if the node |
| symbolizes a <code class="inline-code">h1</code> element in an XHTML document, |
| then its name could be <code class="inline-code">"h1"</code>, it's node type |
| could be <code class="inline-code">"element"</code>, and it's namespace could be |
| <code class="inline-code">"http://www.w3.org/1999/xhtml"</code>. But it's up to |
| the designer of the data-model if what meaning these |
| metainformations have, and if they are used at all. The way of |
| retrieving the topological and metainformations is described <a href="#ref_builtins_node">in a later chapter</a> (that you |
| don't have to understand at this point).</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="dgui_template">The Template</h3> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>It is assumed that you have already read the <a href="#dgui_quickstart">Getting Started</a> and the <a href="#dgui_datamodel">Values, Types</a> |
| chapter.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_template_overallstructure">Overall structure</h4> |
| |
| |
| <p>Templates are in fact programs you write in a language called |
| <strong>FTL</strong> (for FreeMarker |
| Template Language). This is a quite simple programming language |
| designed for writing templates and nothing else.</p> |
| |
| <p>A template (= FTL program) is a mix of the following |
| sections:</p> |
| |
| <ul> |
| <li> |
| <p><strong>Text</strong>: Text that will be printed to the output as |
| is.</p> |
| </li> |
| |
| <li> |
| <p><strong>Interpolation</strong>: These sections will be replaced with a calculated |
| value in the output. Interpolations are delimited by |
| <code class="inline-code">${</code> and <code class="inline-code">}</code> (or with |
| <code class="inline-code">#{</code> and <code class="inline-code">}</code>, but that shouldn't |
| be used anymore; <a href="#ref_depr_numerical_interpolation">see more |
| here</a>).</p> |
| </li> |
| |
| <li> |
| <p><strong>FTL tags</strong>: FTL tags are a bit similar to HTML tags, but they |
| are instructions to FreeMarker and will not be printed to the |
| output.</p> |
| </li> |
| |
| <li> |
| <p><strong>Comments</strong>: Comments are similar to HTML comments, but they |
| are delimited by <code class="inline-code"><#--</code> and |
| <code class="inline-code">--></code>. Comments will be ignored by FreeMarker, |
| and will not be written to the output.</p> |
| </li> |
| </ul> |
| |
| <p>Let's see a concrete template. I have marked the template's |
| components with colors: <span class="marked-text">text</span>, |
| <span class="marked-interpolation">interpolation</span>, <span class="marked-ftl-tag">FTL tag</span>, <span class="marked-comment">comment</span>. With the <em><span class="marked-invisible-text">[BR]</span></em>-s I intend to visualize the |
| <a href="#gloss.lineBreak">line breaks</a>.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><html><em><span class="marked-invisible-text">[BR]</span></em> |
| <head><em><span class="marked-invisible-text">[BR]</span></em> |
| <title>Welcome!</title><em><span class="marked-invisible-text">[BR]</span></em> |
| </head><em><span class="marked-invisible-text">[BR]</span></em> |
| <body><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-comment"><#-- Greet the user with his/her name --></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <h1>Welcome <span class="marked-interpolation">${user}</span>!</h1><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>We have these animals:<em><span class="marked-invisible-text">[BR]</span></em> |
| <ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#list animals as being></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <li><span class="marked-interpolation">${being.name}</span> for <span class="marked-interpolation">${being.price}</span> Euros<em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"></#list></span><em><span class="marked-invisible-text">[BR]</span></em> |
| </ul><em><span class="marked-invisible-text">[BR]</span></em> |
| </body><em><span class="marked-invisible-text">[BR]</span></em> |
| </html></span></pre></div> |
| |
| <p>FTL distinguishes upper case and lower case letters. So |
| <code class="inline-code">list</code> is good directive name, while |
| <code class="inline-code">List</code> is not. Similarly <code class="inline-code">${name}</code> |
| is not the same as <code class="inline-code">${Name}</code> or |
| <code class="inline-code">${NAME}</code></p> |
| |
| <p>It is important to realize that <span class="marked-interpolation">interpolations</span> can be used in |
| <span class="marked-text">text</span> (and in string literal |
| expressions; see <a href="#dgui_template_exp_stringop_interpolation">later</a>) |
| only.</p> |
| |
| <p>An <span class="marked-ftl-tag">FTL tag</span> can't be inside |
| another <span class="marked-ftl-tag">FTL tag</span> nor inside an |
| <span class="marked-interpolation">interpolation</span>. For example |
| this is <em>WRONG</em>: <code class="inline-code"><#if <#include |
| 'foo'>='bar'>...</#if></code></p> |
| |
| <p><span class="marked-comment">Comments</span> can be placed |
| inside <span class="marked-ftl-tag">FTL tags</span> and <span class="marked-interpolation">interpolations</span>. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><h1>Welcome <span class="marked-interpolation">${user <span class="marked-comment"><#-- The name of user --></span>}</span>!</h1><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>We have these animals:<em><span class="marked-invisible-text">[BR]</span></em> |
| <ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#list <span class="marked-comment"><#-- some comment... --></span> animals as <span class="marked-comment"><#-- again... --></span> being></span><em><span class="marked-invisible-text">[BR]</span></em></span> |
| <em>...</em></pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>For those of you who have tried the above examples: You may |
| notice that some of spaces, tabs and line breaks are missing from |
| the template output, even though we said that <span class="marked-text">text</span> is printed as is. Don't bother with |
| it now. This is because the feature called ''white-space stripping'' |
| is turned on, and that automatically removes some superfluous |
| spaces, tabs and line breaks. This will be explained <a href="#dgui_misc_whitespace">later</a>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_template_directives">Directives</h4> |
| |
| |
| |
| |
| |
| |
| <a name="term.designer.directive"></a> |
| |
| |
| |
| <p>You use FTL tags to call <strong>directives</strong>. In the example you have called the |
| <code class="inline-code">list</code> directive. Syntactically you have done it with |
| two tags: <code class="inline-code"><#list animals as being></code> and |
| <code class="inline-code"></#list></code>.</p> |
| |
| <p>There are two kind of FTL tags:</p> |
| |
| <ul> |
| <li> |
| <p>Start-tag: |
| <code class="inline-code"><#<em class="code-color">directivename</em> |
| <em class="code-color">parameters</em>></code></p> |
| </li> |
| |
| <li> |
| <p>End-tag: |
| <code class="inline-code"></#<em class="code-color">directivename</em>></code></p> |
| </li> |
| </ul> |
| |
| <p>This is similar to HTML or XML syntax, except that the tag name |
| starts with <code class="inline-code">#</code>. If the directive doesn't have nested |
| content (content between the start-tag and the end-tag), you must use |
| the start-tag with no end-tag. For example you write <code class="inline-code"><#if |
| <em class="code-color">something</em>><em class="code-color">...</em></#if></code>, |
| but just <code class="inline-code"><#include |
| <em class="code-color">something</em>></code> as FreeMarker knows |
| that the <code class="inline-code">include</code> directive can't have nested |
| content.</p> |
| |
| <p>The format of the |
| <code class="inline-code"><em class="code-color">parameters</em></code> depends on |
| the |
| <code class="inline-code"><em class="code-color">directivename</em></code>.</p> |
| |
| <p>In fact there are two types of directives: <a href="#gloss.predefinedDirective">predefined directives</a> and |
| <a href="#gloss.userDefinedDirective">user-defined |
| directives</a>. For user-defined directives you use |
| <code class="inline-code">@</code> instead of <code class="inline-code">#</code>, for example |
| <code class="inline-code"><@mydirective |
| <em class="code-color">parameters</em>><em class="code-color">...</em></@mydirective></code>. |
| Further difference is that if the directive has no nested content, you |
| must use a tag like <code class="inline-code"><@mydirective |
| <em class="code-color">parameters</em> /></code>, similarly as in |
| XML (e.g. <code class="inline-code"><img <em class="code-color">...</em> |
| /></code>). But user-defined directives is an advanced topic |
| that will be discussed <a href="#dgui_misc_userdefdir">later</a>.</p> |
| |
| <p>FTL tags, like HTML tags, must be properly nested. So the code |
| below is wrong, as the <code class="inline-code">if</code> directive is both inside |
| and outside of the nested content of the <code class="inline-code">list</code> |
| directive:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><ul> |
| <strong><#list animals as being></strong> |
| <li>${being.name} for ${being.price} Euros |
| <strong><#if user == "Big Joe"></strong> |
| (except for you) |
| <strong></#list></strong> <#-- WRONG! The "if" has to be closed first. --> |
| <strong></#if></strong> |
| </ul></pre></div> |
| |
| <p>Note that FreeMarker doesn't care about the nesting of HTML |
| tags, only about the nesting of FTL tags. It just sees HTML as flat |
| text, it doesn't interpret it in any way.</p> |
| |
| <p>If you try to use a non-existing directive (e.g., you mistype |
| the directive name), FreeMarker will decline to use the template and |
| produce an error message.</p> |
| |
| <p>FreeMarker ignores superfluous <a href="#gloss.whiteSpace">white-space</a> inside FTL tags. So you |
| can write this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><span class="marked-ftl-tag"><#list<em><span class="marked-invisible-text">[BR]</span></em> |
| animals as<em><span class="marked-invisible-text">[BR]</span></em> |
| being<em><span class="marked-invisible-text">[BR]</span></em> |
| ></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-interpolation">${being.name}</span> for <span class="marked-interpolation">${being.price}</span> Euros<em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"></#list ></span></span></pre></div> |
| |
| <p>You may not, however, insert white-space between the |
| <code class="inline-code"><</code> or <code class="inline-code"></</code> and the directive |
| name.</p> |
| |
| <p>The complete list and description of all directives can be found |
| in the <a href="#ref_directives">Reference/Directive Reference</a> (but I recommend that you |
| look at the chapter about expressions first).</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>FreeMarker can be configured to use <code class="inline-code">[</code> and |
| <code class="inline-code">]</code> instead of <code class="inline-code"><</code> and |
| <code class="inline-code">></code> in the FTL tags and FTL comments, like |
| <code class="inline-code">[#if user == "Big |
| Joe"]<em class="code-color">...</em>[/#if]</code>. For more |
| information read: <a href="#dgui_misc_alternativesyntax">Miscellaneous/Alternative (square bracket) syntax</a>.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>FreeMarker can be configured so that it understands predefined |
| directives without <code class="inline-code">#</code> (like <code class="inline-code"><if user |
| == "Big |
| Joe"><em class="code-color">...</em></if></code>). |
| However we don't recommend the usage of this mode. For more |
| information read: <a href="#ref_depr_oldsyntax">Reference/Deprecated FTL constructs/Old FTL syntax</a></p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_template_exp">Expressions</h4> |
| |
| |
| <p>When you supply values for interpolations or directive |
| parameters you can use variables or more complex expressions. For |
| example, if x is the number 8 and y is 5, the value of <code class="inline-code">(x + |
| y)/2</code> resolves to the numerical value 6.5.</p> |
| |
| <p>Before we go into details, let's see some concrete |
| examples:</p> |
| |
| <ul> |
| <li> |
| <p>When you supply value for interpolations: The usage of |
| interpolations is |
| <code class="inline-code">${<em class="code-color">expression</em>}</code> where |
| expression gives the value you want to insert into the output as |
| text. So <code class="inline-code">${(5 + 8)/2}</code> prints ``6.5'' to the |
| output (or possibly ``6,5'' if the language of your output is not |
| US English).</p> |
| </li> |
| |
| <li> |
| <p>When you supply a value for the directive parameter: You |
| have already seen the <code class="inline-code">if</code> directive in the |
| Getting Started section. The syntax of this directive is: |
| <code class="inline-code"><#if |
| <em class="code-color">expression</em>><em class="code-color">...</em></#if></code>. |
| The expression here must evaluate to a boolean value. For example |
| in <code class="inline-code"><#if 2 < 3></code> the <code class="inline-code">2 < |
| 3</code> (2 is less than 3) is an expression which evaluates to |
| <code class="inline-code">true</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="exp_cheatsheet">Quick overview (cheat sheet)</h5> |
| |
| |
| <p>This is a reminder for those of you who already know |
| FreeMarker or are just experienced programmers:</p> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_direct">Specify values |
| directly</a> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_direct_string">Strings</a>: |
| <code class="inline-code">"Foo"</code> or <code class="inline-code">'Foo'</code> or |
| <code class="inline-code">"It's \"quoted\""</code> or |
| <code class="inline-code">r"C:\raw\string"</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_direct_number">Numbers</a>: |
| <code class="inline-code">123.45</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_direct_boolean">Booleans</a>: |
| <code class="inline-code">true</code>, <code class="inline-code">false</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_direct_seuqence">Sequences</a>: |
| <code class="inline-code">["foo", "bar", 123.45]</code>, |
| <code class="inline-code">1..100</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_direct_hash">Hashes</a>: |
| <code class="inline-code">{"name":"green mouse", |
| "price":150}</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_var">Retrieving |
| variables</a> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_var_toplevel">Top-level |
| variables</a>: <code class="inline-code">user</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_var_hash">Retrieving |
| data from a hash</a>: <code class="inline-code">user.name</code>, |
| <code class="inline-code">user["name"]</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_var_sequence">Retrieving data |
| from a sequence</a>: |
| <code class="inline-code">products[5]</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_var_special">Special |
| variable</a>: <code class="inline-code">.main</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_stringop">String |
| operations</a> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_stringop_interpolation">Interpolation |
| (or concatenation)</a>: |
| <code class="inline-code">"Hello ${user}!"</code> (or |
| <code class="inline-code">"Free" + "Marker"</code>) |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_get_character">Getting a |
| character</a>: <code class="inline-code">name[0]</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_sequenceop">Sequence |
| operations</a> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_sequenceop_cat">Concatenation</a>: |
| <code class="inline-code">users + ["guest"]</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_seqenceop_slice">Sequence |
| slice</a>: <code class="inline-code">products[10..19]</code> or |
| <code class="inline-code">products[5..]</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_hashop">Hash |
| operations</a> |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_hashop_cat">Concatenation</a>: |
| <code class="inline-code">passwords + {"joe":"secret42"}</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_arit">Arithmetical |
| calculations</a>: <code class="inline-code">(x * 1.5 + 10) / 2 - y % |
| 100</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_comparison">Comparison</a>: |
| <code class="inline-code">x == y</code>, <code class="inline-code">x != y</code>, |
| <code class="inline-code">x < y</code>, <code class="inline-code">x > y</code>, |
| <code class="inline-code">x >= y</code>, <code class="inline-code">x <= y</code>, |
| <code class="inline-code">x &lt; y</code>, ...etc. |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_logicalop">Logical |
| operations</a>: <code class="inline-code">!registered && (firstVisit |
| || fromEurope)</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_builtin">Built-ins</a>: |
| <code class="inline-code">name?upper_case</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_methodcall">Method |
| call</a>: <code class="inline-code">repeat("What", 3)</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_missing">Missing value |
| handler operators</a>: |
| |
| <ul> |
| <li> |
| <a href="#dgui_template_exp_missing_default">Default |
| value</a>: <code class="inline-code">name!"unknown"</code> or |
| <code class="inline-code">(user.name)!"unknown"</code> or |
| <code class="inline-code">name!</code> or |
| <code class="inline-code">(user.name)!</code> |
| </li> |
| |
| <li> |
| <a href="#dgui_template_exp_missing_test">Missing |
| value test</a>: <code class="inline-code">name??</code> or |
| <code class="inline-code">(user.name)??</code> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>See also: <a href="#dgui_template_exp_precedence">Operator |
| precedence</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_direct">Specify values directly</h5> |
| |
| |
| |
| |
| |
| |
| <p>Often you want to specify a value directly and not as a result |
| of some calculations.</p> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_direct_string">Strings</h6> |
| |
| |
| |
| |
| <p>To specify a string value directly you give the text in |
| quotation marks, e.g.: <code class="inline-code">"some text"</code> or in |
| apostrophe-quote, e.g. <code class="inline-code">'some text'</code>. The two |
| forms are equivalent. If the text itself contains the character |
| used for the quoting (either <code class="inline-code">"</code> or |
| <code class="inline-code">'</code>) or backslashes, you have to precede them |
| with a backslash; this is called escaping. You can type any other |
| character, including <a href="#gloss.lineBreak">line |
| breaks</a>, in the text directly. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"It's \"quoted\" and |
| this is a backslash: \\"} |
| |
| ${'It\'s "quoted" and |
| this is a backslash: \\'}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">It's "quoted" and |
| this is a backslash: \ |
| |
| It's "quoted" and |
| this is a backslash: \</pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>Of course, you could simply type the above text into the |
| template, without using |
| <code class="inline-code">${<em class="code-color">...</em>}</code>. But we do |
| it here just for the sake of example, to demonstrate |
| expressions.</p> |
| </div> |
| |
| |
| <a name="topic.escapeSequence"></a> |
| |
| |
| |
| <p>This is the list of all supported escape sequences. All |
| other usage of backlash in string literals is an error and any |
| attempt to use the template will fail.</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Escape sequence</th> |
| |
| |
| <th>Meaning</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">\"</code></td> |
| |
| |
| <td>Quotation mark (u0022)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\'</code></td> |
| |
| |
| <td>Apostrophe (a.k.a. apostrophe-quote) (u0027)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\\</code></td> |
| |
| |
| <td>Back slash (u005C)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\n</code></td> |
| |
| |
| <td>Line feed (u000A)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\r</code></td> |
| |
| |
| <td>Carriage return (u000D)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\t</code></td> |
| |
| |
| <td>Horizontal tabulation (a.k.a. tab) (u0009)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\b</code></td> |
| |
| |
| <td>Backspace (u0008)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\f</code></td> |
| |
| |
| <td>Form feed (u000C)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\l</code></td> |
| |
| |
| <td>Less-than sign: <code class="inline-code"><</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\g</code></td> |
| |
| |
| <td>Greater-than sign: <code class="inline-code">></code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\a</code></td> |
| |
| |
| <td>Ampersand: <code class="inline-code">&</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">\x<em class="code-color">Code</em></code></td> |
| |
| |
| <td>Character given with its hexadecimal <a href="#gloss.unicode">Unicode</a> code (<a href="#gloss.UCS">UCS</a> code)</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>The <code class="inline-code"><em class="code-color">Code</em></code> after |
| the <code class="inline-code">\x</code> is 1 to 4 hexadecimal digits. For |
| example this all put a copyright sign into the string: |
| <code class="inline-code">"\xA9 1999-2001"</code>, |
| <code class="inline-code">"\x0A9 1999-2001"</code>, |
| <code class="inline-code">"\x00A9 1999-2001"</code>. When the character directly |
| after the last hexadecimal digit can be interpreted as hexadecimal |
| digit, you must use all 4 digits or else FreeMarker will be |
| confused.</p> |
| |
| <p>Note that the character sequence <code class="inline-code">${</code> (and |
| <code class="inline-code">#{</code>) has special meaning. It's used to insert |
| the value of expressions (typically: the value of variables, as in |
| <code class="inline-code">"Hello ${user}!"</code>). This will be explained <a href="#dgui_template_exp_stringop_interpolation">later</a>. |
| If you want to print <code class="inline-code">${</code>, you should use raw |
| string literals as explained below.</p> |
| |
| |
| |
| <p>A special kind of string literals is the raw string |
| literals. In raw string literals, backslash and |
| <code class="inline-code">${</code> have no special meaning, they are considered |
| as plain characters. To indicate that a string literal is a raw |
| string literal, you have to put an <code class="inline-code">r</code> directly |
| before the opening quotation mark or apostrophe-quote. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${r"${foo}"} |
| ${r"C:\foo\bar"}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">${foo} |
| C:\foo\bar</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_direct_number">Numbers</h6> |
| |
| |
| |
| |
| <p>To specify a numerical value directly you type the number |
| without quotation marks. You have to use the dot as your decimal |
| separator and must not use any grouping separator symbols. You can |
| use <code class="inline-code">-</code> or <code class="inline-code">+</code> to indicate the |
| sign (<code class="inline-code">+</code> is redundant). Scientific notation is |
| not yet supported (so <code class="inline-code">1E3</code> is wrong). Also, you |
| cannot omit the 0 before the decimal separator (so |
| <code class="inline-code">.5</code> is wrong).</p> |
| |
| <p>Examples of valid number literals: <code class="inline-code">0.08</code>, |
| <code class="inline-code">-5.013</code>, <code class="inline-code">8</code>, |
| <code class="inline-code">008</code>, <code class="inline-code">11</code>, |
| <code class="inline-code">+11</code></p> |
| |
| <p>Note that numerical literals like <code class="inline-code">08</code>, |
| <code class="inline-code">+8</code>, <code class="inline-code">8.00</code> and |
| <code class="inline-code">8</code> are totally equivalent as they all symbolize |
| the number eight. Thus, <code class="inline-code">${08}</code>, |
| <code class="inline-code">${+8}</code>, <code class="inline-code">${8.00}</code> and |
| <code class="inline-code">${8}</code> will all print exactly same.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_direct_boolean">Booleans</h6> |
| |
| |
| |
| |
| |
| |
| <p>To specify a boolean value you write <code class="inline-code">true</code> |
| or <code class="inline-code">false</code>. Don't use quotation marks.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_direct_seuqence">Sequences</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>To specify a literal sequence, you list the <a href="#topic.dataModel.subVar">subvariables</a> separated by |
| commas, and put the whole list into square brackets. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list <strong>["winter", "spring", "summer", "autumn"]</strong> as x> |
| ${x} |
| </#list></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">winter |
| spring |
| summer |
| autumn |
| </pre></div> |
| |
| <p>The items in the list are expressions, so you can do this |
| for example: <code class="inline-code">[2 + 2, [1, 2, 3, 4], "whatnot"]</code>. |
| Here the first subvariable will be the number 4, the second will |
| be another sequence, and the third subvariable will be the string |
| "whatnot".</p> |
| |
| <p>You can define sequences that store a numerical range with |
| <code class="inline-code"><em class="code-color">start</em>..<em class="code-color">end</em></code>, |
| where <code class="inline-code"><em class="code-color">start</em></code> and |
| <code class="inline-code"><em class="code-color">end</em></code> are expressions |
| that resolve to numerical values. For example |
| <code class="inline-code">2..5</code> is the same as <code class="inline-code">[2, 3, 4, |
| 5]</code>, but the former is much more efficient (occupies less |
| memory and faster). Note that the square brackets are missing. You |
| can define decreasing numerical ranges too, e.g.: |
| <code class="inline-code">5..2</code>. (Furthermore, you can omit the |
| <code class="inline-code"><em class="code-color">end</em></code>, for example |
| <code class="inline-code">5..</code>, in which case the sequence will contain 5, |
| 6, 7, 8, ...etc up to the infinity.)</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_direct_hash">Hashes</h6> |
| |
| |
| |
| |
| |
| |
| <p>To specify a hash in a template, you list the key/value |
| pairs separated by commas, and put the list into curly brackets. |
| The key and value within a key/value pair are separated with a |
| colon. Here is an example: <code class="inline-code">{"name":"green mouse", |
| "price":150}</code>. Note that both the names and the values |
| are expressions. However, the lookup names must be strings.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_var">Retrieving variables</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_var_toplevel">Top-level variables</h6> |
| |
| |
| |
| |
| <p>To access a top-level variable, you simply use the variable |
| name. For example, the expression <code class="inline-code">user</code> will |
| evaluate to the value of variable stored with name ``user'' in the |
| root. So this will print what you store there:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${user}</pre></div> |
| |
| <p>If there is no such top-level variable, then an error will |
| result when FreeMarker tries to evaluate the expression, and it |
| aborts template processing (unless programmers has configured |
| FreeMarker differently).</p> |
| |
| <p>In this expression the variable name can contain only |
| letters (including non-Latin letters), digits (including non-Latin |
| digits), underline (_), dollar ($), at sign (@) and hash (#). |
| Furthermore, the name must not start with digit.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_var_hash">Retrieving data from a hash</h6> |
| |
| |
| |
| |
| |
| |
| <p>If we already have a hash as a result of an expression, then |
| we can get its subvariable with a dot and the name of the |
| subvariable. Assume that we have this data-model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- book |
| | | |
| | +- title = "Breeding green mouses" |
| | | |
| | +- author |
| | | |
| | +- name = "Julia Smith" |
| | | |
| | +- info = "Biologist, 1923-1985, Canada" |
| | |
| +- test = "title"</pre></div> |
| |
| <p>Now we can read the <code class="inline-code">title</code> with |
| <code class="inline-code">book.title</code>, since the book expression will |
| return a hash (as explained in the last chapter). Applying this |
| logic further, we can read the name of the author with this |
| expression: <code class="inline-code">book.author.name</code>.</p> |
| |
| <p>There is an alternative syntax if we want to give the |
| subvariable name with an expression: |
| <code class="inline-code">book["title"]</code>. In the square brackets you can |
| give any expression as long as it evaluates to a string. So with |
| this data-model you can also read the title with |
| <code class="inline-code">book[test]</code>. More examples; these are all |
| equivalent: <code class="inline-code">book.author.name</code>, |
| <code class="inline-code">book["author"].name</code>, |
| <code class="inline-code">book.author.["name"]</code>, |
| <code class="inline-code">book["author"]["name"]</code>.</p> |
| |
| <p>When you use the dot syntax, the same restrictions apply |
| regarding the variable name as with top-level variables (name can |
| contain only letters, digits, _, $, @, etc.). There are no such |
| restrictions when you use the square bracket syntax, since the |
| name is the result of an arbitrary expression. (Note, that to help |
| the FreeMarker XML support, if the subvariable name is |
| <code class="inline-code">*</code> (asterisk) or <code class="inline-code">**</code>, then you |
| do not have to use square bracket syntax.)</p> |
| |
| <p>As with the top-level variables, trying to access a |
| non-existent subvariable causes an error and aborts the processing |
| of the template (unless programmers has configured FreeMarker |
| differently).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_var_sequence">Retrieving data from a sequence</h6> |
| |
| |
| |
| |
| |
| |
| <p>This is the same as for hashes, but you can use the square |
| bracket syntax only, and the expression in the brackets must |
| evaluate to a number, not a string. For example to get the name of |
| the first animal of the <a href="#example.stdDataModel">example data-model</a> (remember |
| that the number of the first item is 0, not 1): |
| <code class="inline-code">animals[0].name</code></p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_var_special">Special variables</h6> |
| |
| |
| |
| |
| <p>Special variables are variables defined by the FreeMarker |
| engine itself. To access them, you use the |
| <code class="inline-code">.<em class="code-color">variable_name</em></code> |
| syntax.</p> |
| |
| <p>Normally you don't need to use special variables. They are |
| for expert users. The complete list of special variables can be |
| found in the <a href="#ref_specvar">reference</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_stringop">String operations</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>If you want to insert the value of an expression into a |
| string, you can use |
| <code class="inline-code">${<em class="code-color">...</em>}</code> (and |
| <code class="inline-code">#{<em class="code-color">...</em>}</code>) in string |
| literals. <code class="inline-code">${<em class="code-color">...</em>}</code> |
| behaves similarly as in <span class="marked-text">text</span> |
| sections. For example (assume that user is ``Big Joe''):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"Hello ${user}!"} |
| ${"${user}${user}${user}${user}"}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Hello Big Joe! |
| Big JoeBig JoeBig JoeBig Joe</pre></div> |
| |
| <p>Alternatively, you can use the <code class="inline-code">+</code> operator |
| to achieve similar result. This is the old method, and it is |
| called string concatenation. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"Hello " + user + "!"} |
| ${user + user + user + user}</pre></div> |
| |
| <p>This will print the same as the example with the |
| <code class="inline-code">${<em class="code-color">...</em>}</code>-s.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>A frequent mistake of users is the usage of interpolations |
| in places where it shouldn't/can't be used. Interpolations work |
| <em>only</em> in <a href="#dgui_template_overallstructure"><span class="marked-text">text</span> sections</a> (e.g. |
| <code class="inline-code"><h1>Hello ${name}!</h1></code>) and in |
| string literals (e.g. <code class="inline-code"><#include |
| "/footer/${company}.html"></code>). A typical bad usage is |
| <code class="inline-code"><#if ${isBig}>Wow!</#if></code>, which |
| is syntactically <em>WRONG</em>. You should simply |
| write <code class="inline-code"><#if isBig>Wow!</#if></code>. |
| Also, <code class="inline-code"><#if "${isBig}">Wow!</#if></code> |
| is <em>WRONG</em> too, since the parameter value |
| will be a string, and the <code class="inline-code">if</code> directive wants |
| a boolean value, so it will cause a runtime error.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_get_character">Getting a character</h6> |
| |
| |
| |
| |
| |
| |
| <p>You can get a single character of a string at a given index |
| similarly as you can <a href="#dgui_template_exp_var_sequence">read the subvariable of a |
| sequence</a>, e.g. <code class="inline-code">user[0]</code>. The result will |
| be a string whose length is 1; FTL doesn't have a separate |
| character type. As with sequence subvariables, the index must be a |
| number that is at least 0 and less than the length of the string, |
| or else an error will abort the template processing.</p> |
| |
| <p>Since the sequence subvariable syntax and the character |
| getter syntax clashes, you can use the character getter syntax |
| only if the variable is not a sequence as well (which is possible |
| because FTL supports multi-typed values), since in that case the |
| sequence behavior prevails. (To work this around, you can use |
| <a href="#ref_builtin_string_for_string">the |
| <code>string</code> built-in</a>, e.g. |
| <code class="inline-code">user?string[0]</code>. Don't worry if you don't |
| understand this yet; built-ins will be discussed later.)</p> |
| |
| <p>Example (assume that user is ``Big Joe''):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${user[0]} |
| ${user[4]}</pre></div> |
| |
| <p>will print (note that the index of the first character is |
| 0):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">B |
| J</pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>You can get a range of characters in the same way as you |
| <a href="#dgui_template_exp_seqenceop_slice">get a sequence |
| slice</a>, e.g <code class="inline-code">${user[1..4]}</code> and |
| <code class="inline-code">${user[4..]}</code>. However, it's now depreacted to |
| utilize this, and instead you should use <a href="#ref_builtin_substring">the <code>substring</code> |
| built-in</a>; built-ins will be discussed later.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_sequenceop">Sequence operations</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_sequenceop_cat">Concatenation</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>You can concatenate sequences in the same way as strings, |
| with <code class="inline-code">+</code>. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list ["Joe", "Fred"] + ["Julia", "Kate"] as user> |
| - ${user} |
| </#list></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- Joe |
| - Fred |
| - Julia |
| - Kate |
| </pre></div> |
| |
| <p>Note that sequence concatenation is not to be used for many |
| repeated concatenations, like for appending items to a sequence |
| inside a loop. It's just for things like <code class="inline-code"><#list users |
| + admins as person></code>. Although concatenating sequences |
| is fast and its speed is independently of the size of the |
| concatenated sequences, the resulting sequence will be always a |
| little bit slower to read than the original two sequences were. |
| This way the result of many repeated concatenations is a sequence |
| that is slow to read.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_seqenceop_slice">Sequence slice</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>With |
| <code class="inline-code">[<em class="code-color">firstindex</em>..<em class="code-color">lastindex</em>]</code> |
| you can get a slice of a sequence, where |
| <code class="inline-code"><em class="code-color">firstindex</em></code> and |
| <code class="inline-code"><em class="code-color">lastindex</em></code> are |
| expressions evaluate to number. For example, if |
| <code class="inline-code">seq</code> stores the sequence <code class="inline-code">"a"</code>, |
| <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code>, |
| <code class="inline-code">"f"</code> then the expression |
| <code class="inline-code">seq[1..4]</code> will evaluate to a sequence that |
| contains <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code> (since the item at |
| index 1 is <code class="inline-code">"b"</code>, and the item at index 4 is |
| <code class="inline-code">"e"</code>).</p> |
| |
| <p>The <code class="inline-code"><em class="code-color">lastindex</em></code> |
| can be omitted, in which case it defaults to the index of the last |
| item of the sequence. For example, if <code class="inline-code">seq</code> |
| stores the sequence <code class="inline-code">"a"</code>, |
| <code class="inline-code">"b"</code>, <code class="inline-code">"c"</code>, |
| <code class="inline-code">"d"</code>, <code class="inline-code">"e"</code>, |
| <code class="inline-code">"f"</code> again, then <code class="inline-code">seq[3..]</code> |
| will evaluate to a sequence that contains <code class="inline-code">"d"</code>, |
| <code class="inline-code">"e"</code>, <code class="inline-code">"f"</code>.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p><code class="inline-code"><em class="code-color">lastindex</em></code> |
| can be omitted only since FreeMarker 2.3.3.</p> |
| </div> |
| |
| |
| <p>An attempt to access a subvariable past the last subvariable |
| or before the first subvariable of the sequence will cause an |
| error and abort the processing of the template.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_hashop">Hash operations</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_hashop_cat">Concatenation</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>You can concatenate hashes in the same way as strings, with |
| <code class="inline-code">+</code>. If both hashes contain the same key, the |
| hash on the right-hand side of the <code class="inline-code">+</code> takes |
| precedence. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}> |
| - Joe is ${ages.Joe} |
| - Fred is ${ages.Fred} |
| - Julia is ${ages.Julia}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- Joe is 30 |
| - Fred is 25 |
| - Julia is 18</pre></div> |
| |
| <p>Note that hash concatenation is not to be used for many |
| repeated concatenations, like for adding items to a hash inside a |
| loop. It's the same as with the <a href="#dgui_template_exp_sequenceop_cat">sequence |
| concatenation</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_arit">Arithmetical calculations</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>This is the basic 4-function calculator arithmetic plus the |
| modulus operator. So the operators are:</p> |
| |
| <ul> |
| <li> |
| Addition: <code class="inline-code">+</code> |
| </li> |
| |
| <li> |
| Subtraction: <code class="inline-code">-</code> |
| </li> |
| |
| <li> |
| Multiplication: <code class="inline-code">*</code> |
| </li> |
| |
| <li> |
| Division: <code class="inline-code">/</code> |
| </li> |
| |
| <li> |
| Modulus (remainder): <code class="inline-code">%</code> |
| </li> |
| </ul> |
| |
| |
| |
| <p>Example:</p> |
| |
| <p>Assuming that <code class="inline-code">x</code> is 5, it will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">-75 |
| 2.5 |
| 2</pre></div> |
| |
| <p>Both operands must be expressions which evaluate to a |
| numerical value. So the example below will cause an error when |
| FreeMarker tries to evaluate it, since <code class="inline-code">"5"</code> is a |
| string and not the number 5:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${3 * "5"} <#-- WRONG! --></pre></div> |
| |
| <p>There is an exception to the above rule. The |
| <code class="inline-code">+</code> operator, is used to <a href="#dgui_template_exp_stringop_interpolation">concatenate |
| strings</a> as well. If on one side of <code class="inline-code">+</code> is a |
| string and on the other side of <code class="inline-code">+</code> is a numerical |
| value, then it will convert the numerical value to string (using the |
| format appropriate for language of the page) and then use the |
| <code class="inline-code">+</code> as string concatenation operator. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${3 + "5"}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">35</pre></div> |
| |
| <p>Generally, FreeMarker never converts a string to a number |
| automatically, but it may convert a number to a string |
| automatically.</p> |
| |
| <p> People often want only the integer part of the result |
| of a division (or of other calculations). This is possible with the |
| <code class="inline-code">int</code> built-in. (Built-ins are explained <a href="#dgui_template_exp_builtin">later</a>):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${(x/2)?int} |
| ${1.1?int} |
| ${1.999?int} |
| ${-1.1?int} |
| ${-1.999?int}</pre></div> |
| |
| <p>Assuming that <code class="inline-code">x</code> is 5, it will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">2 |
| 1 |
| 1 |
| -1 |
| -1</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_comparison">Comparison</h5> |
| |
| |
| |
| |
| <p>Sometimes you want to know if two values are equal or not, or |
| which value is the greater.</p> |
| |
| <p>To show concrete examples I will use the <code class="inline-code">if</code> |
| directive here. The usage of <code class="inline-code">if</code> directive is: |
| <code class="inline-code"><#if |
| <em class="code-color">expression</em>>...</#if></code>, |
| where expression must evaluate to a boolean value or else an error |
| will abort the processing of the template. If the value of |
| expression is <code class="inline-code">true</code> then the things between the |
| begin and end-tag will be processed, otherwise they will be |
| skipped.</p> |
| |
| <p>To test two values for equality you use <code class="inline-code">=</code> |
| (or <code class="inline-code">==</code> as in Java or C; the two are absolutely |
| equivalent.) To test two values for inequality you use |
| <code class="inline-code">!=</code>. For example, assume that |
| <code class="inline-code">user</code> is ``Big Joe'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if <strong>user = "Big Joe"</strong>> |
| It is Big Joe |
| </#if> |
| <#if <strong>user != "Big Joe"</strong>> |
| It is not Big Joe |
| </#if></pre></div> |
| |
| <p>The <code class="inline-code">user = "Big Joe"</code> expression in the |
| <code class="inline-code"><#if ...></code> will evaluate to the boolean |
| <code class="inline-code">true</code>, so the above will say ``It is Big |
| Joe''.</p> |
| |
| <p>The expressions on both sides of the <code class="inline-code">=</code> or |
| <code class="inline-code">!=</code> must evaluate to a scalar. Furthermore, the |
| two scalars must have the same type (i.e. strings can only be |
| compared to strings and numbers can only be compared to numbers, |
| etc.) or else an error will abort template processing. For example |
| <code class="inline-code"><#if 1 = "1"></code> will cause an error. Note |
| that FreeMarker does exact comparison, so string comparisons are |
| case and white-space sensitive: <code class="inline-code">"x"</code> and |
| <code class="inline-code">"x "</code> and <code class="inline-code">"X"</code> are not equal |
| values.</p> |
| |
| <p>For numerical and date values you can also use |
| <code class="inline-code"><</code>, <code class="inline-code"><=</code>, |
| <code class="inline-code">>=</code> and <code class="inline-code">></code>. You can't use |
| them for strings! Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x <strong><=</strong> 12> |
| x is less or equivalent with 12 |
| </#if></pre></div> |
| |
| <p>There is a little problem with <code class="inline-code">>=</code> and |
| <code class="inline-code">></code>. FreeMarker interprets the |
| <code class="inline-code">></code> as the closing character of the FTL tag. To |
| prevent this, you have to put the expression into <a href="#dgui_template_exp_parentheses">parenthesis</a>: |
| <code class="inline-code"><#if (x > y)></code>. Or, you can use |
| <code class="inline-code">&gt;</code> and <code class="inline-code">&lt;</code> on the |
| place of the problematic relation marks: <code class="inline-code"><#if x &gt; |
| y></code>. (Note that in general FTL does not support entity |
| references (those |
| <code class="inline-code">&<em class="code-color">...</em>;</code> things) in |
| FTL tags; it is just an exception with the arithmetical |
| comparisons.). Also, as an alternative you can use |
| <code class="inline-code">lt</code> instead of <code class="inline-code"><</code>, |
| <code class="inline-code">lte</code> instead of <code class="inline-code"><=</code>, |
| <code class="inline-code">gt</code> instead of <code class="inline-code">></code> and |
| <code class="inline-code">gte</code> instead of <code class="inline-code">>=</code>. And, for |
| historical reasons FTL also understands <code class="inline-code">\lt</code>, |
| <code class="inline-code">\lte</code>, <code class="inline-code">\gt</code> and |
| <code class="inline-code">\gte</code> which are the same as the ones without the |
| backslash.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_logicalop">Logical operations</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Just the usual logical operators:</p> |
| |
| <ul> |
| <li> |
| Logical or: <code class="inline-code">||</code> |
| </li> |
| |
| <li> |
| Logical and: <code class="inline-code">&&</code> |
| </li> |
| |
| <li> |
| Logical not: <code class="inline-code">!</code> |
| </li> |
| </ul> |
| |
| <p>The operators will work with boolean values only. Otherwise an |
| error will abort the template processing.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x < 12 <strong>&&</strong> color = "green"> |
| We have less than 12 things, and they are green. |
| </#if> |
| <#if <strong>!</strong>hot> <#-- here hot must be a boolean --> |
| It's not hot. |
| </#if></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_builtin">Built-ins</h5> |
| |
| |
| |
| |
| <p>Built-ins provide, as the name suggest, certain built-in |
| functionality that is always available. Typically, a built-in |
| provides a different version of a variable, or some information |
| about the variable in question. The syntax for accessing a built-in |
| is like that of accessing a subvariable in a hash, except that you |
| use the question mark instead of a dot. For example, to get the |
| upper case version of a string: |
| <code class="inline-code">user?upper_case</code>.</p> |
| |
| <p>You can find the complete <a href="#ref_builtins">list of |
| built-ins in the Reference</a>. For now, just a few of the more |
| important ones:</p> |
| |
| <ul> |
| <li> |
| <p>Built-ins to use with strings:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">html</code>: The string with all special |
| HTML characters replaced with entity references (E.g. |
| <code class="inline-code"><</code> with |
| <code class="inline-code">&lt;</code>)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">cap_first</code>: The string with the |
| first letter converted to upper case</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">lower_case</code>: The lowercase version |
| of the string</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">upper_case</code>: The uppercase version |
| of the string</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">trim</code>: The string without leading |
| and trailing <a href="#gloss.whiteSpace">white-spaces</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Built-ins to use with sequences:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">size</code>: The number of elements in the |
| sequence</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Built-ins to use with numbers:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">int</code>: The integer part of a number |
| (e.g. <code class="inline-code">-1.9?int</code> is |
| <code class="inline-code">-1</code>)</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${test?html} |
| ${test?upper_case?html}</pre></div> |
| |
| <p>Assuming that <code class="inline-code">test</code> stores the string ``Tom |
| & Jerry'', the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Tom &amp; Jerry |
| TOM &amp; JERRY</pre></div> |
| |
| <p>Note the <code class="inline-code">test?upper_case?html</code>. Since the |
| result of <code class="inline-code">test?upper_case</code> is a string, you can |
| use the <code class="inline-code">html</code> built-in with it.</p> |
| |
| <p>Another example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${seasons?size} |
| ${seasons[1]?cap_first} <#-- left side can by any expression --> |
| ${"horse"?cap_first}</pre></div> |
| |
| <p>Assuming that <code class="inline-code">seasons</code> stores the sequence |
| <code class="inline-code">"winter"</code>, <code class="inline-code">"spring"</code>, |
| <code class="inline-code">"summer"</code>, <code class="inline-code">"autumn"</code>, the output |
| will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">4 |
| Spring |
| Horse</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_methodcall">Method call</h5> |
| |
| |
| |
| |
| |
| |
| <p>If you have a method then you can use the method call |
| operation on it. The method call operation is a comma-separated list |
| of expressions in parentheses. These values are called parameters. |
| The method call operation passes these values to the method which |
| will in turn return a result. This result will be the value of the |
| whole method call expression.</p> |
| |
| <p>For example, assume the programmers have made available a |
| method variable called <code class="inline-code">repeat</code>. You give a string |
| as the first parameter, and a number as the second parameter, and it |
| returns a string which repeats the first parameter the number of |
| times specified by the second parameter.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${repeat("What", 3)}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">WhatWhatWhat</pre></div> |
| |
| <p>Here <code class="inline-code">repeat</code> was evaluated to the method |
| variable (according to how you <a href="#dgui_template_exp_var_toplevel">access top-level |
| variables</a>) and then <code class="inline-code">("What", 3)</code> invoked |
| that method.</p> |
| |
| <p>I would like to emphasize that method calls are just plain |
| expressions, like everything else. So this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${repeat(repeat("x", 2), 3) + repeat("What", 4)?upper_case}</pre></div> |
| |
| <p>will print this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">xxxxxxWHATWHATWHATWHAT</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_missing">Handling missing values</h5> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>These operators exist since FreeMarker 2.3.7 (replacing the |
| <code class="inline-code">default</code>, <code class="inline-code">exists</code> and |
| <code class="inline-code">if_exists</code> built-ins).</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>As we explained earlier, an error will occur and abort the |
| template processing if you try to access a missing variable. However |
| two special operators can suppress this error, and handle the |
| problematic situation. The handled variable can be top-level |
| variable, hash subvariable, or sequence subvariable as well. |
| Furthermore these operators handle the situation when a method call |
| doesn't return a value <span class="marked-for-programmers">(from the |
| viewpoint of Java programmers: it returns <code class="inline-code">null</code> or |
| it's return type is <code class="inline-code">void</code>)</span>, so it's more |
| correct to say that these operators handle missing values in |
| general, rather than just missing variables.</p> |
| |
| <p><span class="marked-for-programmers">For those who know what's Java |
| <code class="inline-code">null</code>, FreeMarker 2.3.<em>x</em> |
| treats them as missing values. Simply, the template language doesn't |
| know the concept of <code class="inline-code">null</code>. For example, if you |
| have a bean that has a <code class="inline-code">maidenName</code> property, and |
| the value of that property is <code class="inline-code">null</code>, then that's |
| the same as if there were no such property at all, as far as the |
| template is concerned (assuming you didn't configured FreeMarker to |
| use some extreme object wrapper, that is). The result of a method |
| call that returns <code class="inline-code">null</code> is also treated as a |
| missing variable (again, assuming that you use some usual object |
| wrapper). See more <a href="#faq_null">in the |
| FAQ</a>.</span></p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>If you wonder why is FreeMarker so picky about missing |
| variables, <a href="#faq_picky_about_missing_vars">read this |
| FAQ entry</a>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_missing_default">Default value operator</h6> |
| |
| |
| |
| |
| <p>Synopsis: |
| <code class="inline-code"><em class="code-color">unsafe_expr</em>!<em class="code-color">default_expr</em></code> |
| or <code class="inline-code"><em class="code-color">unsafe_expr</em>!</code> or |
| <code class="inline-code">(<em class="code-color">unsafe_expr</em>)!<em class="code-color">default_expr</em></code> |
| or |
| <code class="inline-code">(<em class="code-color">unsafe_expr</em>)!</code></p> |
| |
| <p>This operator allows you to specify a default value for the |
| case when the value is missing.</p> |
| |
| <p>Example. Assume no variable called <code class="inline-code">mouse</code> |
| is present:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${mouse!"No mouse."} |
| <#assign mouse="Jerry"> |
| ${mouse!"No mouse."}</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">No mouse. |
| Jerry</pre></div> |
| |
| <p>The default value can be any kind of expression, so it |
| doesn't have to be a string. For example you can write |
| <code class="inline-code">hits!0</code> or <code class="inline-code">colors!["red", "green", |
| "blue"]</code>. There is no restriction regarding the |
| complexity of the expression that specifies the default value, for |
| example you can write: <code class="inline-code">cargo.weight!(item.weight * |
| itemCount + 10)</code>.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>If you have a composite expression after the |
| <code class="inline-code">!</code>, like <code class="inline-code">1 + x</code>, |
| <em>always</em> use parenthesses, like |
| <code class="inline-code">${x!(1 + y)}</code> or <code class="inline-code">${(x!1) + |
| y)}</code>, depending on which interpretation you meant. |
| That's needed because due to a programming mistake in FreeMarker |
| 2.3.x, the precedence of <code class="inline-code">!</code> (when it's used as |
| default value operator) is very low at its right side. This |
| means that, for example, <code class="inline-code">${x!1 + y}</code> is |
| misinterpreted by FreeMarker as <code class="inline-code">${x!(1 + y)}</code> |
| while it should mean <code class="inline-code">${(x!1) + y}</code>. This |
| programming error will be fixed in FreeMarker 2.4, so you should |
| not utilize this wrong behavior, or else your templates will |
| break with FreeMarker 2.4!</p> |
| </div> |
| |
| |
| <p>If the default value is omitted, then it will be empty |
| string and empty sequence and empty hash at the same time. (This |
| is possible because FreeMarker allows multi-type values.) Note the |
| consequence that you can't omit the default value if you want it |
| to be <code class="inline-code">0</code> or <code class="inline-code">false</code>. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">(${mouse!}) |
| <#assign mouse = "Jerry"> |
| (${mouse!})</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">() |
| (Jerry)</pre></div> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>Due to syntactical ambiguities <code class="inline-code"><@something |
| a=x! b=y /></code> will be interpreted as |
| <code class="inline-code"><@something a=x!(b=y) /></code>, that is, the |
| <code class="inline-code">b=y</code> will be interpreted as a comparison that |
| gives the default value for <code class="inline-code">x</code>, rather than |
| the specification of the <code class="inline-code">b</code> parameter. To |
| prevent this, write: <code class="inline-code"><@something a=(x!) b=y |
| /></code></p> |
| </div> |
| |
| |
| <p>You can use this operator in two ways with non-top-level |
| variables:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">product.color!"red"</pre></div> |
| |
| <p>This will handle if <code class="inline-code">color</code> is missing |
| inside <code class="inline-code">product</code> (and returns |
| <code class="inline-code">"red"</code> if so), but will not handle if |
| <code class="inline-code">product</code> is missing. That is, the |
| <code class="inline-code">product</code> variable itself must exist, otherwise |
| the template processing will die with error.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">(product.color)!"red"</pre></div> |
| |
| <p>This will handle if <code class="inline-code">product.color</code> is |
| missing. That is, if <code class="inline-code">product</code> is missing, or |
| <code class="inline-code">product</code> exists but it does not contain |
| <code class="inline-code">color</code>, the result will be |
| <code class="inline-code">"red"</code>, and no error will occur. The important |
| difference between this and the previous example is that when |
| surrounded with parentheses, it is allowed for any component of |
| the expression to be undefined, while without parentheses only the |
| last component of the expression is allowed to be |
| undefined.</p> |
| |
| <p>Of course, the default value operator can be used with |
| sequence subvariables as well:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign seq = ['a', 'b']> |
| ${seq[0]!'-'} |
| ${seq[1]!'-'} |
| ${seq[2]!'-'} |
| ${seq[3]!'-'}</pre></div> |
| |
| <p>the outpur will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">a |
| b |
| - |
| -</pre></div> |
| |
| <p>A negative sequence index (as |
| <code class="inline-code">seq[-1]!'-'</code>) will always cause an error, you |
| can't suppress that with this or any other operator.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="dgui_template_exp_missing_test">Missing value test operator</h6> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Synopsis: |
| <code class="inline-code"><em class="code-color">unsafe_expr</em>??</code> or |
| <code class="inline-code">(<em class="code-color">unsafe_expr</em>)??</code></p> |
| |
| <p>This operator tells if a value is missing or not. Depending |
| on that, the result is either <code class="inline-code">true</code> or |
| <code class="inline-code">false</code>.</p> |
| |
| <p>Example. Assume no variable called <code class="inline-code">mouse</code> |
| is present:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if mouse??> |
| Mouse found |
| <#else> |
| No mouse found |
| </#if> |
| Creating mouse... |
| <#assign mouse = "Jerry"> |
| <#if mouse??> |
| Mouse found |
| <#else> |
| No mouse found |
| </#if></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> No mouse found |
| Creating mouse... |
| Mouse found</pre></div> |
| |
| <p>With non-top-level variables the rules are the same as with |
| the default value operator, that is, you can write |
| <code class="inline-code">product.color??</code> and |
| <code class="inline-code">(product.color)??</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_parentheses">Parentheses</h5> |
| |
| |
| |
| |
| <p>Parentheses can be used to group any expressions. Some |
| examples:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> <#-- Output will be: --> |
| ${3 * 2 + 2} <#-- 8 --> |
| ${3 * (2 + 2)} <#-- 12 --> |
| ${3 * ((2 + 2) * (1 / 2))} <#-- 6 --> |
| ${"green " + "mouse"?upper_case} <#-- green MOUSE --> |
| ${("green " + "mouse")?upper_case} <#-- GREEN MOUSE --> |
| <#if !( color = "red" || color = "green")> |
| The color is nor red nor green |
| </#if></pre></div> |
| |
| <p>Note that the parentheses of a <a href="#dgui_template_exp_methodcall">method call |
| expressions</a> have nothing to do with the parentheses used for |
| grouping.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_whitespace">White-space in expressions</h5> |
| |
| |
| <p>FTL ignores superfluous <a href="#gloss.whiteSpace">white-space</a> in expressions. So |
| these are totally equivalent:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${x + ":" + book.title?upper_case}</pre></div> |
| |
| <p>and</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${x+":"+book.title?upper_case}</pre></div> |
| |
| <p>and</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${ |
| x |
| + ":" + book . title |
| ? upper_case |
| }</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_template_exp_precedence">Operator precedence</h5> |
| |
| |
| |
| |
| |
| |
| <p>The following table shows the precedence assigned to the |
| operators. The operators in this table are listed in precedence |
| order: the higher in the table an operator appears, the higher its |
| precedence. Operators with higher precedence are evaluated before |
| operators with a relatively lower precedence. Operators on the same |
| line have equal precedence. When binary operators (operators with |
| two ``parameters'', as <code class="inline-code">+</code> and |
| <code class="inline-code">-</code>) of equal precedence appear next to each other, |
| they are evaluated in left-to-right order.</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Operator group</th> |
| |
| |
| <th>Operators</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td>highest precedence operators</td> |
| |
| |
| <td><code class="inline-code">[<em class="code-color">subvarName</em>] |
| [<em class="code-color">subStringRange</em>] . ? |
| (<em class="code-color">methodParams</em>) |
| <em class="code-color">expr</em>! |
| <em class="code-color">expr</em>??</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>unary prefix operators</td> |
| |
| |
| <td><code class="inline-code">+<em class="code-color">expr</em> |
| -<em class="code-color">expr</em> !expr</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>multiplicative</td> |
| |
| |
| <td><code class="inline-code">* / %</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>additive</td> |
| |
| |
| <td><code class="inline-code">+ -</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>relational</td> |
| |
| |
| <td><code class="inline-code">< > <= >=</code> (and quivalents: |
| <code class="inline-code">gt</code>, <code class="inline-code">lt</code>, etc.)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>equality</td> |
| |
| |
| <td><code class="inline-code">== !=</code> (and equivalents: |
| <code class="inline-code">=</code>)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>logical AND</td> |
| |
| |
| <td><code class="inline-code">&&</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>logical OR</td> |
| |
| |
| <td><code class="inline-code">||</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>numerical range</td> |
| |
| |
| <td><code class="inline-code">..</code></td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>For those of you who master C, Java language or JavaScript, |
| note that the precedence rules are the same as in those languages, |
| except that FTL has some operators that do not exist in those |
| languages.</p> |
| |
| <p>The default value operator |
| (<code class="inline-code"><em class="code-color">exp</em>!<em class="code-color">exp</em></code>) |
| is not yet in the table because of a programming mistake, which will |
| be only fixed in FreeMarker 2.4 due to backward compatibility |
| constraints. It meant to be a "highest precedence operator", but in |
| FreeMarker 2.3.x the precedence on its right side is very low by |
| accident. So if you have a composite expression on the right side, |
| always use paranthesses, etiher like <code class="inline-code">x!(y + 1)</code> or |
| like <code class="inline-code">(x!y) + 1</code>. Never write just <code class="inline-code">x!y + |
| 1</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_template_valueinsertion">Interpolations</h4> |
| |
| |
| |
| |
| |
| |
| <p>The format of interpolations is |
| <code class="inline-code">${<em class="code-color">expression</em>}</code>, where |
| <code class="inline-code"><em class="code-color">expression</em></code> can be all |
| kind of expression (e.g. <code class="inline-code">${100 + x}</code>).</p> |
| |
| <p>The interpolation is used to insert the value of the |
| <code class="inline-code"><em class="code-color">expression</em></code> converted to |
| text (to string). Interpolations can be used only on two places: in |
| <a href="#dgui_template_overallstructure"><span class="marked-text">text</span> sections</a> (e.g., |
| <code class="inline-code"><h1>Hello ${name}!</h1></code>) and <a href="#dgui_template_exp_stringop_interpolation">in string literal |
| expressions</a> (e.g., <code class="inline-code">[#include |
| "/footer/${company}.html"]</code>).</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>A frequent mistake is the usage of interpolations in places |
| where it shouldn't/can't be used. A typical bad usage is |
| <code class="inline-code">[#if ${isBig}]Wow![/#if]</code>, which is syntactically |
| <em>WRONG</em>. You should simply write <code class="inline-code">[#if |
| isBig]Wow![/#if]</code>. Also, <code class="inline-code">[#if |
| "${isBig}"]Wow![/#if]</code> is <em>WRONG</em>, since |
| the parameter value will be a string, and the <code class="inline-code">if</code> |
| directive wants a boolean value, so it will cause a runtime |
| error.</p> |
| </div> |
| |
| |
| <p>The result of the expression must be a string, number or date |
| value. This is because only numbers and dates will be converted to |
| string by the interpolation automatically, other types of values (such |
| as booleans, sequences) must be converted to string "manually" somehow |
| (see some advices later), or an error will stop the template |
| processing.</p> |
| |
| <p>If the interpolation is in a <a href="#dgui_template_overallstructure"><span class="marked-text">text</span> section</a> (i.e., not in a <a href="#dgui_template_exp_stringop_interpolation">string literal |
| expression</a>), the string that it will insert will be |
| automatically escaped if an <a href="#ref.directive.escape"><code>escape</code> |
| directive</a> is in effect.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-simplesect" id="autoid_18">Guide for inserting numerical values</h5> |
| |
| |
| <p>If the expression evaluates to a number then the numerical |
| value will be converted to string according the default number |
| format. This may includes the maximum number of decimals, grouping, |
| and like. Usually the programmer should set the default number |
| format; the template author don't have to deal with it (but he can |
| with the <code class="inline-code">number_format</code> setting; see in the <a href="#ref_directive_setting">documentation of |
| <code>setting</code> directive</a>). You can override the |
| default number format for a single interpolation with the <a href="#ref_builtin_string_for_number"><code>string</code> |
| built-in</a>.</p> |
| |
| <p>The decimal separator used (and other such symbols, like the |
| group separator) depends on the current locale (language, country), |
| that also should be set by the programmer. For example, this |
| template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${1.5}</pre></div> |
| |
| <p>will print something like this if the current locale is |
| English:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1.5</pre></div> |
| |
| <p>but if the current locale is Hungarian then it will print |
| something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1,5</pre></div> |
| |
| <p>since Hungarian people use comma as decimal separator.</p> |
| |
| <p>You can modify the formatting for a single interpolation with |
| the <a href="#ref_builtin_string_for_number"><code>string</code> |
| built-in</a>.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>As you can see, interpolations print for human audience (by |
| default at least), as opposed to ''computer audience''. In some |
| cases this is not good, like when you print a database record ID-s |
| as the part of an URL or as an invisible field value in a HTML |
| form, or when you print CSS/JavaScript numerical literals, because |
| these printed values will be read by computer programs and not by |
| humans. Most computer programs are very particular about the |
| format of the numbers, and understand only a kind of simple US |
| number formatting. For that, use the <a href="#ref_builtin_c"><code>c</code></a> (stands for |
| ''computer audience'') built-in, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a href="/shop/productdetails?id=${product.id?c}">Details...</a></pre></div> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-simplesect" id="dgui_template_valueinserion_universal_date">Guide for inserting date/time values</h5> |
| |
| |
| <p>If the expression evaluates to a date then the numerical value |
| will be transformed to a text according to a default format. Usually |
| the programmer should set the default format; you don't have to deal |
| with it (but if you care, see the <code class="inline-code">date_format</code>, |
| <code class="inline-code">time_format</code> and |
| <code class="inline-code">datetime_format</code> settings in the <a href="#ref_directive_setting">documentation of the |
| <code>setting</code> directive</a>).</p> |
| |
| <p>You can override the default formatting for a single |
| interpolation with the <a href="#ref_builtin_string_for_date"><code>string</code> |
| built-in</a>.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>To display a date as text, FreeMarker must know which parts |
| of the date are in use, that is, if only the date part (year, |
| month, day), or only the time part (hour, minute, second, |
| millisecond), or both. Unfortunately, because of the technical |
| limitations of Java platform, for some variables it is not |
| possible to detect this automatically; ask the programmer if the |
| data-model contains such problematic variables. If it is not |
| possible to find out which parts of the date are in use, then you |
| must help FreeMarker with the <a href="#ref_builtin_date_datetype"><code>date</code>, |
| <code>time</code> and <code>datetime</code></a> |
| built-ins, or it will stop with error.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-simplesect" id="autoid_19">Guide for inserting boolean values</h5> |
| |
| |
| <p>An attempt to print boolean values with interpolation causes |
| an error and aborts template processing. For example this will cause |
| an error: <code class="inline-code">${a == 2}</code> and will not print ''true'' |
| or something like that.</p> |
| |
| <p>However, you can convert booleans to strings with the <a href="#ref_builtin_string_for_boolean"><code>?string</code> |
| built-in</a>. For example, to print the value of the "married" |
| variable (assuming it's a boolean), you could write |
| <code class="inline-code">${married?string("yes", "no")}</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-simplesect" id="autoid_20">The exact conversion rules</h5> |
| |
| |
| <p>For those who are interested, the exact rules of conversion |
| from the expression value to string (that is then still subject to |
| escaping) are these, in in this order:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If the value is a number, then it is converted to string |
| in the format specified with the |
| <code class="inline-code">number_format</code> setting. So this usually |
| formats for human audience, as opposed to computer |
| audience.</p> |
| </li> |
| |
| <li> |
| <p>Else if the value is whatever kind of date, time or |
| date-time, then it is converted to string in the format |
| specified with the <code class="inline-code">time_format</code>, |
| <code class="inline-code">date_format</code>, or |
| <code class="inline-code">datetime_format</code> setting, depending on whether |
| the date information is time-only, date-only, or a date-time. If |
| it can't be detected what kind of date it is (date vs time vs |
| date-time), an error will occur.</p> |
| </li> |
| |
| <li> |
| <p>Else if the value is a string, then there is no |
| conversion.</p> |
| </li> |
| |
| <li> |
| <p>Else if the engine is in classic compatibility |
| mode:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If the value is a boolean, true values are converted |
| to "true", false values are converted to an empty |
| string.</p> |
| </li> |
| |
| <li> |
| <p>If the expression is undefined |
| (<code class="inline-code">null</code> or a variable is undefined), it is |
| converted to an empty string.</p> |
| </li> |
| |
| <li> |
| <p>Else an error will abort the template |
| processing.</p> |
| </li> |
| </ol></div> |
| </li> |
| |
| <li> |
| <p>Else an error will abort the template processing.</p> |
| </li> |
| </ol></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="dgui_misc">Miscellaneous</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_misc_userdefdir">Defining your own directives</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>As far as template authors are concerned, user-defined |
| directives can be defined using the <code class="inline-code">macro</code> |
| directive. <span class="marked-for-programmers">Java programmers who want to |
| implement directives in Java Language, rather than in a template, |
| should use |
| <code class="inline-code">freemarker.template.TemplateDirectiveModel</code> (see |
| <a href="#pgui_datamodel_directive">more |
| here...</a>).</span></p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_21">Basics</h5> |
| |
| |
| |
| |
| <p>A macro is a template fragment associated with a variable. You |
| can use that variable in your template as a user-defined directive, |
| so it helps in repetitive tasks. For example, this creates a macro |
| variable that prints a big ``Hello Joe!'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#macro greet></strong> |
| <font size="+2">Hello Joe!</font> |
| <strong></#macro></strong></pre></div> |
| |
| <p>The <code class="inline-code">macro</code> directive itself does not print |
| anything; it just creates the macro variable, so there will be a |
| variable called <code class="inline-code">greet</code>. Things between the |
| <code class="inline-code"><#macro greet></code> and |
| <code class="inline-code"></#macro></code> (called <strong>macro definition body</strong>) will be executed only |
| when you use the variable as directive. You use user-defined |
| directives by writing <code class="inline-code">@</code> instead of |
| <code class="inline-code">#</code> in the FTL tag. Use the variable name as the |
| directive name. Also, the <a href="#gloss.endTag">end-tag</a> for user-defined directives is |
| mandatory. So you use <code class="inline-code">greet</code> like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet></@greet></pre></div> |
| |
| <p>But since |
| <code class="inline-code"><<em class="code-color">anything</em>></<em class="code-color">anything</em>></code> |
| is equivalent with |
| <code class="inline-code"><<em class="code-color">anything</em>/></code> you |
| should use this shorter form (that is familiar for you if you know |
| <a href="#gloss.XML">XML</a>):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet/></pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <font size="+2">Hello Joe!</font> |
| </pre></div> |
| |
| <p>But macros can do much more, since the thing between |
| <code class="inline-code"><#macro <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#macro></code> is a template fragment, thus it |
| can contain interpolations |
| (<code class="inline-code">${<em class="code-color">...</em>}</code>) and FTL tags |
| (e.g. <code class="inline-code"><#if |
| <em class="code-color">...</em>><em class="code-color">...</em></#if></code>).</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>Programmers will say on |
| <code class="inline-code"><@<em class="code-color">...</em>></code> that |
| you <strong>call</strong> the macro.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_22">Parameters</h5> |
| |
| |
| <p>Let's improve the <code class="inline-code">greet</code> macro so it can use |
| arbitrary name, not only ``Joe''. For this purpose you can use |
| <strong>parameters</strong>. You define the |
| parameters after the name of the macro in the |
| <code class="inline-code">macro</code> directive. Here we define one parameter for |
| the <code class="inline-code">green</code> macro, |
| <code class="inline-code">person</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro greet <strong>person</strong>> |
| <font size="+2">Hello <strong>${person}</strong>!</font> |
| </#macro></pre></div> |
| |
| <p>and then you can use this macro as:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet <strong>person="Fred"</strong>/> and <@greet <strong>person="Batman"</strong>/></pre></div> |
| |
| <p>which is similar to HTML syntax. This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <font size="+2">Hello <strong>Fred</strong>!</font> |
| and <font size="+2">Hello <strong>Batman</strong>!</font> |
| </pre></div> |
| |
| <p>As you can see, the actual value of the macro parameter is |
| accessible in the macro definition body as a variable |
| (<code class="inline-code">person</code>). As with <a href="#gloss.predefinedDirective">predefined directives</a>, |
| the value of a parameter (the right side of <code class="inline-code">=</code>) is |
| an <a href="#dgui_template_exp">FTL expression</a>. Thus, |
| unlike with HTML, the quotation marks around |
| <code class="inline-code">"Fred"</code> and <code class="inline-code">"Batman"</code> are not |
| optional. <code class="inline-code"><@greet person=Fred/></code> would mean |
| that you use the value of variable <code class="inline-code">Fred</code> for the |
| <code class="inline-code">person</code> parameter, rather than the string |
| <code class="inline-code">"Fred"</code>. Of course parameter value need not be a |
| string, it can be number, boolean, hash, sequence, ...etc., also you |
| can use complex expression on the left side of <code class="inline-code">=</code> |
| (e.g. <code class="inline-code">someParam=(price + 50)*1.25</code>).</p> |
| |
| <p>User-defined directives can have multiple parameters. For |
| example, add a new parameter <code class="inline-code">color</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro greet person <strong>color</strong>> |
| <font size="+2" color="${color}">Hello ${person}!</font> |
| </#macro></pre></div> |
| |
| <p>and then you can use this macro like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet person="Fred" color="black"/></pre></div> |
| |
| <p>The order of parameters is not important, so this is |
| equivalent with the previous:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet color="black" person="Fred"/></pre></div> |
| |
| <p>When you call the macro, you can use only parameters that you |
| have defined in the <code class="inline-code">macro</code> directive (in this |
| case: <code class="inline-code">person</code> and <code class="inline-code">color</code>). So if |
| you try <code class="inline-code"><@greet person="Fred" color="black" |
| background="green"/></code> then you will get an error, since |
| you haven't mentioned parameter <code class="inline-code">background</code> in the |
| <code class="inline-code"><#macro |
| <em class="code-color">...</em>></code>.</p> |
| |
| <p>Also, you must give value for all parameters that you have |
| defined for the macro. So if you try <code class="inline-code"><@greet |
| person="Fred"/></code> then you will get an error, since you |
| forgot to specify the value of <code class="inline-code">color</code>. However, it |
| often happens that you would specify the same value for a parameter |
| in most cases, so you want to specify the value only when you want a |
| different value for it than the usual. This can be achieved if you |
| specify the parameter in the <code class="inline-code">macro</code> directive as |
| <code class="inline-code"><em class="code-color">param_name</em>=<em class="code-color">usual_value</em></code>. |
| For example, you want to use <code class="inline-code">"black"</code> for |
| <code class="inline-code">color</code> if you don't specify value for that |
| parameter when you use the <code class="inline-code">greet</code> |
| directive:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro greet person color<strong>="black"</strong>> |
| <font size="+2" color="${color}">Hello ${person}!</font> |
| </#macro></pre></div> |
| |
| <p>Now <code class="inline-code"><@greet person="Fred"/></code> is OK, |
| since it is equivalent with <code class="inline-code"><@greet person="Fred" |
| color="black"/></code>, thus the value of |
| <code class="inline-code">color</code> parameter is known. If you want |
| <code class="inline-code">"red"</code> for <code class="inline-code">color</code>, then you |
| write <code class="inline-code"><@greet person="Fred" color="red"/></code>, |
| and this value will override the usual value specified with the |
| <code class="inline-code">macro</code> directive, so the value of |
| <code class="inline-code">color</code> parameter will be |
| <code class="inline-code">"red"</code>.</p> |
| |
| <p>Also, it is important to realize that -- according to the |
| already explained <a href="#dgui_template_exp">FTL expression |
| rules</a> -- <code class="inline-code">someParam=foo</code> and |
| <code class="inline-code">someParam="${foo}"</code> are very different. In the |
| fist case, you use the value of variable <code class="inline-code">foo</code> as |
| the value of the parameter. In the second case, you use a <a href="#dgui_template_exp_stringop_interpolation">string literal |
| with interpolation</a>, so the value of the parameter will be a |
| string -- in this case, the value of <code class="inline-code">foo</code> rendered |
| to text -- regardless of the type (as number, date, etc.) of |
| <code class="inline-code">foo</code>. Or, another example: |
| <code class="inline-code">someParam=3/4</code> and |
| <code class="inline-code">someParam="${3/4}"</code> are different. If the |
| directive wants a numerical value for <code class="inline-code">someParam</code>, |
| it will not like the second variation. Do not exchange these.</p> |
| |
| <p>A very important aspect of macro parameters is that they are |
| local variables. For more information about local variables please |
| read: <a href="#dgui_misc_var">Defining variables in the template</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_23">Nested content</h5> |
| |
| |
| <p>Custom directive can have nested content, similarly as |
| predefined directives like <code class="inline-code"><#if |
| <em class="code-color">...</em>><em class="code-color">nested |
| content</em></#if></code> can have. For example, |
| this creates a macro that draws borders around its nested |
| content:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro border> |
| <table border=4 cellspacing=0 cellpadding=4><tr><td> |
| <strong><#nested></strong> |
| </tr></td></table> |
| </#macro></pre></div> |
| |
| <p>The <code class="inline-code"><#nested></code> directive executes the |
| template fragment between the start-tag and end-tags of the |
| directive. So if you do this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@border>The bordered text</@border></pre></div> |
| |
| <p>the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <table border=4 cellspacing=0 cellpadding=4><tr><td> |
| The bordered text |
| </td></tr></table> |
| </pre></div> |
| |
| <p>The <code class="inline-code">nested</code> directive can be called for |
| multiple times, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro do_thrice><strong> |
| <#nested> |
| <#nested> |
| <#nested></strong> |
| </#macro> |
| <@do_thrice> |
| Anything. |
| </@do_thrice></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Anything. |
| Anything. |
| Anything.</pre></div> |
| |
| <p>If you don't use the nested directive, then the nested content |
| will not be executed. Thus, if you accidentally use the |
| <code class="inline-code">greet</code> directive like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@greet person="Joe"> |
| Anything. |
| </@greet></pre></div> |
| |
| <p>then FreeMarker will not see this as an error, and simply |
| prints:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><font size="+2">Hello Joe!</font></pre></div> |
| |
| <p>and the nested content will be ignored, since the |
| <code class="inline-code">greet</code> macro never uses <code class="inline-code">nested</code> |
| directive.</p> |
| |
| <p>The nested content can be anything that is valid FTL, |
| including other user-defined directives. Thus this is OK:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@border> |
| <ul> |
| <@do_thrice> |
| <li><@greet person="Joe"/> |
| </@do_thrice> |
| </ul> |
| </@border></pre></div> |
| |
| <p>and will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <table border=4 cellspacing=0 cellpadding=4><tr><td> |
| <ul> |
| <li><font size="+2">Hello Joe!</font> |
| |
| <li><font size="+2">Hello Joe!</font> |
| |
| <li><font size="+2">Hello Joe!</font> |
| |
| </ul> |
| |
| </tr></td></table></pre></div> |
| |
| <p>The <a href="#dgui_misc_var">local variables</a> of a |
| macro are not visible in the nested content. Say, this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro repeat count> |
| <#local y = "test"> |
| <#list 1..count as x> |
| ${y} ${count}/${x}: <#nested> |
| </#list> |
| </#macro> |
| <@repeat count=3>${y!"?"} ${x!"?"} ${count!"?"}</@repeat></pre></div> |
| |
| <p>will print this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> test 3/1: ? ? ? |
| test 3/2: ? ? ? |
| test 3/3: ? ? ?</pre></div> |
| |
| <p>because the <code class="inline-code">y</code>, <code class="inline-code">x</code> and |
| <code class="inline-code">count</code> are the local (private) variables of the |
| macro, and are not visible from outside the macro definition. |
| Furthermore, a different set of local variables is used for each |
| macro call, so this will not cause confusion:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test foo>${foo} (<#nested>) ${foo}</#macro> |
| <@test foo="A"><@test foo="B"><@test foo="C"/></@test></@test></pre></div> |
| |
| <p>and will print this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">A (B (C () C) B) A</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_misc_userdefdir_loopvar">Macros with loop variables</h5> |
| |
| |
| |
| |
| <p>Predefined directives like <code class="inline-code">list</code> can use |
| so-called loop variables; you should read <a href="#dgui_misc_var">Defining variables in the template</a> to understand loop variables.</p> |
| |
| <p>User-defined directives can also have loop variables. For |
| example, let's extend the <code class="inline-code">do_thrice</code> directive of |
| the earlier examples so it exposes the current repetition number as |
| a loop variable. As with the predefined directives (as |
| <code class="inline-code">list</code>) the <em>name</em> of loop |
| variables is given when you call the directive (as |
| <code class="inline-code">foo</code> in <code class="inline-code"><#list foos as |
| foo><em class="code-color">...</em></#list></code>), |
| while the <em>value</em> of the variables is set by the |
| directive itself.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro do_thrice> |
| <#nested <strong>1</strong>> |
| <#nested <strong>2</strong>> |
| <#nested <strong>3</strong>> |
| </#macro> |
| <@do_thrice <strong>; x</strong>> <#-- user-defined directive uses ";" instead of "as" --> |
| ${<strong>x</strong>} Anything. |
| </@do_thrice></pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1 Anything. |
| 2 Anything. |
| 3 Anything. |
| </pre></div> |
| |
| <p>The syntactical rule is that you pass the actual value of the |
| loop variable for a certain "loop" (i.e. repetition of the nested |
| content) as the parameter of <code class="inline-code">nested</code> directive (of |
| course the parameter can by arbitrary expression). The name of the |
| loop variable is specified in the user-defined directive open tag |
| (<code class="inline-code"><@...></code>) after the parameters and a |
| semicolon.</p> |
| |
| <p>A macro can use more the one loop variable (the order of |
| variables is significant):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro repeat count> |
| <#list 1..count as x> |
| <#nested <strong>x, x/2, x==count</strong>> |
| </#list> |
| </#macro> |
| <@repeat count=4 ; <strong>c, halfc, last</strong>> |
| ${<strong>c</strong>}. ${<strong>halfc</strong>}<#if <strong>last</strong>> Last!</#if> |
| </@repeat></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1. 0.5 |
| 2. 1 |
| 3. 1.5 |
| 4. 2 Last! |
| </pre></div> |
| |
| <p>It is not a problem if you specify different number of loop |
| variables in the user-defined directive start-tag (that is, after |
| the semicolon) than with the <code class="inline-code">nested</code> directive. If |
| you specify less loop variables after the semicolon, then simply you |
| will not see the last few values that the <code class="inline-code">nested</code> |
| directive provides, since there is no loop variable to hold those |
| values. So these are all OK:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@repeat count=4 ; <strong>c, halfc, last</strong>> |
| ${c}. ${halfc}<#if last> Last!</#if> |
| </@repeat> |
| <@repeat count=4 ; <strong>c, halfc</strong>> |
| ${c}. ${halfc} |
| </@repeat> |
| <@repeat count=4> |
| Just repeat it... |
| </@repeat></pre></div> |
| |
| <p>If you specify more variables after the semicolon than with |
| the <code class="inline-code">nested</code> directive, then the last few loop |
| variables will not be created (i.e. will be undefined in the nested |
| content).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_24">More about user-defined directives and macros</h5> |
| |
| |
| <p>Now you may read the relevant parts of the FreeMarker |
| Reference:</p> |
| |
| <ul> |
| <li> |
| <a href="#ref.directive.userDefined">user-defined |
| directive call</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.macro"><code>macro</code> |
| directive</a> |
| </li> |
| </ul> |
| |
| <p>You can define methods in FTL as well, see <a href="#ref.directive.function">the <code>function</code> |
| directive</a>.</p> |
| |
| <p>Also, you may interested in namespaces: <a href="#dgui_misc_namespace">Namespaces</a>. Namespaces help you to organize |
| and reuse your commonly used macros.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_misc_var">Defining variables in the template</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>As we have described, a template can use the variables defined |
| in the data-model. A template can also define variables outside the |
| data-model for its own use. These temporary variables can be created |
| and replaced using FTL directives. Note that each <a href="#gloss.templateProcessingJob">template processing job</a> |
| has its own private set of these variables that exists while the given |
| page is being rendered. This variable set is initially empty, and will |
| be thrown away when the template processing job has been |
| finished.</p> |
| |
| <p>You access a variable that you have defined in the template |
| exactly as if it were a variable in the data-model root. The variable |
| has precedence over any variable of the same name defined in the |
| data-model. That is, if you define a variable called ``foo'' and |
| coincidentally, there is a ``foo'' in the data-model as well, then the |
| variable created in the template will hide (not overwrite!) the |
| variable in the data-model root. For example, |
| <code class="inline-code">${foo}</code> will print the value of the variable created |
| in the template.</p> |
| |
| <p>There are 3 kind of variables that are defined in a |
| template:</p> |
| |
| <ul> |
| <li> |
| <p><strong>``plain'' variables</strong>: They |
| are accessible from everywhere in the template, or from the |
| templates inserted with <code class="inline-code">include</code> directive. You |
| can create and replace these variables with the <a href="#ref.directive.assign"><code>assign</code></a> or |
| <a href="#ref.directive.macro"><code>macro</code> |
| directives</a>.</p> |
| </li> |
| |
| <li> |
| <p><strong>Local variables</strong>: They can |
| only be set inside a <a href="#gloss.macroDefinitionBody">macro definition body</a>, |
| and are only visible from there. A local variable only exists for |
| the duration of a macro call. You can create and replace local |
| variables inside macro definition bodies with the <a href="#ref.directive.local"><code>local</code> |
| directive</a>.</p> |
| </li> |
| |
| <li> |
| <p><strong>Loop variables</strong>: Loop |
| variables are created automatically by directives like <a href="#ref.directive.list"><code>list</code></a>, and |
| they only exist between the start-tag and end-tag of the |
| directive. <a href="#ref.directive.macro">Macro</a> |
| parameters are local variables, not loop variables.</p> |
| </li> |
| </ul> |
| |
| <p>Example: Create and replace variables with |
| <code class="inline-code">assign</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = 1> <#-- create variable x --> |
| ${x} |
| <#assign x = x + 3> <#-- replace variable x --> |
| ${x}</pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1 |
| 4</pre></div> |
| |
| <p>Local variables hide (not overwrite) ``plain'' variables of the |
| same name. Loop variables hide (not overwrite) local and ``plain'' |
| variables of the same name. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = "plain"> |
| 1. ${x} <#-- we see the plain var. here --> |
| <@test/> |
| 6. ${x} <#-- the value of plain var. was not changed --> |
| <#list ["loop"] as x> |
| 7. ${x} <#-- now the loop var. hides the plain var. --> |
| <#assign x = "plain2"> <#-- replace the plain var, hiding does not mater here --> |
| 8. ${x} <#-- it still hides the plain var. --> |
| </#list> |
| 9. ${x} <#-- the new value of plain var. --> |
| |
| <#macro test> |
| 2. ${x} <#-- we still see the plain var. here --> |
| <#local x = "local"> |
| 3. ${x} <#-- now the local var. hides it --> |
| <#list ["loop"] as x> |
| 4. ${x} <#-- now the loop var. hides the local var. --> |
| </#list> |
| 5. ${x} <#-- now we see the local var. again --> |
| </#macro></pre></div> |
| |
| <p>the output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1. plain |
| 2. plain |
| 3. local |
| 4. loop |
| 5. local |
| 6. plain |
| 7. loop |
| 8. loop |
| 9. plain2 |
| </pre></div> |
| |
| <p>An inner loop variable can hide an outer loop variable:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list ["loop 1"] as x> |
| ${x} |
| <#list ["loop 2"] as x> |
| ${x} |
| <#list ["loop 3"] as x> |
| ${x} |
| </#list> |
| ${x} |
| </#list> |
| ${x} |
| </#list></pre></div> |
| |
| <p>the output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> loop 1 |
| loop 2 |
| loop 3 |
| loop 2 |
| loop 1</pre></div> |
| |
| <p>Note that the value of a loop variable is set by the directive |
| invocation that has created it (the <code class="inline-code"><list |
| <em class="code-color">...</em>></code> tags in this case). There |
| is no other way to change the value of a loop variable (say, you can't |
| change its value with some kind of assignment directive). You can hide |
| temporarily a loop variable with another loop variable though, as you |
| have seen above.</p> |
| |
| <p>Sometimes it happens that a variable hides the variable in the |
| data-model with the same name, but you want to read the variable of |
| the data-model. In this case you can use the <a href="#dgui_template_exp_var_special">special variable</a> |
| <code class="inline-code">globals</code>. For example, assume we have a variable |
| called <code class="inline-code">user</code> in the data-model with value ``Big |
| Joe'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign user = "Joe Hider"> |
| ${user} <#-- prints: Joe Hider --> |
| ${.globals.user} <#-- prints: Big Joe --></pre></div> |
| |
| <p>For information about syntax of variables please read: <a href="#dgui_template_exp">The Template/Expressions</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_misc_namespace">Namespaces</h4> |
| |
| |
| |
| |
| |
| |
| <p>When you run FTL templates, you have a (possibly empty) set of |
| variables that you have created with <code class="inline-code">assign</code> and |
| <code class="inline-code">macro</code> directives, as can be seen from the <a href="#dgui_misc_var">previous chapter</a>. A set of variables |
| like this is called a <strong>namespace</strong>. In |
| simple cases you use only one namespace, the so-called <strong>main namespace</strong>. You don't realize this, since |
| normally you use only this namespace.</p> |
| |
| <p>But if you want to build reusable collection of macros, |
| functions and other variables -- usually referred as <strong>library</strong> by lingo -- the usage of multiple |
| namespaces becomes inevitable. Just consider if you have a big |
| collection of macros, that you use in several projects, or even you |
| want to share it with other people. It becomes impossible to be sure |
| that the library does not have a macro (or other variable) with the |
| same name as the name of a variable in the data-model, or with the |
| same name as a the name of a variable in another library used in the |
| template. In general, variables can clobber each other because of the |
| name clashes. So you should use a separate namespace for the variables |
| of each library.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_25">Creating a library</h5> |
| |
| |
| <p>Let's create a simple library. Assume you commonly need the |
| variables <code class="inline-code">copyright</code> and <code class="inline-code">mail</code> |
| (before you ask, macros <em>are</em> variables):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro copyright date> |
| <p>Copyright (C) ${date} Julia Smith. All rights reserved.</p> |
| </#macro> |
| |
| <#assign mail = "jsmith@acme.com"></pre></div> |
| |
| <p>Store the above in the file <code class="inline-code">lib/my_test.ftl</code> |
| (in the directory where you store the templates). Assume you want to |
| use this in <code class="inline-code">aWebPage.ftl</code>. If you use |
| <code class="inline-code"><#include "/lib/my_test.ftl"></code> in the |
| <code class="inline-code">aWebPage.ftl</code>, then it will create the two |
| variables in the main namespace, and it is not good now, since you |
| want them to be in a namespace that is used exclusively by the ``My |
| Test Library''. Instead of <code class="inline-code">include</code> you have to |
| use <a href="#ref.directive.import"><code>import</code> |
| directive</a>. This directive is, at the first glance, similar to |
| <code class="inline-code">include</code>, but it will create an empty namespace |
| for <code class="inline-code">lib/my_test.ftl</code> and will execute that there. |
| <code class="inline-code">lib/my_test.ftl</code> will find itself in an clean new |
| world, where only the variables of data-model are present (since |
| they are visible from everywhere), and will create the two variables |
| in this new world. That's fine for now, but you want to access the |
| two variables from <code class="inline-code">aWebPage.ftl</code>, and that uses |
| the main namespace, so it can't see the variables of the other |
| namespace. The solution is that the <code class="inline-code">import</code> |
| directive not only creates the new namespace, but a new hash |
| variable in the namespace used by the caller of |
| <code class="inline-code">import</code> (the main namespace in this case), that |
| will act as a gate into the newly created namespace. So this is how |
| <code class="inline-code">aWebPage.ftl</code> will look like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/my_test.ftl" as <strong>my</strong>> <#-- the hash called "my" will be the "gate" --> |
| <@<strong>my</strong>.copyright date="1999-2002"/> |
| ${<strong>my</strong>.mail}</pre></div> |
| |
| <p>Note how it accesses the variables in the namespace created |
| for <code class="inline-code">/lib/my_test.ftl</code> using the newly created |
| namespace accessing hash, <code class="inline-code">my</code>. This will |
| print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>Copyright (C) 1999-2002 Julia Smith. All rights reserved.</p> |
| jsmith@acme.com</pre></div> |
| |
| <p>If you would have a variable called <code class="inline-code">mail</code> or |
| <code class="inline-code">copyright</code> in the main namespace, that would not |
| cause any confusion, since the two templates use separated |
| namespaces. For example, modify the <code class="inline-code">copyright</code> |
| macro in <code class="inline-code">lib/my_test.ftl</code> to this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro copyright date> |
| <p>Copyright (C) ${date} Julia Smith. All rights reserved. |
| <br>Email: <strong>${mail}</strong></p> |
| </#macro></pre></div> |
| |
| <p>and then replace <code class="inline-code">aWebPage.ftl</code> with |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/my_test.ftl" as my> |
| <strong><#assign mail="fred@acme.com"></strong> |
| <@my.copyright date="1999-2002"/> |
| ${my.mail} |
| ${mail}</pre></div> |
| |
| <p>and the output will be this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>Copyright (C) 1999-2002 Julia Smith. All rights reserved. |
| <br>Email: <strong>jsmith@acme.com</strong></p> |
| jsmith@acme.com |
| fred@acme.com</pre></div> |
| |
| <p>This is like that because when you have called the |
| <code class="inline-code">copyright</code> macro, FreeMarker has temporarily |
| switch to the namespace that was created by the |
| <code class="inline-code">import</code> directive for |
| <code class="inline-code">/lib/my_test.ftl</code>. Thus, the |
| <code class="inline-code">copyright</code> macro always sees the |
| <code class="inline-code">mail</code> variable that exists there, and not the |
| other <code class="inline-code">mail</code> that exists in the main |
| namespace.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_26">Writing the variables of imported namespaces</h5> |
| |
| |
| <p>Occasionally you may want to create or replace a variable in |
| an imported namespace. You can do this with the |
| <code class="inline-code">assign</code> directive, if you use its |
| <code class="inline-code">namespace</code> parameter. For example, this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/my_test.ftl" as my> |
| ${my.mail} |
| <#assign mail="jsmith@other.com" <strong>in my</strong>> |
| ${my.mail}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">jsmith@acme.com |
| jsmith@other.com</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_27">Namespaces and data-model</h5> |
| |
| |
| <p>The variables of the data-model are visible from everywhere. |
| For example, if you have a variable called <code class="inline-code">user</code> |
| in the data-model, <code class="inline-code">lib/my_test.ftl</code> will access |
| that, exactly as <code class="inline-code">aWebPage.ftl</code> does:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro copyright date> |
| <p>Copyright (C) ${date} <strong>${user}</strong>. All rights reserved.</p> |
| </#macro> |
| |
| <#assign mail = "<strong>${user}</strong>@acme.com"></pre></div> |
| |
| <p>If <code class="inline-code">user</code> is ``Fred'', then the usual |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/my_test.ftl" as my> |
| <@my.copyright date="1999-2002"/> |
| ${my.mail}</pre></div> |
| |
| <p>will print this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>Copyright (C) 1999-2002 Fred. All rights reserved.</p> |
| Fred@acme.com</pre></div> |
| |
| <p>Don't forget that the variables in the namespace (the |
| variables you create with <code class="inline-code">assign</code> or |
| <code class="inline-code">macro</code> directives) have precedence over the |
| variables of the data-model when you are in that namespace. Thus, |
| the contents of data-model does not interfere with the variables |
| created by the library.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>In some unusual applications you want to create variables in |
| the template those are visible from all namespaces, exactly like |
| the variables of the data-model. But you can't change the |
| data-model with templates. Still, it is possible to achieve |
| similar result with the <code class="inline-code">global</code> directive; read |
| the <a href="#ref.directive.global">reference</a> for more |
| details.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_28">The life-cycle of namespaces</h5> |
| |
| |
| <p>A namespace is identified by the path that was used with the |
| <code class="inline-code">import</code> directive. If you try to |
| <code class="inline-code">import</code> with the same path for multiple times, it |
| will create the namespace and run the template specified by the path |
| for the very first invocation of <code class="inline-code">import</code> only. The |
| later <code class="inline-code">import</code>s with the same path will just create |
| a ``gate'' hash to the same namespace. For example, let this be the |
| <code class="inline-code">aWebPage.ftl</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/my_test.ftl" as my> |
| <#import "/lib/my_test.ftl" as foo> |
| <#import "/lib/my_test.ftl" as bar> |
| ${my.mail}, ${foo.mail}, ${bar.mail} |
| <#assign mail="jsmith@other.com" in my> |
| ${my.mail}, ${foo.mail}, ${bar.mail}</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">jsmith@acme.com, jsmith@acme.com, jsmith@acme.com |
| jsmith@other.com, jsmith@other.com, jsmith@other.com</pre></div> |
| |
| <p>since you see the same namespace through |
| <code class="inline-code">my</code>, <code class="inline-code">foo</code> and |
| <code class="inline-code">bar</code>.</p> |
| |
| <p>Note that namespaces are not hierarchical, they exist |
| independently of each other. That is, if you |
| <code class="inline-code">import</code> namespace N2 while you are in name space |
| N1, N2 will not be inside N1. N1 just gets a hash by which it can |
| access N2. This is the same N2 namespace that you would access if, |
| say, you <code class="inline-code">import</code> N2 when you are in the main |
| namespace.</p> |
| |
| <p>Each <a href="#gloss.templateProcessingJob">template |
| processing job</a> has its own private set of namespaces. Each |
| template-processing job is a separated cosmos that exists only for |
| the short period of time while the given page is being rendered, and |
| then it vanishes with all its populated namespaces. Thus, whenever |
| we say that ``<code class="inline-code">import</code> is called for the first |
| time'' and such, we are always talking in the context of a single |
| template processing job.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_29">Writing libraries for other people</h5> |
| |
| |
| |
| |
| <p>If you have written a good quality library that can be useful |
| for other people, you may want to make it available on the Internet |
| (like on <a href="http://freemarker.org/libraries.html">http://freemarker.org/libraries.html</a>). |
| To prevent clashes with the names of libraries used by other |
| authors, and to make it easy to write libraries that import other |
| published libraries, there is a de-facto standard that specifies the |
| format of library paths. The standard is that the library must be |
| available (importable) for templates and other libraries with a path |
| like this:</p> |
| |
| <p><code class="inline-code">/lib/<em class="code-color">yourcompany.com</em>/<em class="code-color">your_library</em>.ftl</code></p> |
| |
| <p>For example if you work for Example Inc. that owns the |
| www.example.com homepage, and you develop a widget library, then the |
| path of the FTL file to import should be:</p> |
| |
| <p><code class="inline-code">/lib/example.com/widget.ftl</code></p> |
| |
| <p>Note that the www is omitted. The part after the 3rd slash can |
| contain subdirectories such as:</p> |
| |
| <p><code class="inline-code">/lib/example.com/commons/string.ftl</code></p> |
| |
| <p>An important rule is that the path should not contain |
| upper-case letters. To separate words, use <code class="inline-code">_</code>, as |
| in <code class="inline-code">wml_form</code> (not |
| <code class="inline-code">wmlForm</code>).</p> |
| |
| <p>Note that if you do not develop the library for a company or |
| organization, you should use the URL of the project homepage, such |
| as <code class="inline-code">/lib/example.sourceforge.net/example.ftl</code>, or |
| <code class="inline-code">/lib/geocities.com/jsmith/example.ftl</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_misc_whitespace">White-space handling</h4> |
| |
| |
| |
| |
| <p>The control of the <a href="#gloss.whiteSpace">white-space</a> in a template is a |
| problem that to some extent haunts every template engine in the |
| business.</p> |
| |
| <p>Let see this template. I have marked the components of template |
| with colors: <span class="marked-text">text</span>, <span class="marked-interpolation">interpolation</span>, <span class="marked-ftl-tag">FTL tag</span>. With the <em><span class="marked-invisible-text">[BR]</span></em>-s I visualize the <a href="#gloss.lineBreak">line breaks</a>.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#assign users = [{"name":"Joe", "hidden":false},<em><span class="marked-invisible-text">[BR]</span></em> |
| {"name":"James Bond", "hidden":true},<em><span class="marked-invisible-text">[BR]</span></em> |
| {"name":"Julia", "hidden":false}]></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#list users as user></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#if !user.hidden></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <li><span class="marked-interpolation">${user.name}</span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"></#if></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"></#list></span><em><span class="marked-invisible-text">[BR]</span></em> |
| </ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>That's all.</span></pre></div> |
| |
| <p>If FreeMarker were to output all <span class="marked-text">text</span> as is, the output would be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <li></span>Joe<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <li></span>Julia<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| <em><span class="marked-invisible-text">[BR]</span></em> |
| </ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>That's all.</span></pre></div> |
| |
| <p>You have a lot of unwanted spaces and line breaks here. |
| Fortunately neither HTML nor XML is typically white-space sensitive, |
| but this amount of superfluous white-space can be annoying, and |
| needlessly increases the size of produced HTML. Of course, it is even |
| bigger problem when outputting white-space-sensitive formats.</p> |
| |
| <p>FreeMarker provides the following tools to cope with this |
| problem:</p> |
| |
| <ul> |
| <li> |
| <p>Tools to ignore certain white-space of the template files |
| <span class="marked-for-programmers">(parse time white-space |
| removal)</span>:</p> |
| |
| <ul> |
| <li> |
| <p>White-space stripping: This feature automatically |
| ignores typical superfluous white-space around FTL tags. It |
| can be enabled or disabled on per template manner.</p> |
| </li> |
| |
| <li> |
| <p>Trimmer directives: <code class="inline-code">t</code>, |
| <code class="inline-code">rt</code>, <code class="inline-code">lt</code>. With these |
| directives you can explicitly tell FreeMarker to ignore |
| certain white-space. Read <a href="#ref.directive.t">the |
| reference</a> for more information.</p> |
| </li> |
| |
| <li> |
| <p><a href="#ref.directive.ftl"><code>ftl</code></a> |
| parameter <code class="inline-code">strip_text</code>. This removes all |
| top-level text from the template. It is useful for templates |
| that contain macro definitions only (and some other |
| non-outputting directives), because it removes the line-breaks |
| that you use between the macro definitions and between the |
| other top-level directives to improve the readability of the |
| template.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Tools that remove white-space from the output <span class="marked-for-programmers">(on-the-fly white-space |
| removal)</span>:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">compress</code> directive.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="dgui_misc_whitespace_stripping">White-space stripping</h5> |
| |
| |
| |
| |
| <p>If this feature is enabled for a template, then it |
| automatically ignores (i.e. does not print to the output) two kind |
| of typical superfluous white-space:</p> |
| |
| <ul> |
| <li> |
| <p>Indentation white-space, and trailing white-space at the |
| end of the line (includes the line break) will be ignored in |
| lines that contains only FTL tags (e.g. |
| <code class="inline-code"><@myMacro/></code>, <code class="inline-code"><#if |
| <em class="code-color">...</em>></code>) and/or FTL |
| comments (e.g. <code class="inline-code"><#-- blah --></code>), apart |
| from the the ignored white-space itself. For example, if a line |
| contains only an <code class="inline-code"><#if |
| <em class="code-color">...</em>></code>, then the |
| indentation before the tag and the line break after the tag will |
| be ignored. However, if the line contains <code class="inline-code"><#if |
| <em class="code-color">...</em>>x</code>, then the |
| white-space in that line will not be ignored, because of the |
| <code class="inline-code">x</code>, as that is not FTL tag. Note that |
| according these rules, a line that contains <code class="inline-code"><#if |
| <em class="code-color">...</em>><#list |
| <em class="code-color">...</em>></code> is subject to |
| white-space ignoring, while a line that contains |
| <code class="inline-code"><#if <em class="code-color">...</em>> <#list |
| <em class="code-color">...</em>></code> is not, because the |
| white-space between the two FTL tags is embedded white-space, |
| not indentation or trailing white-space.</p> |
| </li> |
| |
| <li> |
| <p>White-space sandwiched between the following directives is |
| ignored: <code class="inline-code">macro</code>, <code class="inline-code">function</code>, |
| <code class="inline-code">assign</code>, <code class="inline-code">global</code>, |
| <code class="inline-code">local</code>, <code class="inline-code">ftl</code>, |
| <code class="inline-code">import</code>, but only if there is |
| <em>only</em> white-space and/or FTL comments |
| between the directives. In practice it means that you can put |
| empty lines between macro definitions and assignments as spacing |
| for better readability, without printing needless empty lines |
| (line breaks) to the output.</p> |
| </li> |
| </ul> |
| |
| <p>The output of the last example with white-space stripping |
| enabled will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em> |
| <ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <li></span>Joe<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> |
| <li></span>Julia<span class="marked-text"><em><span class="marked-invisible-text">[BR]</span></em> |
| </ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>That's all.</span></pre></div> |
| |
| <p>This is because after stripping the template becomes the |
| following; the ignored text is not <span class="marked-text">colored</span>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><span class="marked-text"><p>List of users:<em><span class="marked-invisible-text">[BR]</span></em></span> |
| <span class="marked-ftl-tag"><#assign users = [{"name":"Joe", "hidden":false},<em><span class="marked-invisible-text">[BR]</span></em> |
| {"name":"James Bond", "hidden":true},<em><span class="marked-invisible-text">[BR]</span></em> |
| {"name":"Julia", "hidden":false}]></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-text"><ul><em><span class="marked-invisible-text">[BR]</span></em></span> |
| <span class="marked-ftl-tag"><#list users as user></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"><#if !user.hidden></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-text"> <li><span class="marked-interpolation">${user.name}</span><em><span class="marked-invisible-text">[BR]</span></em></span> |
| <span class="marked-ftl-tag"></#if></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-ftl-tag"></#list></span><em><span class="marked-invisible-text">[BR]</span></em> |
| <span class="marked-text"></ul><em><span class="marked-invisible-text">[BR]</span></em> |
| <p>That's all.</span></pre></div> |
| |
| <p>White-space stripping can be enabled/disabled in per template |
| manner with the <a href="#ref.directive.ftl"><code>ftl</code> directive</a>. |
| If you don't specify this with the <code class="inline-code">ftl</code> directive, |
| then white-space stripping will be enabled or disabled depending on |
| how the programmer has configured FreeMarker. The factory default is |
| white-space stripping enabled, and the programmers probably left it |
| so (<span class="marked-for-programmers">recommended</span>). <span class="marked-for-programmers">Note that enabling white-space stripping does |
| <em>not</em> degrade the performance of template |
| execution; white-space stripping is done during template |
| loading.</span></p> |
| |
| <p>White-space stripping can be disabled for a single line with |
| the <a href="#ref.directive.nt"><code>nt</code></a> |
| directive (for No Trim).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_30">Using compress directive</h5> |
| |
| |
| |
| |
| <p>Another solution is to use the <a href="#ref.directive.compress"><code>compress</code> |
| directive</a>. As opposed to white-space stripping, this works |
| directly on the generated output, not on the template. That is, it |
| will investigate the printed output on the fly, and does not |
| investigate the FTL program that creates the output. It aggressively |
| removes indentations, empty lines and repeated spaces/tabs (for more |
| information read the <a href="#ref.directive.compress">reference</a>). So the output |
| of:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#compress></strong> |
| <#assign users = [{"name":"Joe", "hidden":false}, |
| {"name":"James Bond", "hidden":true}, |
| {"name":"Julia", "hidden":false}]> |
| List of users: |
| <#list users as user> |
| <#if !user.hidden> |
| - ${user.name} |
| </#if> |
| </#list> |
| That's all. |
| <strong></#compress></strong></pre></div> |
| |
| <p>will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">List of users: |
| - Joe |
| - Julia |
| That's all.</pre></div> |
| |
| <p>Note that <code class="inline-code">compress</code> is totally independent |
| of white-space stripping. So it is possible that the white-space of |
| template is stripped, and later the produced output is |
| <code class="inline-code">compress</code>-ed.</p> |
| |
| <p>Also, by default a user-defined directve called |
| <code class="inline-code">compress</code> is available in the data-model (due to |
| backward compatibility). This is the same as the directive, except |
| that you may optionally set the <code class="inline-code">single_line</code> |
| parameter, which will remove all intervening line breaks. If you |
| replace |
| <code class="inline-code"><#compress><em class="code-color">...</em></#compress></code> |
| on the last example with <code class="inline-code"><@compress |
| single_line=true><em class="code-color">...</em></@compress></code>, |
| then you get this output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">List of users: - Joe - Julia That's all.</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="dgui_misc_alternativesyntax">Alternative (square bracket) syntax</h4> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This feature exists since FreeMarker 2.3.4.</p> |
| </div> |
| |
| |
| <p>FreeMarker supports an alternative syntax, where |
| <code class="inline-code">[</code> and <code class="inline-code">]</code> is used instead of |
| <code class="inline-code"><</code> and <code class="inline-code">></code> in FreeMarker |
| directives and comments, for example:</p> |
| |
| <ul> |
| <li> |
| Calling predefined directive: <code class="inline-code">[#list animals as |
| being]<em class="code-color">...</em>[/#list]</code> |
| </li> |
| |
| <li> |
| Calling user-defined directive: <code class="inline-code">[@myMacro |
| /]</code> |
| </li> |
| |
| <li> |
| Comment: <code class="inline-code">[#-- the comment --]</code> |
| </li> |
| </ul> |
| |
| <p>To use the alternative syntax instead of the default one, start |
| the template with the <a href="#ref_directive_ftl"><code>ftl</code> directive</a> |
| using the alternative syntax. If you don't know what is the |
| <code class="inline-code">ftl</code> directive, just start the template with |
| <code class="inline-code">[#ftl]</code>, and remember that it should be the very |
| first thing in the file (except that <a href="#gloss.whiteSpace">white-space</a> can precede it). For |
| example, this is how the last example of the <a href="#dgui_quickstart_template">Getting Started</a> looks with |
| the alternative syntax (assuming it's a complete template, not just a |
| fragment):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong>[#ftl]</strong> |
| <p>We have these animals: |
| <table border=1> |
| <tr><th>Name<th>Price |
| <strong>[#list animals as being]</strong> |
| <tr> |
| <td> |
| <strong>[#if being.size = "large"]</strong><b><strong>[/#if]</strong> |
| ${being.name} |
| <strong>[#if being.size = "large"]</strong></b><strong>[/#if]</strong> |
| <td>${being.price} Euros |
| <strong>[/#list]</strong> |
| </table></pre></div> |
| |
| <p>The alternative (square bracket) and the default (angle bracket) |
| syntax are mutually exclusive within a template. That is, either the |
| whole template uses alternative syntax, or the whole template uses the |
| default syntax. If the template uses alternative syntax, things like |
| <code class="inline-code"><#if <em class="code-color">...</em>></code> are |
| count as static text, not as FTL tags. Similarly, if the template uses |
| the default syntax, things like <code class="inline-code">[#if |
| <em class="code-color">...</em>]</code> count as static text, not as |
| FTL tags.</p> |
| |
| <p>If you start the file with <code class="inline-code">[#ftl |
| <em class="code-color">...</em>]</code> (where the |
| <code class="inline-code"><em class="code-color">...</em></code> stands for the |
| optional parameters; of course <code class="inline-code">[#ftl]</code> works too) |
| the file will surely use the alternative (square bracket) syntax. If |
| you start the file with <code class="inline-code"><#ftl |
| <em class="code-color">...</em>></code> the file will surely use |
| the normal (angle bracket) syntax. If there is no |
| <code class="inline-code">ftl</code> directive in the file, then the programmer |
| decides what the syntax will be by configuring FreeMarker <span class="marked-for-programmers">(programmers see |
| <code class="inline-code">Configuration.setTagSyntax(int)</code> in the API |
| javadocs)</span>. Most probably the programmers use the factory |
| default however. The factory default in 2.3.x is using the normal |
| syntax. The factory default in 2.4.x will be auto-detection, which |
| means that the first FreeMarker tag determines the syntax (it can be |
| anything, not just <code class="inline-code">ftl</code>).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="pgui">Programmer's Guide</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="pgui_quickstart">Getting Started</h3> |
| |
| |
| <p>Note that, if you are new to FreeMarker, you should read at least |
| the <a href="#dgui_quickstart">Template Author's Guide/Getting Started</a> before this chapter.</p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_quickstart_createconfiguration">Create a configuration instance</h4> |
| |
| |
| |
| |
| <p>First you have to create a |
| <code class="inline-code">freemarker.template.Configuration</code> instance and |
| adjust its settings. A <code class="inline-code">Configuration</code> instance is a |
| central place to store the application level settings of FreeMarker. |
| Also, it deals with the creation and caching of pre-parsed |
| templates.</p> |
| |
| <p>Probably you will <em>do it only once</em> at the |
| beginning of the application (possibly servlet) life-cycle:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Configuration cfg = new Configuration(); |
| // Specify the data source where the template files come from. |
| // Here I set a file directory for it: |
| cfg.setDirectoryForTemplateLoading( |
| new File("<em>/where/you/store/templates</em>")); |
| // Specify how templates will see the data-model. This is an advanced topic... |
| // but just use this: |
| cfg.setObjectWrapper(new DefaultObjectWrapper());</pre></div> |
| |
| <p>From now you should use this single configuration instance. Note |
| however that if a system has multiple independent components that use |
| FreeMarker, then of course they will use their own private |
| <code class="inline-code">Configuration</code> instance.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_quickstart_createdatamodel">Create a data-model</h4> |
| |
| |
| |
| |
| <p>In simple cases you can build data-models using |
| <code class="inline-code">java.lang</code> and <code class="inline-code">java.util</code> classes |
| and custom Java Beans:</p> |
| |
| <ul> |
| <li> |
| <p>Use <code class="inline-code">java.lang.String</code> for strings.</p> |
| </li> |
| |
| <li> |
| <p>Use <code class="inline-code">java.lang.Number</code> descents for |
| numbers.</p> |
| </li> |
| |
| <li> |
| <p>Use <code class="inline-code">java.lang.Boolean</code> for boolean |
| values.</p> |
| </li> |
| |
| <li> |
| <p>Use <code class="inline-code">java.util.List</code> or Java arrays for |
| sequences.</p> |
| </li> |
| |
| <li> |
| <p>Use <code class="inline-code">java.util.Map</code> for hashes.</p> |
| </li> |
| |
| <li> |
| <p>Use your custom bean class for hashes where the items |
| correspond to the bean properties. For example the |
| <code class="inline-code">price</code> property of <code class="inline-code">product</code> |
| can be get as <code class="inline-code">product.price</code>. (The actions of |
| the beans can be exposed as well; see much later <a href="#pgui_misc_beanwrapper">here</a>)</p> |
| </li> |
| </ul> |
| |
| <p>For example, let's build the data-model of the <a href="#example.first">first example of the Template Author's |
| Guide</a>. For convenience, here it is again:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- user = "Big Joe" |
| | |
| +- latestProduct |
| | |
| +- url = "products/greenmouse.html" |
| | |
| +- name = "green mouse"</pre></div> |
| |
| <p>This is the Java code fragment that builds this |
| data-model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">// Create the root hash |
| Map root = new HashMap(); |
| // Put string ``user'' into the root |
| root.put("user", "Big Joe"); |
| // Create the hash for ``latestProduct'' |
| Map latest = new HashMap(); |
| // and put it into the root |
| root.put("latestProduct", latest); |
| // put ``url'' and ``name'' into latest |
| latest.put("url", "products/greenmouse.html"); |
| latest.put("name", "green mouse");</pre></div> |
| |
| <p>For the <code class="inline-code">latestProduct</code> you migh as well use a |
| Java Bean that has <code class="inline-code">url</code> and <code class="inline-code">name</code> |
| properties (that is, an object that has public <code class="inline-code">String |
| getURL()</code> and <code class="inline-code">String getName()</code> methods); |
| it's the same from viewpoint of the template.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_quickstart_gettemplate">Get the template</h4> |
| |
| |
| |
| |
| <p>Templates are represented by |
| <code class="inline-code">freemarker.template.Template</code> instances. Typically |
| you obtain a <code class="inline-code">Template</code> instance from the |
| <code class="inline-code">Configuration</code> instance. Whenever you need a |
| template instance you can get it with its |
| <code class="inline-code">getTemplate</code> method. Store <a href="#example.first">the example template</a> in the |
| <code class="inline-code">test.ftl</code> file of the <a href="#pgui_quickstart_createconfiguration">earlier</a> set |
| directory, then you can do this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Template temp = cfg.getTemplate("test.ftl");</pre></div> |
| |
| <p>When you call this, it will create a <code class="inline-code">Template</code> |
| instance corresponds to <code class="inline-code">test.ftl</code>, by reading |
| <code class="inline-code"><em class="code-color">/where/you/store/templates/</em>test.ftl</code> |
| and parsing (compile) it. The <code class="inline-code">Template</code> instance |
| stores the template in the parsed form, and not as text.</p> |
| |
| <p><code class="inline-code">Configuration</code> caches |
| <code class="inline-code">Template</code> instances, so when you get |
| <code class="inline-code">test.ftl</code> again, it probably will not create new |
| <code class="inline-code">Template</code> instance (thus doesn't read and parse the |
| file), just returns the same instance as for the first time.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_quickstart_merge">Merging the template with the data-model</h4> |
| |
| |
| |
| |
| |
| |
| <p>As we know, data-model + template = output, and we have a |
| data-model (<code class="inline-code">root</code>) and a template |
| (<code class="inline-code">temp</code>), so to get the output we have to merge them. |
| This is done by the <code class="inline-code">process</code> method of the template. |
| It takes the data-model root and a <code class="inline-code">Writer</code> as |
| parameters. It writes the produced output to the |
| <code class="inline-code">Writer</code>. For the sake of simplicity here I write to |
| the standard output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Writer out = new OutputStreamWriter(System.out); |
| temp.process(root, out); |
| out.flush();</pre></div> |
| |
| <p>This will print to your terminal the output what you have seen |
| in the <a href="#example.first">first example</a> of the |
| Template Author's Guide.</p> |
| |
| <p>Once you have obtained a <code class="inline-code">Template</code> instance, |
| you can merge it with different data-models for unlimited times |
| (<code class="inline-code">Template</code> instances are basically stateless). Also, |
| the <code class="inline-code">test.ftl</code> file is accessed only while the |
| <code class="inline-code">Template</code> instance is created, not when you call the |
| process method.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_quickstart_all">Putting all together</h4> |
| |
| |
| <p>This is a working source file assembled from the previous |
| fragments. Don't forget to put <code class="inline-code">freemarker.jar</code> into |
| the <code class="inline-code">CLASSPATH</code>.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">import freemarker.template.*; |
| import java.util.*; |
| import java.io.*; |
| |
| public class Test { |
| |
| public static void main(String[] args) throws Exception { |
| |
| /* ------------------------------------------------------------------- */ |
| /* You usually do it only once in the whole application life-cycle: */ |
| |
| /* Create and adjust the configuration */ |
| Configuration cfg = new Configuration(); |
| cfg.setDirectoryForTemplateLoading( |
| new File("<em>/where/you/store/templates</em>")); |
| cfg.setObjectWrapper(new DefaultObjectWrapper()); |
| |
| /* ------------------------------------------------------------------- */ |
| /* You usually do these for many times in the application life-cycle: */ |
| |
| /* Get or create a template */ |
| Template temp = cfg.getTemplate("test.ftl"); |
| |
| /* Create a data-model */ |
| Map root = new HashMap(); |
| root.put("user", "Big Joe"); |
| Map latest = new HashMap(); |
| root.put("latestProduct", latest); |
| latest.put("url", "products/greenmouse.html"); |
| latest.put("name", "green mouse"); |
| |
| /* Merge data-model with template */ |
| Writer out = new OutputStreamWriter(System.out); |
| temp.process(root, out); |
| out.flush(); |
| } |
| }</pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>I have suppressed the exceptions for the sake of simplicity. |
| Don't do it in real products.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="pgui_datamodel">The Data Model</h3> |
| |
| |
| <p>This is just an introductory explanation. See the <a href="api/index.html">FreeMarker Java API documentation</a> for more |
| detailed information.</p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_basics">Basics</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>You have seen how to build a data-model in the <a href="#pgui_quickstart">Getting Started</a> using the standard |
| Java classes (<code class="inline-code">Map</code>, <code class="inline-code">String</code>, |
| etc.). Internally, the variables available in the template are java |
| objects that implement the |
| <code class="inline-code">freemarker.template.TemplateModel</code> interface. But |
| you could use standard java collections as variables in your |
| data-model, because these were replaced with the appropriate |
| <code class="inline-code">TemplateModel</code> instances behind the scenes. This |
| facility is called <strong>object wrapping</strong>. |
| The object wrapping facility can convert <em>any</em> kind |
| of object transparently to the instances of classes that implement |
| <code class="inline-code">TemplateModel</code> interface. This makes it possible, |
| for example, to access <code class="inline-code">java.sql.ResultSet</code> as |
| sequence variable in templates, or to access |
| <code class="inline-code">javax.servlet.ServletRequest</code> objects as a hash |
| variable that contains the request attributes, or even to traverse XML |
| documents as FTL variables (<a href="#xgui">see here</a>). To |
| wrap (convert) these objects, however, you need to plug the proper, so |
| called, object wrapper implementation (possibly your custom |
| implementation); this will be discussed <a href="#pgui_datamodel_objectWrapper">later</a>. The meat for now |
| is that any object that you want to access from the templates, sooner |
| or later must be converted to an object that implements |
| <code class="inline-code">TemplateModel</code> interface. So first you should |
| familiarize yourself with writing of <code class="inline-code">TemplateModel</code> |
| implementations.</p> |
| |
| <p>There is roughly one |
| <code class="inline-code">freemarker.template.TemplateModel</code> descendant |
| interface corresponding to each basic type of variable |
| (<code class="inline-code">TemplateHashModel</code> for hashes, |
| <code class="inline-code">TemplateSequenceModel</code> sequences, |
| <code class="inline-code">TemplateNumberModel</code> for numbers, etc.). For |
| example, if you want to expose a <code class="inline-code">java.sql.ResultSet</code> |
| as a sequence for the templates, then you have to write a |
| <code class="inline-code">TemplateSequenceModel</code> implementation that can read |
| <code class="inline-code">java.sql.ResultSet</code>-s. We used to say on this, that |
| you <em>wrap</em> the |
| <code class="inline-code">java.sql.ResultSet</code> with your |
| <code class="inline-code">TemplateModel</code> implementation, as basically you just |
| encapsulate the <code class="inline-code">java.sql.ResultSet</code> to provide |
| access to it with the common <code class="inline-code">TemplateSequenceModel</code> |
| interface. Note that a class can implement multiple |
| <code class="inline-code">TemplateModel</code> interfaces; this is why FTL variables |
| can have multiple types (see: <a href="#dgui_datamodel_basics">Template Author's Guide/Values, Types/Basics</a>)</p> |
| |
| <p>Note that a trivial implementation of these interfaces is |
| provided with the <code class="inline-code">freemarker.template</code> package. For |
| example, to convert a <code class="inline-code">String</code> to FTL string |
| variable, you can use <code class="inline-code">SimpleScalar</code>, to convert a |
| <code class="inline-code">java.util.Map</code> to FTL hash variable, you can use |
| <code class="inline-code">SimpleHash</code>, etc.</p> |
| |
| <p>An easy way to try your own <code class="inline-code">TemplateModel</code> |
| implementation, is to create an instance of that, and drop it directly |
| into the data-model (as <code class="inline-code">put</code> it into the root hash). |
| The object wrapper will expose it untouched for the template, as it |
| already implements <code class="inline-code">TemplateModel</code>, so no conversion |
| (wrapping) needed. (This trick is also useful in cases when you do not |
| want the object wrapper to try to wrap (convert) a certain |
| object.)</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_scalar">Scalars</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>There are 4 scalar types:</p> |
| |
| <ul> |
| <li> |
| Boolean |
| </li> |
| |
| <li> |
| Number |
| </li> |
| |
| <li> |
| String |
| </li> |
| |
| <li> |
| Date |
| </li> |
| </ul> |
| |
| <p>For each scalar type is a |
| <code class="inline-code">Template<em class="code-color">Type</em>Model</code> |
| interface, where <code class="inline-code"><em class="code-color">Type</em></code> is |
| the name of the type. These interfaces define only one method: |
| <code class="inline-code"><em class="code-color">type</em> |
| getAs<em class="code-color">Type</em>();</code>. This returns the |
| value of the variable with the Java type (<code class="inline-code">boolean</code>, |
| <code class="inline-code">Number</code>, <code class="inline-code">String</code> and |
| <code class="inline-code">Date</code> respectively).</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>For historical reasons the interface for string scalars is |
| called <code class="inline-code">TemplateScalarModel</code>, not |
| <code class="inline-code">TemplateStringModel</code>.</p> |
| </div> |
| |
| |
| <p>A trivial implementation of these interfaces are available in |
| <code class="inline-code">freemarker.template</code> package with |
| <code class="inline-code">Simple<em class="code-color">Type</em></code> class name. |
| However, there is no <code class="inline-code">SimpleBooleanModel</code>; to |
| represent the boolean values you can use the |
| <code class="inline-code">TemplateBooleanModel.TRUE</code> and |
| <code class="inline-code">TemplateBooleanModel.FALSE</code> singletons.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>For historical reasons the class for string scalars is called |
| <code class="inline-code">SimpleScalar</code>, not |
| <code class="inline-code">SimpleString</code>.</p> |
| </div> |
| |
| |
| <p>Scalars are immutable within FTL. When you set the value of a |
| variable in a template, then you replace the |
| <code class="inline-code">Template<em class="code-color">Type</em>Model</code> |
| instance with another instance, and don't change the value stored in |
| the original instance.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_31">Difficulties with the date type</h5> |
| |
| |
| |
| |
| |
| |
| <p>There is a complication around date types, because Java API |
| usually does not differentiate <code class="inline-code">java.util.Date</code>-s |
| that store only the date part (April 4, 2003), only the time part |
| (10:19:18 PM), or both (April 4, 2003 10:19:18 PM). To display a |
| date variable as text correctly, FreeMarker must know what parts of |
| the <code class="inline-code">java.util.Date</code> stores meaningful information, |
| and what parts are unused. Unfortunately, the only place where the |
| Java API cleanly tells this, is with database handling (SQL), |
| because databases typically has separated date, time and timestamp |
| (aka date-time) types, and <code class="inline-code">java.sql</code> has 3 |
| corresponding <code class="inline-code">java.util.Date</code> subclasses for |
| them.</p> |
| |
| <p><code class="inline-code">TemplateDateModel</code> interface has two |
| methods: <code class="inline-code">java.util.Date getAsDate()</code> and |
| <code class="inline-code">int getDateType()</code>. A typical implementation of |
| this interface, stores a <code class="inline-code">java.util.Date</code> object, |
| plus an integer that tells the "database style type". The value of |
| this integer must be a constant from the |
| <code class="inline-code">TemplateDateModel</code> interface: |
| <code class="inline-code">DATE</code>, <code class="inline-code">TIME</code>, |
| <code class="inline-code">DATETIME</code> and <code class="inline-code">UNKNOWN</code>.</p> |
| |
| <p>What is <code class="inline-code">UNKNOWN</code>? As we told earlier, |
| <code class="inline-code">java.lang</code> and <code class="inline-code">java.util</code> |
| classes are usually converted automatically into |
| <code class="inline-code">TemplateModel</code> implementations, be so called |
| object wrappers. If the object wrapper faces a |
| <code class="inline-code">java.util.Date</code>, that is not an instance of a |
| <code class="inline-code">java.sql</code> date class, it can't decide what the |
| "database style type" is, so it uses <code class="inline-code">UNKNOWN</code>. |
| Later, if the template has to use this variable, and the "database |
| style type" is needed for the operation, it will stop with error. To |
| prevent this, for the problematic variables the template author must |
| help FreeMarker to decide the "database style type", by using the |
| <a href="#ref_builtin_date_datetype"><code>date</code>, |
| <code>time</code> or <code>datetime</code> |
| built-ins</a>. Note that if you use <code class="inline-code">string</code> |
| built-in with format parameter, as |
| <code class="inline-code">foo?string("MM/dd/yyyy")</code>, then FreeMarker don't |
| need to know the "database style type".</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_parent">Containers</h4> |
| |
| |
| |
| |
| <p>These are hashes, sequences, and collections.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_32">Hashes</h5> |
| |
| |
| |
| |
| <p>Hashes are java objects that implement |
| <code class="inline-code">TemplateHashModel</code> interface. |
| <code class="inline-code">TemplateHashModel</code> contains two methods: |
| <code class="inline-code">TemplateModel get(String key)</code>, which returns the |
| subvariable of the given name, and <code class="inline-code">boolean |
| isEmpty()</code>, which indicates if the hash has zero |
| subvariable or not. The <code class="inline-code">get</code> method returns null |
| if no subvariable with the given name exists.</p> |
| |
| <p>The <code class="inline-code">TemplateHashModelEx</code> interface extends |
| <code class="inline-code">TemplateHashModel</code>. It adds methods by which <a href="#ref_builtin_values">values</a> and <a href="#ref_builtin_keys">keys</a> built-ins can enumerate the |
| subvariables of the hash.</p> |
| |
| <p>The commonly used implementation is |
| <code class="inline-code">SimpleHash</code>, which implements |
| <code class="inline-code">TemplateHashModelEx</code>. Internally it uses a |
| <code class="inline-code">java.util.Hash</code> to store the subvariables. |
| <code class="inline-code">SimpleHash</code> has methods by which you can add and |
| remove subvariable. These methods should be used to initialize the |
| variable directly after its creation.</p> |
| |
| <p>Containers are immutable within FTL. That is, you can't add, |
| replace or remove the subvariables they contain.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_33">Sequences</h5> |
| |
| |
| |
| |
| <p>Sequences are java objects that implement |
| <code class="inline-code">TemplateSequenceModel</code>. It contains two methods: |
| <code class="inline-code">TemplateModel get(int index)</code> and <code class="inline-code">int |
| size()</code>.</p> |
| |
| <p>The commonly used implementation is |
| <code class="inline-code">SimpleSequence</code>. It uses internally a |
| <code class="inline-code">java.util.List</code> to store its subvariables. |
| <code class="inline-code">SimpleSequence</code> has methods by which you can add |
| subvariables. These methods should be used to populate the sequence |
| directly after its creation.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_34">Collections</h5> |
| |
| |
| |
| |
| <p>Collections are java objects that implement the |
| <code class="inline-code">TemplateCollectionModel</code> interface. That interface |
| has one method: <code class="inline-code">TemplateModelIterator iterator()</code>. |
| The <code class="inline-code">TemplateModelIterator</code> interface is similar to |
| <code class="inline-code">java.util.Iterator</code>, but it returns |
| <code class="inline-code">TemplateModels</code> instead of |
| <code class="inline-code">Object</code>-s, and it can throw |
| <code class="inline-code">TemplateModelException</code>s.</p> |
| |
| <p>The commonly used implementation is |
| <code class="inline-code">SimpleCollection</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_method">Methods</h4> |
| |
| |
| |
| |
| <p>Method variables exposed to a template implement the |
| <code class="inline-code">TemplateMethodModel</code> interface. This contains one |
| method: <code class="inline-code">TemplateModel exec(java.util.List |
| arguments)</code>. When you call a method with a <a href="#dgui_template_exp_methodcall">method call expression</a>, |
| then the <code class="inline-code">exec</code> method will be called. The arguments |
| parameter will contain the values of the FTL method call arguments. |
| The return value of <code class="inline-code">exec</code> gives the value of the FTL |
| method call expression.</p> |
| |
| <p>The <code class="inline-code">TemplateMethodModelEx</code> interface extends |
| <code class="inline-code">TemplateMethodModel</code>. It does not add any new |
| methods. The fact that the object implements this |
| <em>marker</em> interface indicates to the FTL engine that |
| the arguments should be put to the <code class="inline-code">java.util.List</code> |
| directly as <code class="inline-code">TemplateModel</code>-s. Otherwise they will be |
| put to the list as <code class="inline-code">String</code>-s.</p> |
| |
| <p>For obvious reasons there is no default implementation for these |
| interfaces.</p> |
| |
| <p>Example: This is a method, which returns the index within the |
| second string of the first occurrence of the first string, or -1 if |
| the second string doesn't contains the first.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">public class IndexOfMethod implements TemplateMethodModel { |
| |
| public TemplateModel exec(List args) throws TemplateModelException { |
| if (args.size() != 2) { |
| throw new TemplateModelException("Wrong arguments"); |
| } |
| return new SimpleNumber( |
| ((String) args.get(1)).indexOf((String) args.get(0))); |
| } |
| }</pre></div> |
| |
| <p>If you put an instance of this, say, into the root:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("indexOf", new IndexOfMethod());</pre></div> |
| |
| <p>then you can call it in the template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = "something"> |
| ${indexOf("met", x)} |
| ${indexOf("foo", x)}</pre></div> |
| |
| <p>and then the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">2 |
| -1</pre></div> |
| |
| <p>If you need to access the runtime FTL environment (read/write |
| variables, get the current locale, etc.), you can get it with |
| <code class="inline-code">Environment.getCurrentEnvironment()</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_directive">Directives</h4> |
| |
| |
| |
| |
| <p>Java programmers can implement user-defined directives in Java |
| using the <code class="inline-code">TemplateDirectiveModel</code> interface. See in |
| the API documentation.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p><code class="inline-code">TemplateDirectiveModel</code> was introduced in |
| FreeMarker 2.3.11, replacing the soon to be depreciated |
| <code class="inline-code">TemplateTransformModel</code>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_35">Example 1</h5> |
| |
| |
| <p>We will implement a directive which converts all output |
| between its start-tag and end-tag to upper case. Like, this |
| template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">foo |
| <strong><@upper></strong> |
| bar |
| <#-- All kind of FTL is allowed here --> |
| <#list ["red", "green", "blue"] as color> |
| ${color} |
| </#list> |
| baaz |
| <strong></@upper></strong> |
| wombat</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">foo |
| BAR |
| RED |
| GREEN |
| BLUE |
| BAAZ |
| wombat</pre></div> |
| |
| <p>This is the source code of the directive class:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">package com.example; |
| import java.io.IOException; |
| import java.io.Writer; |
| import java.util.Map; |
| |
| import freemarker.core.Environment; |
| import freemarker.template.TemplateDirectiveBody; |
| import freemarker.template.TemplateDirectiveModel; |
| import freemarker.template.TemplateException; |
| import freemarker.template.TemplateModel; |
| import freemarker.template.TemplateModelException; |
| |
| /** |
| * FreeMarker user-defined directive that progressively transforms |
| * the output of its nested content to upper-case. |
| * |
| * |
| * <p><b>Directive info</b></p> |
| * |
| * <p>Directive parameters: None |
| * <p>Loop variables: None |
| * <p>Directive nested content: Yes |
| */ |
| public class UpperDirective implements TemplateDirectiveModel { |
| |
| public void execute(Environment env, |
| Map params, TemplateModel[] loopVars, |
| TemplateDirectiveBody body) |
| throws TemplateException, IOException { |
| // Check if no parameters were given: |
| if (!params.isEmpty()) { |
| throw new TemplateModelException( |
| "This directive doesn't allow parameters."); |
| } |
| if (loopVars.length != 0) { |
| throw new TemplateModelException( |
| "This directive doesn't allow loop variables."); |
| } |
| |
| // If there is non-empty nested content: |
| if (body != null) { |
| // Executes the nested body. Same as <#nested> in FTL, except |
| // that we use our own writer instead of the current output writer. |
| body.render(new UpperCaseFilterWriter(env.getOut())); |
| } else { |
| throw new RuntimeException("missing body"); |
| } |
| } |
| |
| /** |
| * A {@link Writer} that transforms the character stream to upper case |
| * and forwards it to another {@link Writer}. |
| */ |
| private static class UpperCaseFilterWriter extends Writer { |
| |
| private final Writer out; |
| |
| UpperCaseFilterWriter (Writer out) { |
| this.out = out; |
| } |
| |
| public void write(char[] cbuf, int off, int len) |
| throws IOException { |
| char[] transformedCbuf = new char[len]; |
| for (int i = 0; i < len; i++) { |
| transformedCbuf[i] = Character.toUpperCase(cbuf[i + off]); |
| } |
| out.write(transformedCbuf); |
| } |
| |
| public void flush() throws IOException { |
| out.flush(); |
| } |
| |
| public void close() throws IOException { |
| out.close(); |
| } |
| } |
| |
| }</pre></div> |
| |
| <p>Now we still need to create an instance of this class, and |
| make this directive available to the template with the name "upper" |
| (or with whatever name we want) somehow. A possible solution is to |
| put the directive in the data-model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("upper", new com.example.UpperDirective());</pre></div> |
| |
| <p>But typically it is better practice to put commonly used |
| directives into the <code class="inline-code">Configuration</code> as <a href="#pgui_config_sharedvariables">shared |
| variables</a>.</p> |
| |
| <p>It is also possible to put the directive into an FTL library |
| (collection of macros and like in a template, that you |
| <code class="inline-code">include</code> or <code class="inline-code">import</code> in other |
| templates) using the <a href="#ref_builtin_new"><code>new</code> |
| built-in</a>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- Maybe you have directives that you have implemented in FTL --> |
| <#macro something> |
| ... |
| </#macro> |
| |
| <#-- Now you can't use <#macro upper>, but instead you can: --> |
| <#assign upper = "com.example.UpperDirective"?new()></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_36">Example 2</h5> |
| |
| |
| <p>We will create a directive that executes its nested content |
| again and again for the specified number of times (similarly to |
| <code class="inline-code">list</code> directive), optionally separating the the |
| output of the repetations with a <code class="inline-code"><hr></code>-s. |
| Let's call this directive "repeat". Example template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = 1> |
| |
| <strong><@repeat count=4></strong> |
| Test ${x} |
| <#assign x = x + 1> |
| <strong></@repeat></strong> |
| |
| <strong><@repeat count=3 hr=true></strong> |
| Test |
| <strong></@repeat></strong> |
| |
| <strong><@repeat count=3; cnt></strong> |
| ${cnt}. Test |
| <strong></@repeat></strong></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Test 1 |
| Test 2 |
| Test 3 |
| Test 4 |
| |
| Test |
| <hr> Test |
| <hr> Test |
| |
| 1. Test |
| 2. Test |
| 3. Test |
| </pre></div> |
| |
| <p>The class:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">package com.example; |
| import java.io.IOException; |
| import java.io.Writer; |
| import java.util.Iterator; |
| import java.util.Map; |
| |
| import freemarker.core.Environment; |
| import freemarker.template.SimpleNumber; |
| import freemarker.template.TemplateBooleanModel; |
| import freemarker.template.TemplateDirectiveBody; |
| import freemarker.template.TemplateDirectiveModel; |
| import freemarker.template.TemplateException; |
| import freemarker.template.TemplateModel; |
| import freemarker.template.TemplateModelException; |
| import freemarker.template.TemplateNumberModel; |
| |
| /** |
| * FreeMarker user-defined directive for repeating a section of a template, |
| * optionally with separating the output of the repetations with |
| * <tt>&lt;hr></tt>-s. |
| * |
| * |
| * <p><b>Directive info</b></p> |
| * |
| * <p>Parameters: |
| * <ul> |
| * <li><code>count</code>: The number of repetations. Required! |
| * Must be a non-negative number. If it is not a whole number then it will |
| * be rounded <em>down</em>. |
| * <li><code>hr</code>: Tells if a HTML "hr" element could be printed between |
| * repetations. Boolean. Optional, defaults to <code>false</code>. |
| * </ul> |
| * |
| * <p>Loop variables: One, optional. It gives the number of the current |
| * repetation, starting from 1. |
| * |
| * <p>Nested content: Yes |
| */ |
| public class RepeatDirective implements TemplateDirectiveModel { |
| |
| private static final String PARAM_NAME_COUNT = "count"; |
| private static final String PARAM_NAME_HR = "hr"; |
| |
| public void execute(Environment env, |
| Map params, TemplateModel[] loopVars, |
| TemplateDirectiveBody body) |
| throws TemplateException, IOException { |
| |
| // --------------------------------------------------------------------- |
| // Processing the parameters: |
| |
| int countParam = 0; |
| boolean countParamSet = false; |
| boolean hrParam = false; |
| |
| Iterator paramIter = params.entrySet().iterator(); |
| while (paramIter.hasNext()) { |
| Map.Entry ent = (Map.Entry) paramIter.next(); |
| |
| String paramName = (String) ent.getKey(); |
| TemplateModel paramValue = (TemplateModel) ent.getValue(); |
| |
| if (paramName.equals(PARAM_NAME_COUNT)) { |
| if (!(paramValue instanceof TemplateNumberModel)) { |
| throw new TemplateModelException( |
| "The \"" + PARAM_NAME_HR + "\" parameter " |
| + "must be a number."); |
| } |
| countParam = ((TemplateNumberModel) paramValue) |
| .getAsNumber().intValue(); |
| countParamSet = true; |
| if (countParam < 0) { |
| throw new TemplateModelException( |
| "The \"" + PARAM_NAME_HR + "\" parameter " |
| + "can't be negative."); |
| } |
| } else if (paramName.equals(PARAM_NAME_HR)) { |
| if (!(paramValue instanceof TemplateBooleanModel)) { |
| throw new TemplateModelException( |
| "The \"" + PARAM_NAME_HR + "\" parameter " |
| + "must be a boolean."); |
| } |
| hrParam = ((TemplateBooleanModel) paramValue) |
| .getAsBoolean(); |
| } else { |
| throw new TemplateModelException( |
| "Unsupported parameter: " + paramName); |
| } |
| } |
| if (!countParamSet) { |
| throw new TemplateModelException( |
| "The required \"" + PARAM_NAME_COUNT + "\" paramter" |
| + "is missing."); |
| } |
| |
| if (loopVars.length > 1) { |
| throw new TemplateModelException( |
| "At most one loop variable is allowed."); |
| } |
| |
| // Yeah, it was long and boring... |
| |
| // --------------------------------------------------------------------- |
| // Do the actual directive execution: |
| |
| Writer out = env.getOut(); |
| if (body != null) { |
| for (int i = 0; i < countParam; i++) { |
| // Prints a <hr> between all repetations if the "hr" parameter |
| // was true: |
| if (hrParam && i != 0) { |
| out.write("<hr>"); |
| } |
| |
| // Set the loop variable, if there is one: |
| if (loopVars.length > 0) { |
| loopVars[0] = new SimpleNumber(i + 1); |
| } |
| |
| // Executes the nested body (same as <#nested> in FTL). In this |
| // case we don't provide a special writer as the parameter: |
| body.render(env.getOut()); |
| } |
| } |
| } |
| |
| }</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_37">Notices</h5> |
| |
| |
| <p>It's important that a |
| <code class="inline-code">TemplateDirectiveModel</code> object usually should not |
| be stateful. The typical mistake is the storing of the state of the |
| directive call execution in the fields of the object. Think of |
| nested calls of the same directive, or directive objects used as |
| shared variables accessed by multiple threads concurrently.</p> |
| |
| <p>Unfortunatelly, <code class="inline-code">TemplateDirectiveModel</code>-s |
| don't support passing parameters by position (rather than by name). |
| This is fixed starting from FreeMarker 2.4.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_node">Node variables</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>A node variable embodies a node in a tree structure. Node |
| variables were introduced to help <a href="#xgui">the handling of |
| XML documents in the data-model</a>, but they can be used for the |
| modeling of other tree structures as well. For more information about |
| nodes from the point of view of the template language <a href="#dgui_datamodel_node">read this earlier section</a>.</p> |
| |
| <p>A node variable has the following properties, provided by the |
| methods of <code class="inline-code">TemplateNodeModel</code> interface:</p> |
| |
| <ul> |
| <li> |
| <p>Basic properties:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">TemplateSequenceModel |
| getChildNodes()</code>: A node has sequence of children |
| (except if the node is a leaf node, in which case the method |
| return an empty sequence or null). The child nodes should be |
| node variables as well.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateNodeModel getParentNode()</code>: A |
| node has exactly 1 parent node, except if the node is root |
| node of the tree, in which case the method returns |
| <code class="inline-code">null</code>.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Optional properties. If a property does not make sense in |
| the concrete use case, the corresponding method should return |
| <code class="inline-code">null</code>:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">String getNodeName()</code>: The node name |
| is the name of the macro, that handles the node when you use |
| <a href="#ref.directive.recurse"><code>recurse</code></a> |
| and <a href="#ref.directive.visit"><code>visit</code></a> |
| directives. Thus, if you want to use these directives with the |
| node, the node name is <em>required</em>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">String getNodeType()</code>: In the case of |
| XML: <code class="inline-code">"element"</code>, <code class="inline-code">"text"</code>, |
| <code class="inline-code">"comment"</code>, ...etc. This information, if |
| available, is used by the <code class="inline-code">recurse</code> and |
| <code class="inline-code">visit</code> directives to find the default |
| handler macro for a node. Also it can be useful for other |
| application specific purposes.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">String getNamespaceURI()</code>: The node |
| namespace (has nothing to do with FTL namespaces used for |
| libraries) this node belongs to. For example, in the case of |
| XML, this is the URI of the XML namespace the element or |
| attribute belongs to. This information, if available, is used |
| by the <code class="inline-code">recurse</code> and <code class="inline-code">visit</code> |
| directives to find the FTL namespaces that store the handler |
| macros.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>On the FTL side, the direct utilization of node properties is |
| done with <a href="#ref_builtins_node">node built-ins</a>, and |
| with the <code class="inline-code">visit</code> and <code class="inline-code">recurse</code> |
| macros.</p> |
| |
| <p>In most use cases, variables that implement |
| <code class="inline-code">TemplateNodeModel</code>, implement other interfaces as |
| well, since node variable properties just provide the basic |
| infrastructure for navigating between nodes. For a concrete example, |
| see <a href="#xgui">how FreeMarker deals with XML</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_datamodel_objectWrapper">Object wrappers</h4> |
| |
| |
| |
| |
| |
| |
| <p>When you add something to a container, it may receive any java |
| object as a parameter, not necessarily a |
| <code class="inline-code">TemplateModel</code>, as you could see in the FreeMarker |
| API. This is because the container implementation can silently replace |
| that object with the appropriate <code class="inline-code">TemplateModel</code> |
| object. For example if you add a <code class="inline-code">String</code> to the |
| container, perhaps it will be replaced with a |
| <code class="inline-code">SimpleScalar</code> instance which stores the same |
| text.</p> |
| |
| <p>As for when the replacement occurs, it's the business of the |
| container in question (i.e. the business of the class that implements |
| the container interface), but it must happen at the latest when you |
| get the subvariable, as the getter methods (according to the |
| interfaces) return <code class="inline-code">TemplateModel</code>, not |
| <code class="inline-code">Object</code>. For example, <code class="inline-code">SimpleHash</code>, |
| <code class="inline-code">SimpleSequence</code> and |
| <code class="inline-code">SimpleCollection</code> use the laziest strategy; they |
| replace a non-<code class="inline-code">TemplateModel</code> subvariable with an |
| appropriate <code class="inline-code">TemplateModel</code> object when you get the |
| subvariable for the first time.</p> |
| |
| <p>As for what java objects can be replaced, and with what |
| <code class="inline-code">TemplateModel</code> implementations, it is either handled |
| by the container implementation itself, or it delegates this to an |
| <code class="inline-code">ObjectWrapper</code> instance. |
| <code class="inline-code">ObjectWrapper</code> is an interface that specifies one |
| method: <code class="inline-code">TemplateModel wrap(java.lang.Object obj)</code>. |
| You pass in an <code class="inline-code">Object</code>, and it returns the |
| corresponding <code class="inline-code">TemplateModel</code> object, or throws a |
| <code class="inline-code">TemplateModelException</code> if this is not possible. The |
| replacement rules are coded into the <code class="inline-code">ObjectWrapper</code> |
| implementation.</p> |
| |
| <p>The most important <code class="inline-code">ObjectWrapper</code> |
| implementations that the FreeMarker core provides are:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code>: It |
| replaces <code class="inline-code">String</code> with |
| <code class="inline-code">SimpleScalar</code>, <code class="inline-code">Number</code> with |
| <code class="inline-code">SimpleNumber</code>, <code class="inline-code">List</code> and array |
| with <code class="inline-code">SimpleSequence</code>, <code class="inline-code">Map</code> |
| with <code class="inline-code">SimpleHash</code>, <code class="inline-code">Boolean</code> |
| with <code class="inline-code">TemplateBooleanModel.TRUE</code> or |
| <code class="inline-code">TemplateBooleanModel.FALSE</code>, W3C DOM nodes with |
| <code class="inline-code">freemarker.ext.dom.NodeModel</code>. For Jython |
| objects, this wrapper will invoke |
| <code class="inline-code">freemarker.ext.jython.JythonWrapper</code>. For all |
| other objects, it will invoke <a href="#pgui_misc_beanwrapper"><code>BEANS_WRAPPER</code></a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>: It can |
| expose java Bean properties and other members of arbitrary objects |
| using Java reflection. At least in FreeMarker 2.3, it is a |
| <code class="inline-code">freemarker.ext.beans.BeansWrapper</code> instance; |
| there is a separated <a href="#pgui_misc_beanwrapper">chapter |
| about it</a>.</p> |
| </li> |
| </ul> |
| |
| <p>For a concrete example, let's see how the |
| <code class="inline-code">Simple<em class="code-color">Xxx</em></code> classes work. |
| <code class="inline-code">SimpleHash</code>, <code class="inline-code">SimpleSequence</code> and |
| <code class="inline-code">SimpleCollection</code> use |
| <code class="inline-code">DEFAULT_WRAPPER</code> to wrap the subvariables (unless |
| you pass in an alternative wrapper in their constructor). So this |
| example demonstrates <code class="inline-code">DEFAULT_WRAPPER</code> in |
| action:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Map map = new HashMap(); |
| map.put("anotherString", "blah"); |
| map.put("anotherNumber", new Double(3.14)); |
| List list = new ArrayList(); |
| list.add("red"); |
| list.add("green"); |
| list.add("blue"); |
| |
| SimpleHash root = new SimpleHash(); // will use the default wrapper |
| root.put("theString", "wombat"); |
| root.put("theNumber", new Integer(8)); |
| root.put("theMap", map); |
| root.put("theList", list);</pre></div> |
| |
| <p>Assuming that root is the data-model root, the resulting |
| data-model is:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- theString = "wombat" |
| | |
| +- theNumber = 8 |
| | |
| +- theMap |
| | | |
| | +- anotherString = "blah" |
| | | |
| | +- anotherNumber = 3.14 |
| | |
| +- theList |
| | |
| +- (1st) = "red" |
| | |
| +- (2nd) = "green" |
| | |
| +- (3rd) = "blue"</pre></div> |
| |
| <p>Note that the <code class="inline-code">Object</code>-s inside |
| <code class="inline-code">theMap</code> and <code class="inline-code">theList</code> are |
| accessible as subvariables too. This is because when you, say, try to |
| access <code class="inline-code">theMap.anotherString</code>, then the |
| <code class="inline-code">SimpleHash</code> (which is used as root hash here) will |
| silently replace the <code class="inline-code">Map</code> |
| (<code class="inline-code">theMap</code>) with a <code class="inline-code">SimpleHash</code> |
| instance that uses the same wrapper as the root hash, so when you try |
| to access the <code class="inline-code">anotherString</code> subvariable of it, it |
| will replace that with a <code class="inline-code">SimpleScalar</code>.</p> |
| |
| <p>If you drop an ``arbitrary'' object into the data-model, |
| <code class="inline-code">DEFAULT_WRAPPER</code> will invoke |
| <code class="inline-code">BEANS_WRAPPER</code> to wrap the object:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">SimpleHash root = new SimpleHash(); |
| // expose a "simple" java objects: |
| root.put("theString", "wombat"); |
| // expose an "arbitrary" java objects: |
| root.put("theObject", new TestObject("green mouse", 1200));</pre></div> |
| |
| <p>Assuming this is <code class="inline-code">TestObject</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">public class TestObject { |
| private String name; |
| private int price; |
| |
| public TestObject(String name, int price) { |
| this.name = name; |
| this.price = price; |
| } |
| |
| // JavaBean properties |
| // Note that public fields are not visible directly; |
| // you must write a getter method for them. |
| public String getName() {return name;} |
| public int getPrice() {return price;} |
| |
| // A method |
| public double sin(double x) { |
| return Math.sin(x); |
| } |
| }</pre></div> |
| |
| <p>The data-model will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-data-model">(root) |
| | |
| +- theString = "wombat" |
| | |
| +- theObject |
| | |
| +- name = "green mouse" |
| | |
| +- price = 1200 |
| | |
| +- number sin(number)</pre></div> |
| |
| <p>So we can merge it with this template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${theObject.name} |
| ${theObject.price} |
| ${theObject.sin(123)}</pre></div> |
| |
| <p>Which will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">green mouse |
| 1200 |
| -0,45990349068959124</pre></div> |
| |
| <p>You have seen in earlier examples of this manual that we have |
| used <code class="inline-code">java.util.HashMap</code> as root hash, and not |
| <code class="inline-code">SimpleHash</code> or other FreeMarker specific class. It |
| works because |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| automatically wraps the object you give as its data-model argument. It |
| uses the object wrapper dictated by the |
| <code class="inline-code">Configuration</code> level <a href="#pgui_config_settings">setting</a>, |
| <code class="inline-code">object_wrapper</code> (unless you explicitly specify an |
| <code class="inline-code">ObjectWrapper</code> as its parameter). Thus, in simple |
| FreeMarker application you need not know about |
| <code class="inline-code">TemplateModel</code>-s at all. Note that the root need not |
| be a <code class="inline-code">java.util.Map</code>. It can be anything that is |
| wrapped so that it implements the <code class="inline-code">TemplateHashModel</code> |
| interface.</p> |
| |
| <p>The factory default value of the |
| <code class="inline-code">object_wrapper</code> setting is |
| <code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code>. If you want to |
| change it to, say, <code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>, you |
| can configure the FreeMarker engine (before starting to use it from |
| other threads) like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setObjectWrapper(ObjectWrapper.BEANS_WRAPPER);</pre></div> |
| |
| <p>Note that you can set any object here that implements interface |
| <code class="inline-code">ObjectWrapper</code>, so you can set your custom |
| implementation as well.</p> |
| |
| <p>For <code class="inline-code">TemplateModel</code> implementations that wrap |
| basic Java container types, as <code class="inline-code">java.util.Map</code>-s and |
| <code class="inline-code">java.util.List</code>-s, the convention is that they use |
| the same object wrapper to wrap their subvariables as their parent |
| container does. Technically correctly said, they are instantiated by |
| their parent container (so it has full control over the creation of |
| them), and the parent container create them so they will use the same |
| object wrapper as the parent itself. Thus, if |
| <code class="inline-code">BEANS_WRAPPER</code> is used for the wrapping of the root |
| hash, it will be used for the wrapping of the subvariables (and the |
| subvariables of the subvariables, etc.) as well. This is exactly the |
| same phenomenon as you have seen with |
| <code class="inline-code">theMap.anotherString</code> earlier.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="pgui_config">The Configuration</h3> |
| |
| |
| |
| |
| <p>This is just an overview. See the <a href="api/index.html">FreeMarker Java API documentation</a> for the |
| details.</p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_config_basics">Basics</h4> |
| |
| |
| <p>A configuration is an object that stores your common |
| (application level) settings and defines certain variables that you |
| want to be available in all templates. Also it deals with the creation |
| and caching of <code class="inline-code">Template</code> instances. A configuration |
| is a <code class="inline-code">freemarker.template.Configuration</code> instances, |
| that you can create with its constructor. An application typically |
| uses only a single shared <code class="inline-code">Configuration</code> |
| instance.</p> |
| |
| <p>Configurations are used by the <code class="inline-code">Template</code> |
| methods, especially by <code class="inline-code">process</code> method. Each |
| <code class="inline-code">Template</code> instance has exactly one |
| <code class="inline-code">Configuration</code> instance associated with it, which is |
| assigned to the <code class="inline-code">Template</code> instance by the |
| <code class="inline-code">Template</code> constructor; you can specify a |
| <code class="inline-code">Configuration</code> instance as its parameter. Usually |
| you obtain <code class="inline-code">Template</code> instances with |
| <code class="inline-code">Configuration.getTemplate</code> (not by directly calling |
| the <code class="inline-code">Template</code> constructor), in which case the |
| associated <code class="inline-code">Configuration</code> instance will be the one |
| whose <code class="inline-code">getTemplate</code> method has been called.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_config_sharedvariables">Shared variables</h4> |
| |
| |
| |
| |
| <p><strong>Shared variables</strong> are variables |
| that are defined for all templates. You can add shared variables to |
| the configuration with the <code class="inline-code">setSharedVariable</code> |
| methods:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Configuration cfg = new Configuration(); |
| <em>...</em> |
| cfg.setSharedVariable("wrap", new WrapDirective()); |
| cfg.setSharedVariable("company", "Foo Inc."); // Using ObjectWrapper.DEFAULT_WRAPPER</pre></div> |
| |
| <p>In all templates that use this configuration, an user-defined |
| directive with name <code class="inline-code">wrap</code> and a string with name |
| <code class="inline-code">company</code> will be visible in the data-model root, so |
| you don't have to add them to the root hash again and again. A |
| variable in the root object that you pass to the |
| <code class="inline-code">Template.process</code> will hide the shared variable with |
| the same name.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>Never use <code class="inline-code">TemplateModel</code> implementation that |
| is not <a href="#gloss.threadSafe">thread-safe</a> for |
| shared variables, if the configuration is used by multiple threads! |
| This is the typical situation for Servlet based Web sites.</p> |
| </div> |
| |
| |
| <p>Due to backward compatibility heritage, the set of shared |
| variables is initially (i.e., for a new |
| <code class="inline-code">Configuration</code> instance) not empty. It contains the |
| following user-defined directives (they are "user-defined" in the |
| sense that you use <code class="inline-code">@</code> to call them instead of |
| <code class="inline-code">#</code>):</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>name</th> |
| |
| |
| <th>class</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">capture_output</code></td> |
| |
| |
| <td><code class="inline-code">freemarker.template.utility.CaptureOutput</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">compress</code></td> |
| |
| |
| <td><code class="inline-code">freemarker.template.utility.StandardCompress</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">html_escape</code></td> |
| |
| |
| <td><code class="inline-code">freemarker.template.utility.HtmlEscape</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">normalize_newlines</code></td> |
| |
| |
| <td><code class="inline-code">freemarker.template.utility.NormalizeNewlines</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">xml_escape</code></td> |
| |
| |
| <td><code class="inline-code">freemarker.template.utility.XmlEscape</code></td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_config_settings">Settings</h4> |
| |
| |
| |
| |
| <p><strong>Settings</strong> are named values that |
| influence the behavior of FreeMarker. Examples of settings are: |
| <code class="inline-code">locale</code>, <code class="inline-code">number_format</code></p> |
| |
| <p>Settings stored in <code class="inline-code">Configuration</code> instance can |
| be overridden in a <code class="inline-code">Template</code> instance. For example |
| you set <code class="inline-code">"en_US"</code> for the <code class="inline-code">locale</code> |
| setting in the configuration, then the <code class="inline-code">locale</code> in |
| all templates that use this configuration will be |
| <code class="inline-code">"en_US"</code>, except in templates where the locale was |
| explicitly specified differently (see <a href="#ref_directive_include_localized">localization</a>). Thus, |
| values in a <code class="inline-code">Configuration</code> serve as defaults that |
| can be overridden in a per template manner. The value comes from |
| <code class="inline-code">Configuration</code> instance or |
| <code class="inline-code">Template</code> instance can be further overridden for a |
| single <code class="inline-code">Template.process</code> call. For each such call a |
| <code class="inline-code">freemarker.core.Environment</code> object is created |
| internally that holds the runtime environment of the template |
| processing, including the setting values that were overridden on that |
| level. The values stored there can even be changed during the template |
| processing, so a template can set settings itself, like switching |
| <code class="inline-code">locale</code> at the middle of the output.</p> |
| |
| <p>This can be imagined as 3 layers |
| (<code class="inline-code">Configuration</code>, <code class="inline-code">Template</code>, |
| <code class="inline-code">Environment</code>) of settings, where the topmost layer |
| that contains the value for a certain setting provides the effective |
| value of that setting. For example (settings A to F are just imaginary |
| settings for this example):</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| |
| |
| |
| |
| <thead> |
| <tr> |
| <th align="left"></th> |
| |
| |
| <th align="center">Setting A</th> |
| |
| |
| <th align="center">Setting B</th> |
| |
| |
| <th align="center">Setting C</th> |
| |
| |
| <th align="center">Setting D</th> |
| |
| |
| <th align="center">Setting E</th> |
| |
| |
| <th align="center">Setting F</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td align="left">Layer 3: <code class="inline-code">Environment</code></td> |
| |
| |
| <td align="center">1</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">1</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">-</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td align="left">Layer 2: <code class="inline-code">Template</code></td> |
| |
| |
| <td align="center">2</td> |
| |
| |
| <td align="center">2</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">2</td> |
| |
| |
| <td align="center">-</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td align="left">Layer 1: <code class="inline-code">Configuration</code></td> |
| |
| |
| <td align="center">3</td> |
| |
| |
| <td align="center">3</td> |
| |
| |
| <td align="center">3</td> |
| |
| |
| <td align="center">3</td> |
| |
| |
| <td align="center">-</td> |
| |
| |
| <td align="center">-</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>The effective value of settings will be: A = 1, B = 2, C = 3, D |
| = 1, E = 2. The F setting is probably <code class="inline-code">null</code>, or it |
| throws exception when you try to get it.</p> |
| |
| <p>Let's see exactly how to set settings:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">Configuration</code> layer: In principle you set |
| the settings with the setter methods of the |
| <code class="inline-code">Configuration</code> object, fore example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Configuration myCfg = new Configuration(); |
| myCfg.setLocale(java.util.Locale.ITALY); |
| myCfg.setNumberFormat("0.####");</pre></div> |
| |
| <p>You do it before you start to actually use the |
| <code class="inline-code">Configuration</code> object (typically, when you |
| initialize the application); you should treat the object as |
| read-only after that.</p> |
| |
| <p>In practice, in most Web application frameworks you have to |
| specify the setting in a framework-specific configuration file |
| that require specifying setting as <code class="inline-code">String</code> |
| name-value pairs (like in a <code class="inline-code">.properties</code> file). |
| In that case the authors of the frameworks most probably use the |
| <code class="inline-code">setSetting(String name, String value)</code> method of |
| <code class="inline-code">Configuration</code>; see available setting names and |
| the format of the values in the API doc of |
| <code class="inline-code">setSetting</code>. Example for Spring |
| Framework:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><bean id="freemarkerConfig" |
| class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"> |
| <property name="freemarkerSettings"> |
| <props> |
| <prop key="locale">it_IT</prop> |
| <prop key="number_format">0.####</prop> |
| </props> |
| </property> |
| </bean></pre></div> |
| |
| <p>Note that this kind of configuring |
| (<code class="inline-code">String</code> key-value pairs) is unfortunately |
| limited compared to directly using the API of |
| <code class="inline-code">Configuration</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Template</code> layer: You shouldn't set |
| settings here, unless you manage the <code class="inline-code">Template</code> |
| objects instead of a |
| <code class="inline-code">freemarker.cache.TemplateCache</code>, in which case |
| you should set the setting before the <code class="inline-code">Template</code> |
| object is first used, and then treat the |
| <code class="inline-code">Template</code> object as read-only.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Environment </code>layer: There are two ways |
| doing it:</p> |
| |
| <ul> |
| <li> |
| <p>With Java API: Use the setter methods of the |
| <code class="inline-code">Environment</code> object. Certainly you want to |
| do that just before the processing of the template is started, |
| and then you run into the problem that when you call |
| <code class="inline-code">myTemplate.process(...)</code> it creates the |
| <code class="inline-code">Environment</code> object internally and the |
| immediately processes the template, so you had no chance. The |
| solution is that this two steps can be separated like |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out); |
| env.setLocale(java.util.Locale.ITALY); |
| env.setNumberFormat("0.####"); |
| env.process(); // process the template</pre></div> |
| </li> |
| |
| <li> |
| <p>Directly in the Template: Use the <a href="#ref.directive.setting"><code>setting</code> |
| directive</a>, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#setting locale="it_IT"> |
| <#setting number_format="0.####"></pre></div> |
| </li> |
| </ul> |
| |
| <p>There are no restriction regarding when can you change the |
| settings in this layer.</p> |
| </li> |
| </ul> |
| |
| <p>To see the list of supported settings, please read the following |
| parts of the FreeMarker Java API documentation:</p> |
| |
| <ul> |
| <li> |
| <p>Setter methods of |
| <code class="inline-code">freemarker.core.Configurable</code> for the settings |
| that are in all three layers</p> |
| </li> |
| |
| <li> |
| <p>Setter methods of |
| <code class="inline-code">freemarker.template.Configuration</code> for the |
| settings that are available only in the |
| <code class="inline-code">Configuration</code> layer</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.core.Configurable.setSetting(String, |
| String)</code> for settings that are available in all three |
| layers and are writable with <code class="inline-code">String</code> key-value |
| pairs.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.Configuration.setSetting(String, |
| String)</code> for settings that are available only in the |
| <code class="inline-code">Configuration</code> layer and are writable with |
| <code class="inline-code">String</code> key-value pairs.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_config_templateloading">Template loading</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_38">Template loaders</h5> |
| |
| |
| |
| |
| <p>Template loaders are objects that load raw textual data based |
| on abstract template paths like <code class="inline-code">"index.ftl"</code> or |
| <code class="inline-code">"products/catalog.ftl"</code>. It is up to the concrete |
| template loader object what source does it use to fetch the |
| requested data (files in a directory, data base, etc.). When you |
| call <code class="inline-code">cfg.getTemplate</code> (where |
| <code class="inline-code">cfg</code> is a <code class="inline-code">Configuration</code> |
| instance), FreeMarker ask the template loader you have set up for |
| the <code class="inline-code">cfg</code> to return the text for the given template |
| path, and then FreeMarker parses that text as template.</p> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_39">Built-in template loaders</h6> |
| |
| |
| <p>You can set up three template loading methods in the |
| <code class="inline-code">Configuration</code> using the following convenience |
| methods. (Each method will create a template loader object |
| internally and set up the <code class="inline-code">Configuration</code> |
| instance to use that.)</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">void setDirectoryForTemplateLoading(File dir);</pre></div> |
| |
| <p>or</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">void setClassForTemplateLoading(Class cl, String prefix);</pre></div> |
| |
| <p>or</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">void setServletContextForTemplateLoading(Object servletContext, String path);</pre></div> |
| |
| <p>The first method above sets an explicit directory on the |
| file system from which to load templates. Needless to say perhaps, |
| the <code class="inline-code">File</code> parameter must be an existing |
| directory. Otherwise, an exception will be thrown.</p> |
| |
| <p>The second call takes a <code class="inline-code">Class</code> as a |
| parameter and a prefix. This is for when you want to load |
| templates via the same mechanism that a java |
| <code class="inline-code">ClassLoader</code> uses to load classes. This means |
| that the class you pass in will be used to call |
| <code class="inline-code">Class.getResource()</code> to find the templates. The |
| <code class="inline-code">prefix</code> parameter is prepended to the name of |
| the template. The classloading mechanism will very likely be the |
| preferred means of loading templates for production code, since |
| loading from the classpath mechanism is usually more foolproof |
| than specifying an explicit directory location on the file system. |
| It is also nicer in a final application to keep everything in a |
| <code class="inline-code">.jar</code> file that the user can simply execute |
| directly and have all the icons and text and everything else |
| inside the <code class="inline-code">.jar</code> file.</p> |
| |
| <p>The third call takes the context of your web application, |
| and a base path, which is interpreted relative to the web |
| application root directory (that's the parent of the |
| <code class="inline-code">WEB-INF</code> directory). This loader will load the |
| templates from the web application directory. Note that we refer |
| to "directory" here although this loading method works even for |
| unpacked <code class="inline-code">.war</code> files since it uses |
| <code class="inline-code">ServletContext.getResource()</code> to access the |
| templates. If you omit the second parameter (or use |
| <code class="inline-code">""</code>), you can simply store the static files |
| (<code class="inline-code">.html</code>, <code class="inline-code">.jpg</code>, etc.) mixed |
| with the <code class="inline-code">.ftl</code> files, just |
| <code class="inline-code">.ftl</code> files will be sent to the client |
| processed. Of course, you must set up a Servlet for the |
| <code class="inline-code">*.ftl</code> uri-pattern in |
| <code class="inline-code">WEB-INF/web.xml</code> for this, otherwise the client |
| will get the templates as is, and thus may see confidential |
| content! You should not use empty path if this is a problem for |
| your site, rather you should store the templates somewhere inside |
| the <code class="inline-code">WEB-INF</code> directory, so the raw templates are |
| never served accidentally. This mechanism will very likely be the |
| preferred means of loading templates for servlet applications, |
| since the templates can be updated without restarting the web |
| application, while this often doesn't work with the class-loader |
| mechanism.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_40">Loading templates from multiple locations</h6> |
| |
| |
| <p>If you need to load templates from multiple locations, you |
| have to instantiate the template loader objects for every |
| location, wrap them into a special template loader named |
| <code class="inline-code">MultiTemplateLoader</code> and finally pass that |
| loader to the <code class="inline-code">setTemplateLoader(TemplateLoader |
| loader)</code> method of <code class="inline-code">Configuration</code>. |
| Here's an example for loading templates from two distinct |
| directories and with the class-loader:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">import freemarker.cache.*; // template loaders live in this package |
| |
| <em>...</em> |
| |
| FileTemplateLoader ftl1 = new FileTemplateLoader(new File("/tmp/templates")); |
| FileTemplateLoader ftl2 = new FileTemplateLoader(new File("/usr/data/templates")); |
| ClassTemplateLoader ctl = new ClassTemplateLoader(getClass(), ""); |
| TemplateLoader[] loaders = new TemplateLoader[] { ftl1, ftl2, ctl }; |
| MultiTemplateLoader mtl = new MultiTemplateLoader(loaders); |
| |
| cfg.setTemplateLoader(mtl);</pre></div> |
| |
| <p>Now FreeMarker will try to load templates from |
| <code class="inline-code">/tmp/templates</code> directory, and if it does not |
| find the requested template there, it will try to load that from |
| <code class="inline-code">/usr/data/templates</code>, and if it still does not |
| find the requested template, then it tries to load that with the |
| class-loader.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_41">Loading templates from other sources</h6> |
| |
| |
| <p>If none of the built-in class loaders are good for you, you |
| will have to write your own class that implements the |
| <code class="inline-code">freemarker.cache.TemplateLoader</code> interface and |
| pass it to the <code class="inline-code">setTemplateLoader(TemplateLoader |
| loader)</code> method of <code class="inline-code">Configuration</code>. |
| Please read the API JavaDoc for more information.</p> |
| |
| <p>If your template source accesses the templates through an |
| URL, you needn't implement a <code class="inline-code">TemplateLoader</code> |
| from scratch; you can choose to subclass |
| <code class="inline-code">freemarker.cache.URLTemplateLoader</code> instead and |
| just implement the <code class="inline-code">URL getURL(String |
| templateName)</code> method.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_42">The template path</h6> |
| |
| |
| |
| |
| |
| |
| <p>It is up to the template loader how it interprets template |
| paths. But to work together with other components there are |
| restrictions regarding the format of the path. In general, it is |
| strongly recommended that template loaders use URL-style paths. |
| The path must not use <code class="inline-code">/</code>, <code class="inline-code">./</code> |
| and <code class="inline-code">../</code> and <code class="inline-code">://</code> with other |
| meaning as they have in URL paths (or in UN*X paths). The |
| characters <code class="inline-code">*</code> and <code class="inline-code">?</code> are |
| reserved. Also, the template loader must not want paths starting |
| with <code class="inline-code">/</code>; FreeMarker will never call template |
| loader with such path. Note that FreeMarker always normalizes the |
| paths before passing them to the template loader, so the paths do |
| not contain <code class="inline-code">/../</code> and such, and are relative to |
| the imaginary template root directory.</p> |
| |
| <p>Note that FreeMarker template loading always uses slash (not |
| backslash) regardless of the host OS.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="pgui_config_templateloading_caching">Template caching</h5> |
| |
| |
| |
| |
| |
| |
| <p>FreeMarker caches templates (assuming you use the |
| <code class="inline-code">Configuration</code> methods to create |
| <code class="inline-code">Template</code> objects). This means that when you call |
| <code class="inline-code">getTemplate</code>, FreeMarker not only returns the |
| resulting <code class="inline-code">Template</code> object, but stores it in a |
| cache, so when next time you call <code class="inline-code">getTemplate</code> |
| with the same (or equivalent) path, it just returns the cached |
| <code class="inline-code">Template</code> instance, and will not load and parse |
| the template file again.</p> |
| |
| <p>If you change the template file, then FreeMarker will re-load |
| and re-parse the template automatically when you get the template |
| next time. However, since checking if the file has been changed can |
| be time consuming, there is a <code class="inline-code">Configuration</code> level |
| setting called ``update delay''. This is the time that must elapse |
| since the last checking for a newer version of a certain template |
| before FreeMarker will check that again. This is set to 5 seconds by |
| default. If you want to see the changes of templates immediately, |
| set it to 0. Note that some template loaders may have problems with |
| template updating. For example, class-loader based template loaders |
| typically do not notice that you have changed the template |
| file.</p> |
| |
| <p>A template will be removed from the cache if you call |
| <code class="inline-code">getTemplate</code> and FreeMarker realizes that the |
| template file has been removed meanwhile. Also, if the JVM thinks |
| that it begins to run out of memory, by default it can arbitrarily |
| drop templates from the cache. Furthermore, you can empty the cache |
| manually with the <code class="inline-code">clearTemplateCache</code> method of |
| <code class="inline-code">Configuration</code>.</p> |
| |
| <p>The actual strategy of when a cached template should be thrown |
| away is pluggable with the <code class="inline-code">cache_storage</code> setting, |
| by which you can plug any <code class="inline-code">CacheStorage</code> |
| implementation. For most users |
| <code class="inline-code">freemarker.cache.MruCacheStorage</code> will be |
| sufficient. This cache storage implements a two-level Most Recently |
| Used cache. In the first level, items are strongly referenced up to |
| the specified maximum (strongly referenced items can't be dropped by |
| the JVM, as opposed to softly referenced items). When the maximum is |
| exceeded, the least recently used item is moved into the second |
| level cache, where they are softly referenced, up to another |
| specified maximum. The size of the strong and soft parts can be |
| specified with the constructor. For example, set the size of the |
| strong part to 20, and the size of soft part to 250:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setCacheStorage(new freemarker.cache.MruCacheStorage(20, 250))</pre></div> |
| |
| <p>Or, since <code class="inline-code">MruCacheStorage</code> is the default |
| cache storage implementation:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setSetting(Configuration.CACHE_STORAGE_KEY, "strong:20, soft:250");</pre></div> |
| |
| <p>When you create a new <code class="inline-code">Configuration</code> object, |
| initially it uses an <code class="inline-code">MruCacheStorage</code> where |
| <code class="inline-code">maxStrongSize</code> is 0, and |
| <code class="inline-code">maxSoftSize</code> is |
| <code class="inline-code">Integer.MAX_VALUE</code> (that is, in practice, |
| infinite). But using non-0 <code class="inline-code">maxStrongSize</code> is maybe |
| a better strategy for high load servers, since it seems that, with |
| only softly referenced items, JVM tends to cause just higher |
| resource consumption if the resource consumption was already high, |
| because it constantly throws frequently used templates from the |
| cache, which then have to be re-loaded and and re-parsed.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_config_errorhandling">Error handling</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_43">The possible exceptions</h5> |
| |
| |
| <p>The exceptions that can occur regarding FreeMarker could be |
| classified like this:</p> |
| |
| <ul> |
| <li> |
| <p>Exceptions occurring when you configure FreeMarker: |
| Typically you configure FreeMarker only once in your |
| application, when your application initializes itself. Of |
| course, during this, exceptions can occur, as it is obvious from |
| the FreeMarker API...</p> |
| </li> |
| |
| <li> |
| <p>Exceptions occurring when loading and parsing templates: |
| When you call |
| <code class="inline-code">Configuration.getTemplate(<em class="code-color">...</em>)</code>, |
| FreeMarker has to load the template file into the memory and |
| parse it (unless the template is already <a href="#pgui_config_templateloading_caching">cached</a> in |
| that <code class="inline-code">Configuration</code> object). During this, two |
| kind of exceptions can occur:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">IOException</code> because the template |
| file was not found, or other I/O problem occurred while |
| trying to read it, for example you have no right to read the |
| file, or there are disk errors. The emitter of these errors |
| is the <a href="#pgui_config_templateloading"><code>TemplateLoader</code> |
| object</a>, which is plugged into the |
| <code class="inline-code">Configuration</code> object. (For the sake of |
| correctness: When I say ``file'' here, that's a |
| simplification. For example, templates can be stored in a |
| table of a relational database as well. This is the business |
| of the <code class="inline-code">TemplateLoader</code>.)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.core.ParseException</code> |
| because the template file is syntactically incorrect |
| according the rules of the FTL language. The point is that |
| this error occurs when you obtain the |
| <code class="inline-code">Template</code> object |
| (<code class="inline-code">Configuration.getTemplate(<em class="code-color">...</em>)</code>), |
| and not when you execute |
| (<code class="inline-code">Template.process(<em class="code-color">...</em>)</code>) |
| the template. This exception is an |
| <code class="inline-code">IOException</code> subclass.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Exceptions occurring when executing (processing) |
| templates, that is, when you call |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code>. |
| Two kind of exceptions can occur:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">IOException</code> because there was an |
| error when trying to write into the output writer.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplatException</code> |
| because other problem occurred while executing the template. |
| For example, a frequent error is when a template refers to a |
| variable which is not existing. Be default, when a |
| <code class="inline-code">TemplatException</code> occurs, FreeMarker |
| prints the FTL error message and the stack trace to the |
| output writer with plain text format, and then aborts the |
| template execution by re-throwing the |
| <code class="inline-code">TemplatException</code>, which then you can |
| catch as |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| throws it. But this behavior can be customized. FreeMarker |
| always <a href="#pgui_misc_logging">logs</a> |
| <code class="inline-code">TemplatException</code>-s.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_44">Customizing the behavior regarding TemplatException-s</h5> |
| |
| |
| <p><code class="inline-code">TemplateException</code>-s thrown during the |
| template processing are handled by the |
| <code class="inline-code">freemarker.template.TemplateExceptionHandler</code> |
| object, which is plugged into the <code class="inline-code">Configuration</code> |
| object with its |
| <code class="inline-code">setTemplateExceptionHandler(<em class="code-color">...</em>)</code> |
| mehod. The <code class="inline-code">TemplateExceptionHandler</code> contains 1 |
| method:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">void handleTemplateException(TemplateException te, Environment env, Writer out) |
| throws TemplateException;</pre></div> |
| |
| <p>Whenever a <code class="inline-code">TemplateException</code> occurs, this |
| method will be called. The exception to handle is passed with the |
| <code class="inline-code">te</code> argument, the runtime environment of the |
| template processing is accessible with the <code class="inline-code">env</code> |
| argument, and the handler can print to the output using the |
| <code class="inline-code">out</code> argument. If the method throws exception |
| (usually it re-throws <code class="inline-code">te</code>), then the template |
| processing will be aborted, and |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| will throw the same exception. If |
| <code class="inline-code">handleTemplateException</code> doesn't throw exception, |
| then template processing continues as if nothing had happen, but the |
| statement that caused the exception will be skipped (see more |
| later). Of course, the handler can still print an error indicator to |
| the output.</p> |
| |
| <p>In any case, before the |
| <code class="inline-code">TemplateExceptionHandler</code> is invoked, FreeMarker |
| will <a href="#pgui_misc_logging">log</a> the |
| exception.</p> |
| |
| <p>Let's see how FreeMarker skips ``statements'' when the error |
| handler doesn't throw exception, through examples. Assume we are |
| using this template exception handler:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">class MyTemplateExceptionHandler implements TemplateExceptionHandler { |
| public void handleTemplateException(TemplateException te, Environment env, java.io.Writer out) |
| throws TemplateException { |
| try { |
| out.write("[ERROR: " + te.getMessage() + "]"); |
| } catch (IOException e) { |
| throw new TemplateException("Failed to print error message. Cause: " + e, env); |
| } |
| } |
| } |
| |
| <em>...</em> |
| |
| cfg.setTemplateExceptionHandler(new MyTemplateExceptionHandler());</pre></div> |
| |
| <p>If an error occurs in an interpolation which is not inside an |
| FTL tag (that is, not enclosed into |
| <code class="inline-code"><#<em class="code-color">...</em>></code> or |
| <code class="inline-code"><@<em class="code-color">...</em>></code>), then |
| the whole interpolation will be skipped. So this template (assuming |
| that <code class="inline-code">badVar</code> is missing from the |
| data-model):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a${badVar}b</pre></div> |
| |
| <p>will print this if we use the |
| <code class="inline-code">MyTemplateExceptionHandler</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">a[ERROR: Expression badVar is undefined on line 1, column 4 in test.ftl.]b</pre></div> |
| |
| <p>This template will print the same (except that the column |
| number will differ...):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a${"moo" + badVar}b</pre></div> |
| |
| <p>since, as it was written, the whole interpolation is skipped |
| if any error occurs inside it.</p> |
| |
| <p>If an error occurs when evaluating the value of a parameter |
| for a directive call, or if there are other problems with the |
| parameter list, or if an error occurs when evaluating |
| <code class="inline-code"><em class="code-color">exp</em></code> in |
| <code class="inline-code"><@<em class="code-color">exp</em> |
| <em class="code-color">...</em>></code>, or if the value of |
| <code class="inline-code"><em class="code-color">exp</em></code> is not an |
| user-defined directive, then the whole directive call is skipped. |
| For example this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a<#if badVar>Foo</#if>b</pre></div> |
| |
| <p>will print this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">a[ERROR: Expression badVar is undefined on line 1, column 7 in test.ftl.]b</pre></div> |
| |
| <p>Note that the error occurred in the <code class="inline-code">if</code> |
| start-tag (<code class="inline-code"><#if badVar></code>), but the whole |
| directive call was skipped. Logically, the nested content |
| (<code class="inline-code">Foo</code>) was skipped with this, since the nested |
| content is handled (printed) by the enclosing directive |
| (<code class="inline-code">if</code>).</p> |
| |
| <p>The output will be the same with this (except that the column |
| number will differ...):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a<#if "foo${badVar}" == "foobar">Foo</#if>b</pre></div> |
| |
| <p>since, as it was written, the whole directive calling will be |
| skipped if any error occurs during the parameter evaluation.</p> |
| |
| <p>The directive call will not be skipped if the error occurs |
| after the execution of the directive was already started. That is, |
| if an error occurs in the nested content:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a |
| <#if true> |
| Foo |
| ${badVar} |
| Bar |
| </#if> |
| c</pre></div> |
| |
| <p>or in the macro definition body:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">a |
| <@test /> |
| b |
| <#macro test> |
| Foo |
| ${badVar} |
| Bar |
| </#macro></pre></div> |
| |
| <p>the output will be something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">a |
| Foo |
| [ERROR: Expression badVar is undefined on line 4, column 5 in test.ftl.] |
| Bar |
| c</pre></div> |
| |
| <p>FreeMarker comes with these prewritten error handlers:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler.DEBUG_HANDLER</code>: |
| Prints stack trace (includes FTL error message and FTL stack |
| trace) and re-throws the exception. This is the default handler |
| (that is, it is initially prugged into all new |
| <code class="inline-code">Configuration</code> objects).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler.HTML_DEBUG_HANDLER</code>: |
| Same as <code class="inline-code">DEBUG_HANDLER</code>, but it formats the |
| stack trace so that it will be readable with Web browsers. |
| Recommended over <code class="inline-code">DEBUG_HANDLER</code> when you |
| generate HTML pages.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler.IGNORE_HANDLER</code>: |
| Simply suppresses all exceptions (but remember, FreeMarker will |
| still log them). It does nothing to handle the event. It does |
| not re-throw the exception.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler.RETHROW_HANDLER</code>: |
| Simply re-throws all exceptions, it doesn't do anything else. |
| This handler can be good for Web applications (assuming you |
| don't want to continue template processing after exception), |
| because it gives the most control to the Web application over |
| page generation on error conditions (since FreeMarker doesn't |
| print anything to the output about the error). For more |
| information about handling errors in Web applications <a href="#misc.faq.niceErrorPage">see the FAQ</a>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_45">Explicit error handling in templates</h5> |
| |
| |
| <p>Although it has nothing to do with the FreeMarker |
| configuration (the topic of this chapter), for the sake of |
| completeness it is mentioned here that you can handle errors |
| directly in templates as well. This is usually a bad practice (try |
| keep templates simple and non-technical), but nonetheless necessary |
| sometimes:</p> |
| |
| <ul> |
| <li> |
| <p>Handling missing/null variables: <a href="#dgui_template_exp_missing">Template Author's Guide/The Template/Expressions/Handling missing values</a></p> |
| </li> |
| |
| <li> |
| <p>Surviving malfunctioning ``portlets'' and such expendable |
| page sections: <a href="#ref_directive_attempt">Reference/Directive Reference/attempt, recover</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="pgui_misc">Miscellaneous</h3> |
| |
| |
| <p>This is just an introductory guide. See the <a href="api/index.html">FreeMarker Java API documentation</a> for the |
| details.</p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_var">Variables</h4> |
| |
| |
| |
| |
| <p>This chapter explains what happens when a template tries to |
| access a variable, and how the variables are stored.</p> |
| |
| <p>When you call <code class="inline-code">Template.process</code> it will |
| internally create an <code class="inline-code">Environment</code> object that will |
| be in use until <code class="inline-code">process</code> returns. This object stores |
| the runtime state of template processing. Among other things, it |
| stores the variables created by the template with directives like |
| <code class="inline-code">assign</code>, <code class="inline-code">macro</code>, |
| <code class="inline-code">local</code> or <code class="inline-code">global</code>. It never tries |
| to modify the data-model object that you pass to the |
| <code class="inline-code">process</code> call, nor does it create or replace shared |
| variables stored in the configuration.</p> |
| |
| <p>When you try to read a variable, FreeMarker will seek the |
| variable in this order, and stops when it finds a variable with the |
| right name:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>In the Environment:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If you are in a loop, in the set of loop variables. Loop |
| variables are the variables created by directives like |
| <code class="inline-code">list</code>.</p> |
| </li> |
| |
| <li> |
| <p>If you are inside a macro, in the local variable set of |
| the macro. Local variables can be created with the |
| <code class="inline-code">local</code> directive. Also, the parameters of |
| macros are local variables.</p> |
| </li> |
| |
| <li> |
| <p>In the current <a href="#dgui_misc_namespace">namespace</a>. You can put |
| variables into a namespace with the <code class="inline-code">assign</code> |
| directive.</p> |
| </li> |
| |
| <li> |
| <p>In the set of variables created with |
| <code class="inline-code">global</code> directive. FTL handles these |
| variables as if they were normal members of the data-model. |
| That is, they are visible in all namespaces, and you can |
| access them as if they would be in the data-model.</p> |
| </li> |
| </ol></div> |
| </li> |
| |
| <li> |
| <p>In the data-model object you have passed to the |
| <code class="inline-code">process</code> method</p> |
| </li> |
| |
| <li> |
| <p>In the set of shared variables stored in the |
| <code class="inline-code">Configuration</code></p> |
| </li> |
| </ol></div> |
| |
| <p>In practice, from the viewpoint of template authors these 6 |
| layers are only 4 layers, since from that viewpoint the last 3 layers |
| (variables created with <code class="inline-code">global</code>, the actual |
| data-model object, shared variables) together constitute the set of |
| global variables.</p> |
| |
| <p>Note that it is possible to get variables from a specific layer |
| in FTL with <a href="#ref_specvar">special |
| variables</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_charset">Charset issues</h4> |
| |
| |
| |
| |
| |
| |
| <p>FreeMarker, as most Java applications, works with "<a href="#gloss.unicode">UNICODE</a> text" (UTF-16). Nonetheless, |
| there are situations when it must deal with <a href="#gloss.charset">charsets</a>, because it has to exchange |
| data with the outer world that may uses various charsets.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_46">The charset of the input</h5> |
| |
| |
| <p>When FreeMarker has to load a template file (or an unparsed |
| text file), then it must know the charset of the file, since files |
| are just raw byte arrays. You can use the |
| <code class="inline-code">encoding</code> <a href="#pgui_config_settings">setting</a> to specify the |
| charset. This setting takes effect only when FreeMarker loads a |
| template (parsed or unparsed) with the |
| <code class="inline-code">getTemplate</code> method of |
| <code class="inline-code">Configuration</code>. Note that the <a href="#ref.directive.include"><code>include</code> |
| directive</a> uses this method internally, so the value of the |
| <code class="inline-code">encoding</code> setting is significant for an already |
| loaded template if the template contains <code class="inline-code">include</code> |
| directive call.</p> |
| |
| <p>The getter and setter method of the |
| <code class="inline-code">encoding</code> setting is special in the first |
| (configuration) layer. The getter method guesses the return value |
| based on a <code class="inline-code">Locale</code> passed as parameter; it looks |
| up the encoding in a table that maps locales to encodings (called |
| encoding map), and if the locale was not found there, it returns the |
| default encoding. You can fill the encoding map with the |
| <code class="inline-code">setEncoding(Locale locale, String encoding)</code> |
| method of the configuration; the encoding map is initially empty. |
| The default encoding is initially the value of the |
| <code class="inline-code">file.encoding</code> system property, but you can set a |
| different default with the <code class="inline-code">setDefaultEncoding</code> |
| method.</p> |
| |
| <p>You can give the charset directly by overriding the |
| <code class="inline-code">encoding</code> setting in the template layer or runtime |
| environment layer (When you specify an encoding as the parameter of |
| <code class="inline-code">getTemplate</code> method, you override the |
| <code class="inline-code">encoding</code> setting in the template layer.). If you |
| don't override it, the effective value will be what the |
| <code class="inline-code">configuration.getEncoding(Locale)</code> method returns |
| for the effective value of the <code class="inline-code">locale</code> |
| setting.</p> |
| |
| <p>Also, instead of relying on this charset guessing mechanism, |
| you can specify the charset of the template in the template file |
| itself, with the <a href="#ref.directive.ftl"><code>ftl</code></a> |
| directive.</p> |
| |
| <p>You may wonder what charset you should choose for the |
| templates. It primarily depends on the tools (as text editors) that |
| you want to use to create and modify templates. In principle, using |
| UTF-8 is the best, but currently (2004) only a few tools supports |
| it, actually most of them doesn't even know about charsets. So in |
| that case you should use the widely used charset of your language, |
| which is probably also the default charset of you working |
| environment.</p> |
| |
| <p>Note that the charset of the template is independent from the |
| charset of the output that the tempalte generates (unless the |
| enclosing software deliberately sets the output charset to the same |
| as the template charset).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_47">The charset of the output</h5> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">output_encoding</code> setting/variable and |
| the <a href="#ref_builtin_url"><code>url</code> |
| built-in</a> is available since FreeMarker 2.3.1. It doesn't |
| exist in 2.3.</p> |
| </div> |
| |
| |
| <p>In principle FreeMarker does not deal with the charset |
| of the output, since it writes the output to a |
| <code class="inline-code">java.io.Writer</code>. Since the |
| <code class="inline-code">Writer</code> is made by the software that encapsulates |
| FreeMarker (such as a Web application framework), the output charset |
| is controlled by the encapsulating software. Still, FreeMarker has a |
| setting called <code class="inline-code">output_encoding</code> (starting from |
| FreeMarker version 2.3.1). The enclosing software should set this |
| setting (to the charset that the <code class="inline-code">Writer</code> uses), to |
| inform FreeMarker what charset is used for the output (otherwise |
| FreeMarker can't find it out). Some features, such as the <a href="#ref_builtin_url"><code>url</code> built-in</a>, |
| and the <a href="#ref_specvar"><code>output_encoding</code> special |
| variable</a> utilize this information. Thus, if the enclosing |
| software doesn't set this setting then FreeMarker features that need |
| to know the output charset can't be used.</p> |
| |
| <p>If you write software that will use FreeMarker, you may wonder |
| what output charset should you choose. Of course it depends on the |
| consumer of the FreeMarker output, but if the consumer is flexible |
| regarding this question, then the common practice is either using |
| the charset of the template file for the output, or using UTF-8. |
| Using UTF-8 is usually a better practice, because arbitrary text may |
| comes from the data-model, which then possibly contains characters |
| that couldn't be encoded with the charset of the template.</p> |
| |
| <p>FreeMarker settings can be set for each individual template |
| processing if you use |
| <code class="inline-code">Template.createProcessingEnvironment(<em class="code-color">...</em>)</code> |
| plus |
| <code class="inline-code">Environment.process(<em class="code-color">...</em>)</code> |
| instead of |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code>. |
| Thus, you can set the <code class="inline-code">output_encoding</code> setting for |
| each template execution independently:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Writer w = new OutputStreamWriter(out, outputCharset); |
| Environment env = template.createProcessingEnvironment(dataModel, w); |
| env.setOutputEncoding(outputCharset); |
| env.process();</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_multithreading">Multithreading</h4> |
| |
| |
| |
| |
| |
| |
| <p>In a multithreaded environment <code class="inline-code">Configuration</code> |
| instances, <code class="inline-code">Template</code> instances and data-models |
| should be handled as immutable (read-only) objects. That is, you |
| create and initialize them (for example with |
| <code class="inline-code">set<em class="code-color">...</em></code> methods), and |
| then you don't modify them later (e.g. you don't call |
| <code class="inline-code">set<em class="code-color">...</em></code>). This allows us |
| to avoid expensive synchronized blocks in a multithreaded environment. |
| Beware with <code class="inline-code">Template</code> instances; when you get a |
| <code class="inline-code">Template</code> instance with |
| <code class="inline-code">Configuration.getTemplate</code>, you may get an instance |
| from the template cache that is already used by other threads, so do |
| not call its <code class="inline-code">set<em class="code-color">...</em></code> |
| methods (calling <code class="inline-code">process</code> is of course fine).</p> |
| |
| <p>The above restrictions do not apply if you access all objects |
| from the <em>same</em> single thread only.</p> |
| |
| <p>It is impossible to modify the data-model object or a <a href="#pgui_config_sharedvariables">shared variable</a> with FTL, |
| unless you put methods (or other objects) into the data-model that do |
| that. We discourage you from writing methods that modify the |
| data-model object or the shared variables. Try to use variables that |
| are stored in the environment object instead (this object is created |
| for a single <code class="inline-code">Template.process</code> call to store the |
| runtime state of processing), so you don't modify data that are |
| possibly used by multiple threads. For more information read: <a href="#pgui_misc_var">Variables</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_beanwrapper">Bean wrapper</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>The <code class="inline-code">freemarker.ext.beans.BeansWrapper</code> is an |
| <a href="#pgui_datamodel_objectWrapper">object wrapper</a> |
| that was originally added to FreeMarker so arbitrary POJO-s (Plain Old |
| Java Objects) can be wrapped into <code class="inline-code">TemplateModel</code> |
| interfaces. Since then it has becomed the normal way of doing things, |
| and in fact the <code class="inline-code">DefaultObjectWrapper</code> itself is a |
| <code class="inline-code">BeansWrapper</code> extension. So everything described |
| here goes for the <code class="inline-code">DefaultObjectWrapper</code> too, except |
| that the <code class="inline-code">DefaultObjectWrapper</code> will wrap |
| <code class="inline-code">String</code>, <code class="inline-code">Number</code>, |
| <code class="inline-code">Date</code>, <code class="inline-code">array</code>, |
| <code class="inline-code">Collection</code> (like <code class="inline-code">List</code>), |
| <code class="inline-code">Map</code>, <code class="inline-code">Boolean</code> and |
| <code class="inline-code">Iterator</code> objects with the |
| <code class="inline-code">freemarker.template.Simple<em class="code-color">Xxx</em></code> |
| classes, and W3C DOM nodes with |
| <code class="inline-code">freemarker.ext.dom.NodeModel</code> (<a href="#xgui">more about wrapped W3C DOM...</a>), so for those the |
| above described rules doesn't apply.</p> |
| |
| <p>You will want to use <code class="inline-code">BeansWrapper</code> instead of |
| <code class="inline-code">DefaultObjectWrapper</code> when any of these |
| stands:</p> |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">Collection</code>-s and |
| <code class="inline-code">Map</code>-s of the model should be allowed to be |
| modified during template execution. |
| (<code class="inline-code">DefaultObjectWrapper</code> prevents that, since it |
| creates a copy of the collections when they are wrapped, and the |
| copies will be read-only.)</p> |
| </li> |
| |
| <li> |
| <p>If the identity of the <code class="inline-code">array</code>, |
| <code class="inline-code">Collection</code> and <code class="inline-code">Map</code> objects |
| must be kept when they are passed to a wrapped object's method in |
| the template. That is, if those methods must get exactly the same |
| object that was earlier wrapped.</p> |
| </li> |
| |
| <li> |
| <p>If the Java API of the earlier listed classes |
| (<code class="inline-code">String</code>, <code class="inline-code">Map</code>, |
| <code class="inline-code">List</code> ...etc) should be visible for the |
| templates. Even with <code class="inline-code">BeansWrapper</code>, they are not |
| visible by default, but it can be achieved by setting the exposure |
| level (see later). Note that this is usually a bad practice; try |
| to use <a href="#ref_builtins">the built-ins</a> (like |
| <code class="inline-code">foo?size</code>, <code class="inline-code">foo?upper</code>, |
| <code class="inline-code">foo?replace('_', '-')</code> ...etc) instead of the |
| Java API.</p> |
| </li> |
| </ul> |
| |
| <p>Below is a summary of the <code class="inline-code">TemplateModel</code>-s |
| that the <code class="inline-code">BeansWrapper</code> creates. Let's assume that |
| the object is called <code class="inline-code">obj</code> before wrapping, and |
| <code class="inline-code">model</code> after wrapping for the sake of the following |
| discussion.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="beanswrapper_hash">TemplateHashModel functionality</h5> |
| |
| |
| <p>Every object will be wrapped into a |
| <code class="inline-code">TemplateHashModel</code> that will expose JavaBeans |
| properties and methods of the object. This way, you can use |
| <code class="inline-code">model.foo</code> in the template to invoke |
| <code class="inline-code">obj.getFoo()</code> or <code class="inline-code">obj.isFoo()</code> |
| methods. (Note that public fields are not visible directly; you must |
| write a getter method for them.) Public methods are also retrievable |
| through the hash model as template method models, therefore you can |
| use the <code class="inline-code">model.doBar()</code> to invoke |
| <code class="inline-code">object.doBar()</code>. More on this on discussion of |
| method model functionality.</p> |
| |
| <p>If the requested key can not be mapped to a bean property or |
| method, the framework will attempt to locate the so-called "generic |
| get method", that is a method with signature public |
| <code class="inline-code"><em class="code-color">any-return-type</em> |
| get(String)</code> or public |
| <code class="inline-code"><em class="code-color">any-return-type</em> |
| get(Object)</code> and invoke that method with the requested key. |
| Note that this allows convenient access to mappings in a |
| <code class="inline-code">java.util.Map</code> and similar classes - as long as |
| the keys of the map are <code class="inline-code">String</code>s and some property |
| or method name does not shadow the mapping. (There is a solution to |
| avoid shadowing, read on.) Also note that the models for |
| <code class="inline-code">java.util.ResourceBundle</code> objects use the |
| <code class="inline-code">getObject(String)</code> as the generic get |
| method.</p> |
| |
| <p>If you call <code class="inline-code">setExposeFields(true)</code> on a |
| <code class="inline-code">BeansWrapper</code> instance, it will also expose |
| public, non-static fields of classes as hash keys and values. I.e. |
| if <code class="inline-code">foo</code> is a public, non-static field of the class |
| <code class="inline-code">Bar</code>, and <code class="inline-code">bar</code> is a template |
| variable wrapping an instance of <code class="inline-code">Bar</code>, then |
| <code class="inline-code">bar.foo</code> expression will evaluate as the value of |
| the field <code class="inline-code">foo</code> of the <code class="inline-code">bar</code> |
| object. The public fields in all superclasses of the class are also |
| exposed.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_48">A word on security</h5> |
| |
| |
| <p>By default, you will not be able to access several methods |
| that are considered not safe for templating. For instance, you can't |
| use synchronization methods (<code class="inline-code">wait</code>, |
| <code class="inline-code">notify</code>, <code class="inline-code">notifyAll</code>), thread and |
| thread group management methods (<code class="inline-code">stop</code>, |
| <code class="inline-code">suspend</code>, <code class="inline-code">resume</code>, |
| <code class="inline-code">setDaemon</code>, <code class="inline-code">setPriority</code>), |
| reflection (<code class="inline-code">Field</code> |
| <code class="inline-code">set<em class="code-color">Xxx</em></code> methods, |
| <code class="inline-code">Method.invoke</code>, |
| <code class="inline-code">Constructor.newInstance</code>, |
| <code class="inline-code">Class.newInstance</code>, |
| <code class="inline-code">Class.getClassLoader</code> etc.) and various dangerous |
| methods in <code class="inline-code">System</code> and <code class="inline-code">Runtime</code> |
| classes (<code class="inline-code">exec</code>, <code class="inline-code">exit</code>, |
| <code class="inline-code">halt</code>, <code class="inline-code">load</code>, etc.). The |
| <code class="inline-code">BeansWrapper</code> has several security levels (called |
| "levels of method exposure"), and the default called |
| <code class="inline-code">EXPOSE_SAFE</code> is probably suited for most |
| applications. There is a no-safeguard level called |
| <code class="inline-code">EXPOSE_ALL</code> that allows you to call even the above |
| unsafe methods, and a strict level |
| <code class="inline-code">EXPOSE_PROPERTIES_ONLY</code> that will expose only bean |
| property getters. Finally, there is a level named |
| <code class="inline-code">EXPOSE_NOTHING</code> that will expose no properties and |
| no methods. The only data you will be able to access through hash |
| model interface in this case are items in maps and resource bundles, |
| as well as objects returned from a call to generic |
| <code class="inline-code">get(Object)</code> or <code class="inline-code">get(String)</code> |
| methods - provided the affected objects have such method.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_49">TemplateScalarModel functionality</h5> |
| |
| |
| <p>Models for <code class="inline-code">java.lang.String</code> objects will |
| implement <code class="inline-code">TemplateScalarModel</code> whose |
| <code class="inline-code">getAsString()</code> method simply delegates to |
| <code class="inline-code">toString()</code>. Note that wrapping |
| <code class="inline-code">String</code> objects into Bean wrappers provides much |
| more functionality than just them being scalars: because of the hash |
| interface described above, the models that wrap |
| <code class="inline-code">String</code>s also provide access to all |
| <code class="inline-code">String</code> methods (<code class="inline-code">indexOf</code>, |
| <code class="inline-code">substring</code>, etc.).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_50">TemplateNumberModel functionality</h5> |
| |
| |
| <p>Model wrappers for objects that are instances of |
| <code class="inline-code">java.lang.Number</code> implement |
| <code class="inline-code">TemplateNumberModel</code> whose |
| <code class="inline-code">getAsNumber()</code> method returns the wrapped number |
| object. Note that wrapping <code class="inline-code">Number</code> objects into |
| Bean wrappers provides much more functionality than just them being |
| number models: because of the hash interface described above, the |
| models that wrap <code class="inline-code">Number</code>s also provide access to |
| all their methods.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_51">TemplateCollectionModel functionality</h5> |
| |
| |
| <p>Model wrappers for native Java arrays and all classes that |
| implement <code class="inline-code">java.util.Collection</code> will implement |
| <code class="inline-code">TemplateCollectionModel</code> and thus gain the |
| additional capability of being usable through |
| <code class="inline-code">list</code> directive.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_52">TemplateSequenceModel functionality</h5> |
| |
| |
| <p>Model wrappers for native Java arrays and all classes that |
| implement <code class="inline-code">java.util.List</code> will implement |
| <code class="inline-code">TemplateSequenceModel</code> and thus their elements |
| will be accessible by index using the <code class="inline-code">model[i]</code> |
| syntax. You can also query the length of the array or the size of |
| the list using the <code class="inline-code">model?size</code> built-in.</p> |
| |
| <p>Also, every method that takes a single parameter that is |
| assignable through reflective method invocation from a |
| <code class="inline-code">java.lang.Integer</code> (these are |
| <code class="inline-code">int</code>, <code class="inline-code">long</code>, |
| <code class="inline-code">float</code>, <code class="inline-code">double</code>, |
| <code class="inline-code">java.lang.Object</code>, |
| <code class="inline-code">java.lang.Number</code>, and |
| <code class="inline-code">java.lang.Integer</code>) also implements this |
| interface. What this means is that you have a convenient way for |
| accessing the so-called indexed bean properties: |
| <code class="inline-code">model.foo[i]</code> will translate into |
| <code class="inline-code">obj.getFoo(i)</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="beanswrapper_method">TemplateMethodModel functionality</h5> |
| |
| |
| <p>All methods of an object are represented as |
| <code class="inline-code">TemplateMethodModelEx</code> objects accessible using a |
| hash key with method name on their object's model. When you call a |
| method using |
| <code class="inline-code">model.<em class="code-color">method</em>(<em class="code-color">arg1</em>, |
| <em class="code-color">arg2</em>, |
| <em class="code-color">...</em>)</code> the arguments are passed |
| to the method as template models. The method will first try to |
| unwrap them - see below for details about unwrapping. These |
| unwrapped arguments are then used for the actual method call. In |
| case the method is overloaded, the most specific method will be |
| selected using the same rules that are used by the Java compiler to |
| select a method from several overloaded methods. In case that no |
| method signature matches the passed parameters, or that no method |
| can be chosen without ambiguity, a |
| <code class="inline-code">TemplateModelException</code> is thrown.</p> |
| |
| <p>Methods of return type <code class="inline-code">void</code> return |
| <code class="inline-code">TemplateModel.NOTHING</code>, so they can be safely |
| called with the <code class="inline-code">${obj.method(args)}</code> |
| syntax.</p> |
| |
| <p>Models for instances of <code class="inline-code">java.util.Map</code> also |
| implement <code class="inline-code">TemplateMethodModelEx</code> as a means for |
| invoking their <code class="inline-code">get()</code> method. As it was discussed |
| previously, you can use the hash functionality to access the "get" |
| method as well, but it has several drawbacks: it's slower because |
| first property and method names are checked for the key; keys that |
| conflict with property and method names will be shadowed by them; |
| finally you can use <code class="inline-code">String</code> keys only with that |
| approach. In contrast, invoking <code class="inline-code">model(key)</code> |
| translates to <code class="inline-code">model.get(key)</code> directly: it's |
| faster because there's no property and method name lookup; it is |
| subject to no shadowing; and finally it works for non-String keys |
| since the argument is unwrapped just as with ordinary method calls. |
| In effect, <code class="inline-code">model(key)</code> on a <code class="inline-code">Map</code> |
| is equal to <code class="inline-code">model.get(key)</code>, only shorter to |
| write.</p> |
| |
| <p>Models for <code class="inline-code">java.util.ResourceBundle</code> also |
| implement <code class="inline-code">TemplateMethodModelEx</code> as a convenient |
| way of resource access and message formatting. A single-argument |
| call to a bundle will retrieve the resource with the name that |
| corresponds to the <code class="inline-code">toString()</code> value of the |
| unwrapped argument. A multiple-argument call to a bundle will also |
| retrieve the resource with the name that corresponds to the |
| <code class="inline-code">toString()</code> value of the unwrapped argument, but |
| it will use it as a format pattern and pass it to |
| <code class="inline-code">java.text.MessageFormat</code> using the unwrapped |
| values of second and later arguments as formatting parameters. |
| <code class="inline-code">MessageFormat</code> objects will be initialized with |
| the locale of the bundle that originated them.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_53">Unwrapping rules</h5> |
| |
| |
| <p>When invoking a Java method from a template, its arguments |
| need to be converted from template models back to Java objects. |
| Assuming that the target type (the declared type of the method's |
| formal parameter) is denoted as <code class="inline-code">T</code>, the following |
| rules are tried in the following order:</p> |
| |
| <ul> |
| <li> |
| <p>If the model is the null model for this wrapper, Java |
| <code class="inline-code">null</code> is returned.</p> |
| </li> |
| |
| <li> |
| <p>If the model implements |
| <code class="inline-code">AdapterTemplateModel</code>, the result of |
| <code class="inline-code">model.getAdaptedObject(T)</code> is returned if it |
| is instance of <code class="inline-code">T</code> or it is a number and can be |
| converted to <code class="inline-code">T</code> using numeric coercion as |
| described three bullets lower. <span class="marked-for-programmers">All |
| models created by the BeansWrapper are themselves |
| AdapterTemplateModel implementations, so unwrapping a model that |
| was created by BeansWrapper for an underlying Java object always |
| yields the original Java object.</span></p> |
| </li> |
| |
| <li> |
| <p>If the model implements the deprecated |
| <code class="inline-code">WrapperTemplateModel</code>, the result of |
| <code class="inline-code">model.getWrappedObject()</code> is returned if it is |
| instance of <code class="inline-code">T</code> or it is a number and can be |
| converted to <code class="inline-code">T</code> using numeric coercion as |
| described two bullets lower.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is |
| <code class="inline-code">java.lang.String</code>, then if model implements |
| <code class="inline-code">TemplateScalarModel</code> its string value is |
| returned. <span class="marked-for-programmers">Note that if the model |
| doesn't implement TemplateScalarModel we don't attempt to |
| automatically convert the model to string using |
| String.valueOf(model). You'll have to use the ?string built-in |
| explicitly to pass non-scalars as strings.</span></p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is a primitive numeric type or |
| <code class="inline-code">java.lang.Number</code> is assignable from |
| <code class="inline-code">T</code>, and model implements |
| <code class="inline-code">TemplateNumberModel</code>, then its numeric value |
| is returned if it is instance of <code class="inline-code">T</code> or its |
| boxing type (if <code class="inline-code">T</code> is primitive type). |
| Otherwise, if <code class="inline-code">T</code> is a built-in Java numeric |
| type (primitive type or a standard subclass of |
| <code class="inline-code">java.lang.Number</code>, including |
| <code class="inline-code">BigInteger</code> and <code class="inline-code">BigDecimal</code>) |
| a new object of class <code class="inline-code">T</code> or its boxing type is |
| created with the number model's appropriately coerced |
| value.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is <code class="inline-code">boolean</code> or |
| <code class="inline-code">java.lang.Boolean</code>, and model implements |
| <code class="inline-code">TemplateBooleanModel</code>, then its boolean value |
| is returned.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is |
| <code class="inline-code">java.util.Map</code> and the model implements |
| <code class="inline-code">TemplateHashModel</code>, then a special Map |
| representation of the hash model is returned.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is |
| <code class="inline-code">java.util.List</code> and the model implements |
| <code class="inline-code">TemplateSequenceModel</code>, then a special List |
| representation of the sequence model is returned.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is |
| <code class="inline-code">java.util.Set</code> and the model implements |
| <code class="inline-code">TemplateCollectionModel</code>, then a special Set |
| representation of the collection model is returned.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is |
| <code class="inline-code">java.util.Collection</code> or |
| <code class="inline-code">java.lang.Iterable</code> and the model implements |
| either <code class="inline-code">TemplateCollectionModel</code> or |
| <code class="inline-code">TemplateSequenceModel</code>, then a special Set or |
| List representation of the collection or sequence model |
| (respectively) is returned.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is a Java array type and the model |
| implements <code class="inline-code">TemplateSequenceModel</code>, then a new |
| array of the specified type is created and its elements |
| unwrapped into the array recursively using the array's component |
| type as <code class="inline-code">T</code>.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">T</code> is <code class="inline-code">char</code> or |
| <code class="inline-code">java.lang.Character</code>, and model implements |
| <code class="inline-code">TemplateScalarModel</code>, and its string |
| representation contains exactly one character, then a |
| <code class="inline-code">java.lang.Character</code> with that value is |
| retured.</p> |
| </li> |
| |
| <li> |
| <p>If <code class="inline-code">java.util.Date</code> is assignable from |
| <code class="inline-code">T</code>, and model implements |
| <code class="inline-code">TemplateDateModel</code>, and its date value is |
| instance of <code class="inline-code">T</code>, then its date value is |
| returned.</p> |
| </li> |
| |
| <li> |
| <p>If model is a number model, and its numeric value is |
| instance of <code class="inline-code">T</code>, the numeric value is returned. |
| <span class="marked-for-programmers">You can have a custom subclass of |
| java.lang.Number that implements a custom interface, and T might |
| be that interface. (*)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a date model, and its date value is instance |
| of <code class="inline-code">T</code>, the date value is returned. <span class="marked-for-programmers">Similar consideration as for |
| (*)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a scalar model, and <code class="inline-code">T</code> is |
| assignable from <code class="inline-code">java.lang.String</code>, the string |
| value is returned. <span class="marked-for-programmers">This covers |
| cases when T is java.lang.Object, java.lang.Comparable, and |
| java.io.Serializable (**)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a boolean model, and <code class="inline-code">T</code> is |
| assignable from <code class="inline-code">java.lang.Boolean</code>, the |
| boolean value is returned. <span class="marked-for-programmers">Same as |
| (**)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a hash model, and <code class="inline-code">T</code> is |
| assignable from |
| <code class="inline-code">freemarker.ext.beans.HashAdapter</code>, a hash |
| adapter is returned. <span class="marked-for-programmers">Same as |
| (**)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a sequence model, and <code class="inline-code">T</code> is |
| assignable from |
| <code class="inline-code">freemarker.ext.beans.SequenceAdapter</code>, a |
| sequence adapter is returned. <span class="marked-for-programmers">Same |
| as (**)</span></p> |
| </li> |
| |
| <li> |
| <p>If model is a collection model, and <code class="inline-code">T</code> |
| is assignable from |
| <code class="inline-code">freemarker.ext.beans.SetAdapter</code>, a set |
| adapter for the collection is returned. <span class="marked-for-programmers">Same as (**)</span></p> |
| </li> |
| |
| <li> |
| <p>If the model is instance of <code class="inline-code">T</code>, the |
| model itself is returned. <span class="marked-for-programmers">This |
| covers the case where the method explicitly declared a |
| FreeMarker-specific model interface, as well as allows returning |
| directive, method and transform models when java.lang.Object is |
| requested.</span></p> |
| </li> |
| |
| <li> |
| <p>An exception signifying no conversion is possible is |
| thrown.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_54">Accessing static methods</h5> |
| |
| |
| |
| |
| <p>The <code class="inline-code">TemplateHashModel</code> returned from |
| <code class="inline-code">BeansWrapper.getStaticModels()</code> can be used to |
| create hash models for accessing static methods and fields of an |
| arbitrary class.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance(); |
| TemplateHashModel staticModels = wrapper.getStaticModels(); |
| TemplateHashModel fileStatics = |
| (TemplateHashModel) staticModels.get("java.io.File");</pre></div> |
| |
| <p>And you will get a template hash model that exposes all static |
| methods and static fields (both final and non-final) of the |
| <code class="inline-code">java.lang.System</code> class as hash keys. Suppose that |
| you put the previous model in your root model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("File", fileStatics);</pre></div> |
| |
| <p>From now on, you can use <code class="inline-code">${File.SEPARATOR}</code> |
| to insert the file separator character into your template, or you |
| can even list all roots of your file system by:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list File.listRoots() as fileSystemRoot>...</#list></pre></div> |
| |
| <p>Of course, you must be aware of the potential security issues |
| this model brings.</p> |
| |
| <p>You can even give the template authors complete freedom over |
| which classes' static methods they use by placing the static models |
| hash into your template root model with</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("statics", BeansWrapper.getDefaultInstance().getStaticModels());</pre></div> |
| |
| <p>This object exposes just about any class' static methods if |
| it's used as a hash with class name as the key. You can then use |
| expression like |
| <code class="inline-code">${statics["java.lang.System"].currentTimeMillis()}</code> |
| in your template. Note, however that this has even more security |
| implications, as someone could even invoke |
| <code class="inline-code">System.exit()</code> using this model if the method |
| exposure level is weakened to <code class="inline-code">EXPOSE_ALL</code>.</p> |
| |
| <p>Note that in above examples, we always use the default |
| <code class="inline-code">BeansWrapper</code> instance. This is a convenient |
| static wrapper instance that you can use in most cases. You are also |
| free to create your own <code class="inline-code">BeansWrapper</code> instances |
| and use them instead especially when you want to modify some of its |
| characteristics (like model caching, security level, or the null |
| model representation).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="jdk_15_enums">Accessing enums</h5> |
| |
| |
| <p>The <code class="inline-code">TemplateHashModel</code> returned from |
| <code class="inline-code">BeansWrapper.getEnumModels()</code> can be used to |
| create hash models for accessing values of enums on JRE 1.5 or |
| later. (An attempt to invoke this method on an earlier JRE will |
| result in an |
| <code class="inline-code">UnsupportedOperationException</code>.)</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance(); |
| TemplateHashModel enumModels = wrapper.getEnumModels(); |
| TemplateHashModel roundingModeEnums = |
| (TemplateHashModel) enumModels.get("java.math.RoundingMode");</pre></div> |
| |
| <p>And you will get a template hash model that exposes all enum |
| values of the <code class="inline-code">java.math.RoundingMode</code> class as |
| hash keys. Suppose that you put the previous model in your root |
| model:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("RoundingMode", roundingModeEnums);</pre></div> |
| |
| <p>From now on, you can use <code class="inline-code">RoundingMode.UP</code> as |
| an expression to reference the <code class="inline-code">UP</code> enum value in |
| your template.</p> |
| |
| <p>You can even give the template authors complete freedom over |
| which enum classes they use by placing the enum models hash into |
| your template root model with</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">root.put("enums", BeansWrapper.getDefaultInstance().getEnumModels());</pre></div> |
| |
| <p>This object exposes any enum class if it's used as a hash with |
| class name as the key. You can then use expression like |
| <code class="inline-code">${enums["java.math.RoundingMode"].UP}</code> in your |
| template.</p> |
| |
| <p>The exposed enum values can be used as scalars (they'll |
| delegate to their <code class="inline-code">toString()</code> method), and can be |
| used in equality and inequality comparisons as well.</p> |
| |
| <p>Note that in above examples, we always use the default |
| <code class="inline-code">BeansWrapper</code> instance. This is a convenient |
| static wrapper instance that you can use in most cases. You are also |
| free to create your own <code class="inline-code">BeansWrapper</code> instances |
| and use them instead especially when you want to modify some of its |
| characteristics (like model caching, security level, or the null |
| model representation).</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_logging">Logging</h4> |
| |
| |
| |
| |
| <p>FreeMarker integrates with the following logging packages: <a href="http://jakarta.apache.org/log4j">Log4J</a>, <a href="http://jakarta.apache.org/avalon/logkit">Avalon |
| LogKit</a>, and <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">java.util.logging</a> |
| (Java2 platform 1.4 and above). You need not do anything in order for |
| FreeMarker to use these loggers; if any of them is discovered through |
| the class loader that loaded FreeMarker classes, it is used |
| automatically. All log messages produced by FreeMarker are logged into |
| the logger hierarchy whose top-level logger is named |
| <code class="inline-code">freemarker</code>. Currently used loggers are:</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Logger name</th> |
| |
| |
| <th>Purpose</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">freemarker.beans</code></td> |
| |
| |
| <td>Logs messages of the Beans wrapper module.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.cache</code></td> |
| |
| |
| <td>Logs messages related to template loading and caching.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.runtime</code></td> |
| |
| |
| <td>Logs template exceptions thrown during template |
| processing.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.runtime.attempt</code></td> |
| |
| |
| <td>Logs template exceptions thrown during template processing, |
| but caught by |
| <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> |
| directives. Enable DEBUG severity to see the exceptions.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.servlet</code></td> |
| |
| |
| <td>Logs messages of the FreemarkerServlet class.</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>FreeMarker will look for the logging packages in this order, and |
| will use the first package it finds: Log4J, Avalon, java.util.logging. |
| However, if you call the static <code class="inline-code">selectLoggerLibrary</code> |
| method on the <code class="inline-code">freemarker.log.Logger</code> class with |
| appropriate parameter, you can explicitly select a logger package, or |
| even disable the logging.</p> |
| |
| <p>You can also call the static |
| <code class="inline-code">selectLoggerLibrary</code> method on the |
| <code class="inline-code">freemarker.log.Logger</code> class and pass it a string |
| that will be used to prefix the above mentioned logger names. This is |
| useful if you want to have separate loggers on a per-application |
| basis.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_servlet">Using FreeMarker with servlets</h4> |
| |
| |
| <a name="topic.servlet"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>In a fundamental sense, using FreeMarker in the web application |
| space is no different from anywhere else; FreeMarker writes its output |
| to a <code class="inline-code">Writer</code> that you pass to the |
| <code class="inline-code">Template.process</code> method, and it does not care if |
| that <code class="inline-code">Writer</code> prints to the console or to a file or |
| to the output stream of <code class="inline-code">HttpServletResponse</code>. |
| FreeMarker knows nothing about servlets and Web; it just merges Java |
| object with template files and generates text output from them. From |
| here, it is up to you how to build a Web application around |
| this.</p> |
| |
| <p>But, probably you want to user FreeMarker with some already |
| existing Web application framework. Many frameworks rely on the |
| ``Model 2'' architecture, where JSP pages handle presentation. If you |
| use such a framework (for example, <a href="http://jakarta.apache.org/struts">Apache Struts</a>), |
| then read on. For other frameworks please refer to the documentation |
| of the framework.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="pgui_misc_servlet_model2">Using FreeMarker for ``Model 2''</h5> |
| |
| |
| <p>Many frameworks follow the strategy that the HTTP request is |
| dispatched to user-defined ``action'' classes that put data into |
| <code class="inline-code">ServletContext</code>, <code class="inline-code">HttpSession</code> |
| and <code class="inline-code">HttpServletRequest</code> objects as attributes, and |
| then the request is forwarded by the framework to a JSP page (the |
| view) that will generate the HTML page using the data sent with the |
| attributes. This is often referred as Model 2.</p> |
| |
| <p class="center-img"> <img src="figures/model2sketch.png" alt="Figure"> </p> |
| |
| |
| <p>With these frameworks you can simply use FTL files instead of |
| JSP files. But, since your servlet container (Web application |
| server), unlike with JSP files, does not know out-of-the-box what to |
| do with FTL files, a little extra configuring is needed for your Web |
| application:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>Copy <code class="inline-code">freemarker.jar</code> (from the |
| <code class="inline-code">lib</code> directory of the FreeMarker distribution) |
| into the <code class="inline-code">WEB-INF/lib</code> directory of your Web |
| application.</p> |
| </li> |
| |
| <li> |
| <p>Insert the following section to the |
| <code class="inline-code">WEB-INF/web.xml</code> file of your Web application |
| (and adjust it if required):</p> |
| </li> |
| </ol></div> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><servlet> |
| <servlet-name>freemarker</servlet-name> |
| <servlet-class><strong>freemarker.ext.servlet.FreemarkerServlet</strong></servlet-class> |
| |
| <!-- FreemarkerServlet settings: --> |
| <init-param> |
| <param-name>TemplatePath</param-name> |
| <param-value>/</param-value> |
| </init-param> |
| <init-param> |
| <param-name>NoCache</param-name> |
| <param-value>true</param-value> |
| </init-param> |
| <init-param> |
| <param-name>ContentType</param-name> |
| <param-value>text/html</param-value> |
| </init-param> |
| |
| <!-- FreeMarker settings: --> |
| <init-param> |
| <param-name>template_update_delay</param-name> |
| <param-value>0</param-value> <!-- 0 is for development only! Use higher value otherwise. --> |
| </init-param> |
| <init-param> |
| <param-name>default_encoding</param-name> |
| <param-value>ISO-8859-1</param-value> |
| </init-param> |
| <init-param> |
| <param-name>number_format</param-name> |
| <param-value>0.##########</param-value> |
| </init-param> |
| |
| <load-on-startup>1</load-on-startup> |
| </servlet> |
| |
| <servlet-mapping> |
| <servlet-name>freemarker</servlet-name> |
| <url-pattern><strong>*.ftl</strong></url-pattern> |
| </servlet-mapping></pre></div> |
| |
| <p>That's all. After this, you can use FTL files |
| (<code class="inline-code">*.ftl</code>) in the same manner as JSP |
| (<code class="inline-code">*.jsp</code>) files. (Of course you can choose another |
| extension besides <code class="inline-code">ftl</code>; it is just the |
| convention)</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>How does it work? Let's examine how JSP-s work. Many servlet |
| container handles JSP-s with a servlet that is mapped to the |
| <code class="inline-code">*.jsp</code> request URL pattern. That servlet will |
| receive all requests where the request URL ends with |
| <code class="inline-code">.jsp</code>, find the JSP file based on the request |
| URL, and internally compiles it to a <code class="inline-code">Servlet</code>, |
| and then call the generated servlet to generate the page. The |
| <code class="inline-code">FreemarkerServlet</code> mapped here to the |
| <code class="inline-code">*.ftl</code> URL pattern does the same, except that |
| FTL files are not compiled to <code class="inline-code">Servlet</code>-s, but to |
| <code class="inline-code">Template</code> objects, and then the |
| <code class="inline-code">process</code> method of <code class="inline-code">Template</code> |
| will be called to generate the page.</p> |
| </div> |
| |
| |
| <p><a name="topic.servlet.scopeAttr"></a>For example, |
| instead of this JSP file (note that it heavily uses Struts tag-libs |
| to save designers from embedded Java monsters):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %> |
| <%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %> |
| |
| <html> |
| <head><title>Acmee Products International</title> |
| <body> |
| <h1>Hello <bean:write name="user"/>!</h1> |
| <p>These are our latest offers: |
| <ul> |
| <logic:iterate name="latestProducts" id="prod"> |
| <li><bean:write name="prod" property="name"/> |
| for <bean:write name="prod" property="price"/> Credits. |
| </logic:iterate> |
| </ul> |
| </body> |
| </html></pre></div> |
| |
| <p>you can use this FTL file (use <code class="inline-code">ftl</code> file |
| extension instead of <code class="inline-code">jsp</code>):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><html> |
| <head><title>Acmee Products International</title> |
| <body> |
| <h1>Hello ${user}!</h1> |
| <p>These are our latest offers: |
| <ul> |
| <#list latestProducts as prod> |
| <li>${prod.name} for ${prod.price} Credits. |
| </#list> |
| </ul> |
| </body> |
| </html></pre></div> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>In FreeMarker <code class="inline-code"><html:form |
| action="/query"><em class="code-color">...</em></html:form></code> |
| is just static text, so it is printed to the output as is, like |
| any other XML or HTML markup. JSP tags are just FreeMarker |
| directives, nothing special, so you <em>use FreeMarker |
| syntax</em> for calling them, not JSP syntax: |
| <code class="inline-code"><@html.form |
| action="/query"><em class="code-color">...</em></@html.form></code>. |
| Note that in the FreeMarker syntax you <em>don't use |
| <code class="inline-code">${<em class="code-color">...</em>}</code> in |
| parameters</em> as in JSP, and you <em>don't quote the |
| parameter values</em>. So this is |
| <em>WRONG</em>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- WRONG: --> |
| <@my.jspTag color="${aVariable}" name="aStringLiteral" |
| width="100" height=${a+b} /></pre></div> |
| |
| <p>and this is good:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- Good: --> |
| <@my.jspTag color=aVariable name="aStringLiteral" |
| width=100 height=a+b /></pre></div> |
| </div> |
| |
| |
| <p>In both templates, when you refer to <code class="inline-code">user</code> |
| and <code class="inline-code">latestProduct</code>, it will first try to find a |
| variable with that name that was created in the template (like |
| <code class="inline-code">prod</code>; if you master JSP: a page scope attribute). |
| If that fails, it will try to look up an attribute with that name in |
| the <code class="inline-code">HttpServletRequest</code>, and if it is not there |
| then in the <code class="inline-code">HttpSession</code>, and if it still doesn't |
| find it then in the <code class="inline-code">ServletContext</code>. In the case |
| of FTL this works because <code class="inline-code">FreemarkerServlet</code> |
| builds the data-model from the attributes of the mentioned 3 |
| objects. That is, in this case the root hash is not a |
| <code class="inline-code">java.util.Map</code> (as it was in some example codes in |
| this manual), but |
| <code class="inline-code">ServletContext</code>+<code class="inline-code">HttpSession</code>+<code class="inline-code">HttpServletRequest</code>; |
| FreeMarker is pretty flexible about what the data-model is. So if |
| you want to put variable <code class="inline-code">"name"</code> into the |
| data-model, then you call |
| <code class="inline-code">servletRequest.setAttribute("name", "Fred")</code>; this |
| is the logic of Model 2, and FreeMarker adapts itself to it.</p> |
| |
| <p><code class="inline-code">FreemarkerServlet</code> also puts 3 hashes into |
| the data-model, by which you can access the attributes of the 3 |
| objects directly. The hash variables are: |
| <code class="inline-code">Request</code>, <code class="inline-code">Session</code>, |
| <code class="inline-code">Application</code> (corresponds to |
| <code class="inline-code">ServletContext</code>). It also exposes another hash |
| named <code class="inline-code">RequestParameters</code> that provides access to |
| the parameters of the HTTP request.</p> |
| |
| <p><code class="inline-code">FreemarkerServlet</code> has various init-params. |
| It can be set up to load templates from an arbitrary directory, from |
| the classpath, or relative to the Web application directory. You can |
| set the charset used for templates. You can set up what object |
| wrapper do you want to use. Etc.</p> |
| |
| <p><code class="inline-code">FreemarkerServlet</code> is easily tailored to |
| special needs through subclassing. Say, if you need to have |
| additional variables available in your data-model for all templates, |
| subclass the servlet and override the |
| <code class="inline-code">preTemplateProcess()</code> method to shove any |
| additional data you need into the model before the template gets |
| processed. Or subclass the servlet, and set these globally available |
| variables as <a href="#pgui_config_sharedvariables">shared |
| variables</a> in the <code class="inline-code">Configuration</code>.</p> |
| |
| <p>For more information please read the Java API documentation of |
| the class.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="pgui_misc_servlet_include">Including content from other web application |
| resources</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>You can use the <code class="inline-code"><@include_page |
| path="..."/></code> custom directive provided by the |
| <code class="inline-code">FreemarkerServlet</code> (since 2.3.15) to include the |
| contents of another web application resource into the output; this |
| is often useful to integrate output of JSP pages (living alongside |
| the FreeMarker templates in the same web server) into the FreeMarker |
| template output. Using:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@include_page path="path/to/some.jsp"/></pre></div> |
| |
| <p>is identical to using this tag in JSP:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><jsp:include page="path/to/some.jsp"></pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p><code class="inline-code"><@include_page ...></code> is not to be |
| confused with <code class="inline-code"><#include ...></code>, as the last |
| is for including FreeMarker templates without involving the |
| Servlet container. An <code class="inline-code"><#include ...></code>-ed |
| template shares the template processing state with the including |
| template, such as the data-model and the template-language |
| variables, while <code class="inline-code"><@include_page ...></code> |
| starts an independent HTTP request processing.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>Some Web Application Frameworks provide their own solution |
| for this, in which case you possibly should use that instead. Also |
| some Web Application Frameworks don't use |
| <code class="inline-code">FreemarkerServlet</code>, so |
| <code class="inline-code">include_page</code> is not available.</p> |
| </div> |
| |
| |
| <p>The path can be relative or absolute. Relative paths are |
| interpreted relative to the URL of the current HTTP request (one |
| that triggered the template processing), while absolute paths are |
| absolute in the current servlet context (current web application). |
| You can not include pages from outside the current web application. |
| Note that you can include any page, not just a JSP page; we just |
| used page with path ending in <code class="inline-code">.jsp</code> as an |
| illustration.</p> |
| |
| <p>In addition to the <code class="inline-code">path</code> parameter, you can |
| also specify an optional parameter named |
| <code class="inline-code">inherit_params</code> with a boolean value (defaults to |
| true when not specified) that specifies whether the included page |
| will see the HTTP request parameters of the current request or |
| not.</p> |
| |
| <p>Finally, you can specify an optional parameter named |
| <code class="inline-code">params</code> that specifies new request parameters that |
| the included page will see. In case inherited parameters are passed |
| too, the values of specified parameters will get prepended to the |
| values of inherited parameters of the same name. The value of |
| <code class="inline-code">params</code> must be a hash, with each value in it |
| being either a string, or a sequence of strings (if you need |
| multivalued parameters). Here's a full example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@include_page path="path/to/some.jsp" inherit_params=true params={"foo": "99", "bar": ["a", "b"]}/></pre></div> |
| |
| <p>This will include the page |
| <code class="inline-code">path/to/some.jsp</code>, pass it all request parameters |
| of the current request, except for "foo" and "bar", which will be |
| set to "99" and multi-value of "a", "b", respectively. In case the |
| original request already had values for these parameters, the new |
| values will be prepended to the existing values. I.e. if "foo" had |
| values "111" and "123", then it will now have values "99", "111", |
| "123".</p> |
| |
| <p><span class="marked-for-programmers">It is in fact possible to pass |
| non-string values for parameter values within |
| <code class="inline-code">params</code>. Such a value will be converted to a |
| suitable Java object first (i.e. a Number, a Boolean, a Date, etc.), |
| and then its Java <code class="inline-code">toString()</code> method will be used |
| to obtain the string value. It is better to not rely on this |
| mechanism, though, and instead explicitly ensure that parameter |
| values that aren't strings are converted to strings on the template |
| level where you have control over formatting using the |
| <code class="inline-code">?string</code> and <code class="inline-code">?c</code> built-ins. |
| </span></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_55">Using JSP custom tags in FTL</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p><code class="inline-code">FreemarkerServlet</code> puts a hash |
| <code class="inline-code">JspTaglibs</code> into the data-model, what you can use |
| to access JSP taglibs. The JSP custom tags will be accessible as |
| plain user-defined directives. For example, this is a JSP file that |
| uses some Struts tags:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><%@page contentType="text/html;charset=ISO-8859-2" language="java"%> |
| <%@taglib uri="/WEB-INF/struts-html.tld" prefix="html"%> |
| <%@taglib uri="/WEB-INF/struts-bean.tld" prefix="bean"%> |
| |
| <html> |
| <body> |
| <h1><bean:message key="welcome.title"/></h1> |
| <html:errors/> |
| <html:form action="/query"> |
| Keyword: <html:text property="keyword"/><br> |
| Exclude: <html:text property="exclude"/><br> |
| <html:submit value="Send"/> |
| </html:form> |
| </body> |
| </html></pre></div> |
| |
| <p>And this is the (near) equivalent FTL:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign html=JspTaglibs["/WEB-INF/struts-html.tld"]> |
| <#assign bean=JspTaglibs["/WEB-INF/struts-bean.tld"]> |
| |
| <html> |
| <body> |
| <h1><@bean.message key="welcome.title"/></h1> |
| <@html.errors/> |
| <@html.form action="/query"> |
| Keyword: <@html.text property="keyword"/><br> |
| Exclude: <@html.text property="exclude"/><br> |
| <@html.submit value="Send"/> |
| </@html.form> |
| </body> |
| </html></pre></div> |
| |
| <p>Since JSP custom tags are written to operate in JSP |
| environment, they assume that variables (often referred as ``beans'' |
| in JSP world) are stored in 4 scopes: page scope, request scope, |
| session scope and application scope. FTL has no such notation (the 4 |
| scopes), but <code class="inline-code">FreemarkerServlet</code> provides emulated |
| JSP environment for the custom JSP tags, which maintains |
| correspondence between the ``beans'' of JSP scopes and FTL |
| variables. For the custom JSP tags, the request, session and |
| application scopes are exactly the same as with real JSP: the |
| attributes of the <code class="inline-code">javax.servlet.ServletContext</code>, |
| <code class="inline-code">HttpSession</code> and <code class="inline-code">ServerRequest</code> |
| objects. From the FTL side you see these 3 scopes together as the |
| data-model, as it was explained earlier. The page scope corresponds |
| to the FTL global variables (see the <a href="#ref.directive.global"><code>global</code> |
| directive</a>). That is, if you create a variable with the |
| <code class="inline-code">global</code> directive, it will be visible for the |
| custom tags as page scope variable through the emulated JSP |
| environment. Also, if a JSP-tag creates a new page scope variable, |
| the result will be the same as if you create a variable with the |
| <code class="inline-code">global</code> directive. Note that the variables in the |
| data-model are not visible as page-scope attributes for the JSP |
| tags, despite that they are globally visible, since the data-model |
| corresponds to the request, session and application scopes, not the |
| page-scope.</p> |
| |
| <p>On JSP pages you quote all attribute values, it does not mater |
| if the type of the parameter is string or boolean or number. But |
| since custom tags are accessible in FTL templates as user-defined |
| FTL directives, you have to use the FTL syntax rules inside the |
| custom tags, not the JSP rules. So when you specify the value of an |
| ``attribute'', then on the right side of the <code class="inline-code">=</code> |
| there is an <a href="#dgui_template_exp">FTL expression</a>. |
| Thus, <em>you must not quote boolean and numerical parameter |
| values</em> (e.g. <code class="inline-code"><@tiles.insert |
| page="/layout.ftl" flush=true/></code>), or they are |
| interpreted as string values, and this will cause a type mismatch |
| error when FreeMarker tries to pass the value to the custom tag that |
| expects non-string value. Also note, that naturally, you can use any |
| FTL expression as attribute value, such as variables, calculated |
| values, etc. (e.g. <code class="inline-code"><@tiles.insert page=layoutName |
| flush=foo && bar/></code>).</p> |
| |
| <p>FreeMarker does not rely on the JSP support of the servlet |
| container in which it is run when it uses JSP taglibs since it |
| implements its own lightweight JSP runtime environment. There is |
| only one small detail to pay attention to: to enable the FreeMarker |
| JSP runtime environment to dispatch events to JSP taglibs that |
| register event listeners in their TLD files, you should add this to |
| the <code class="inline-code">WEB-INF/web.xml</code> of your Web |
| application:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><listener> |
| <listener-class>freemarker.ext.jsp.EventForwarding</listener-class> |
| </listener></pre></div> |
| |
| <p>Note that you can use JSP taglibs with FreeMarker even if the |
| servlet container has no native JSP support, just make sure that the |
| <code class="inline-code">javax.servlet.jsp.*</code> packages for JSP 1.2 (or |
| later) are available to your Web application. If your servlet |
| container comes with JSP 1.1, then you have to obtain the following |
| six classes (for example you can extract them from the jar-s of |
| Tomcat 5.x or Tomcat 4.x), and copy them into your webapp's |
| <code class="inline-code">WEB-INF/classes/<em class="code-color">...</em></code> |
| directory: <code class="inline-code">javax.servlet.jsp.tagext.IterationTag</code>, |
| <code class="inline-code">javax.servlet.jsp.tagext.TryCatchFinally</code>, |
| <code class="inline-code">javax.servlet.ServletContextListener</code>, |
| <code class="inline-code">javax.servlet.ServletContextAttributeListener</code>, |
| <code class="inline-code">javax.servlet.http.HttpSessionAttributeListener</code>, |
| <code class="inline-code">javax.servlet.http.HttpSessionListener</code>. But |
| beware, since containers that come with JSP 1.1 usually use earlier |
| Serlvet versions than 2.3, event listeners will not be supported, |
| and thus JSP 1.2 taglibs that register event listeners will not work |
| properly.</p> |
| |
| <p>As of this writing, JSP features up to JSP 2.1 are |
| implemented, except the "tag files" feature of JSP 2 (i.e., custom |
| JSP tags <em>implemented</em> in JSP language). The tag |
| files had to be compiled to Java classes to be usable under |
| FreeMarker.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_56">Embed FTL into JSP pages</h5> |
| |
| |
| |
| |
| <p>There is a taglib that allows you to put FTL fragments into |
| JSP pages. The embedded FTL fragment can access the attributes |
| (Beans) of the 4 JSP scopes. You can find a working example and the |
| taglib in the FreeMarker distribution.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_secureenv">Configuring security policy for FreeMarker</h4> |
| |
| |
| |
| |
| <p>When FreeMarker is used in a Java virtual machine with a |
| security manager installed, you have to grant it few permissions to |
| ensure it operates properly. Most notably, you need these entries to |
| your security policy file for |
| <code class="inline-code">freemarker.jar</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">grant codeBase "file:/path/to/freemarker.jar" |
| { |
| permission java.util.PropertyPermission "file.encoding", "read"; |
| permission java.util.PropertyPermission "freemarker.*", "read"; |
| }</pre></div> |
| |
| <p>Additionally, if you are loading templates from a directory, you |
| need to give FreeMarker permissions to read files from that directory |
| using the following permission:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">grant codeBase "file:/path/to/freemarker.jar" |
| { |
| ... |
| permission java.io.FilePermission "/path/to/templates/-", "read"; |
| }</pre></div> |
| |
| <p>Finally, if you're just using the default template loading |
| mechanism which loads templates from the current directory, then |
| specify these permissions additionally: (note that the expression |
| <code class="inline-code">${user.dir}</code> will be evaluated at run time by the |
| policy interpreter, pretty much as if it were a FreeMarker |
| template)</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"> |
| grant codeBase "file:/path/to/freemarker.jar" |
| { |
| ... |
| permission java.util.PropertyPermission "user.dir", "read"; |
| permission java.io.FilePermission "${user.dir}/-", "read"; |
| }</pre></div> |
| |
| <p>Naturally, if you're running under Windows, use double backslash |
| instead of a single slash for separating directory components in |
| paths.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_xml_legacy">Legacy XML wrapper implementation</h4> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p><em>The legacy XML wrapper is deprecated.</em> |
| FreeMarker 2.3 has introduced support for a new XML processing |
| model. To support this, a new XML wrapper package was introduced, |
| <code class="inline-code">freemarker.ext.dom</code>. For new usage, we encourage |
| you to use that. It is documented in the part <a href="#xgui">XML Processing Guide</a>.</p> |
| </div> |
| |
| |
| <p>The class <code class="inline-code">freemarker.ext.xml.NodeListModel</code> |
| provides a template model for wrapping XML documents represented as |
| node trees. Every node list can contain zero or more XML nodes |
| (documents, elements, texts, processing instructions, comments, entity |
| references, CDATA sections, etc.). The node list implements the |
| following template model interfaces with the following |
| semantics:</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_57">TemplateScalarModel</h5> |
| |
| |
| <p>When used as a scalar, the node list will render the XML |
| fragment that represents its contained nodes. This makes it handy |
| for use in XML-to-XML transforming templates.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_58">TemplateCollectionModel</h5> |
| |
| |
| <p>When used as a collection with <code class="inline-code">list</code> |
| directive, it will simply enumerate its nodes. Every node will be |
| returned as a new node list consisting of a single node.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_59">TemplateSequenceModel</h5> |
| |
| |
| <p>When used as a sequence, it will return the i-th node as a new |
| node list consisting of the single requested node. I.e. to return |
| the 3rd <code class="inline-code"><chapter></code> element of the |
| <code class="inline-code"><book></code> element, you'd use the following |
| (note indexes are zero-based):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign 3rdChapter = xmldoc.book.chapter[2]></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_60">TemplateHashModel</h5> |
| |
| |
| <p>When used as a hash, it is basically used to traverse |
| children. That is, if you have a node list named |
| <code class="inline-code">book</code> that wraps an element node with several |
| chapters, then the <code class="inline-code">book.chapter</code> will yield a node |
| list with all chapter elements of that book element. The at sign is |
| used to refer to attributes: <code class="inline-code">book.@title</code> yields a |
| node list with a single attribute node, that is the title attribute |
| of the book element.</p> |
| |
| <p>It is important to realize the consequence that, for example, |
| if <code class="inline-code">book</code> has no <code class="inline-code">chapter</code>-s then |
| <code class="inline-code">book.chapter</code> is an empty sequence, so |
| <code class="inline-code">xmldoc.book.chapter??</code> will |
| <em>not</em> be <code class="inline-code">false</code>, it will be |
| always <code class="inline-code">true</code>! Similarly, |
| <code class="inline-code">xmldoc.book.somethingTotallyNonsense??</code> will not |
| be <code class="inline-code">false</code> either. To check if there was no |
| children found, use <code class="inline-code">xmldoc.book.chapter?size == |
| 0</code>.</p> |
| |
| <p>The hash defines several "magic keys" as well. All these keys |
| start with an underscore. The most notable is the |
| <code class="inline-code">_text</code> key which retrieves the text of the node: |
| <code class="inline-code">${book.@title._text}</code> will render the value of the |
| attribute into the template. Similarly, <code class="inline-code">_name</code> |
| will retrieve the name of the element or attribute. |
| <code class="inline-code">*</code> or <code class="inline-code">_allChildren</code> returns all |
| direct children elements of all elements in the node list, while |
| <code class="inline-code">@*</code> or <code class="inline-code">_allAttributes</code> returns |
| all attributes of the elements in the node list. There are many more |
| such keys; here's a detailed summary of all the hash keys:</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Key name</th> |
| |
| |
| <th>Evaluates to</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">*</code> or <code class="inline-code">_children</code></td> |
| |
| |
| <td>all direct element children of current nodes |
| (non-recursive). Applicable to element and document |
| nodes.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">@*</code> or |
| <code class="inline-code">_attributes</code></td> |
| |
| |
| <td>all attributes of current nodes. Applicable to elements |
| only.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">@<em class="code-color">attributeName</em></code></td> |
| |
| |
| <td>named attributes of current nodes. Applicable to elements, |
| doctypes and processing instructions. On doctypes it supports |
| attributes <code class="inline-code">publicId</code>, |
| <code class="inline-code">systemId</code> and |
| <code class="inline-code">elementName</code>. On processing instructions, it |
| supports attributes <code class="inline-code">target</code> and |
| <code class="inline-code">data</code>, as well as any other attribute name |
| specified in data as <code class="inline-code">name="value"</code> pair. The |
| attribute nodes for doctype and processing instruction are |
| synthetic, and as such have no parent. Note, however that |
| <code class="inline-code">@*</code> does NOT operate on doctypes or |
| processing instructions.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_ancestor</code></td> |
| |
| |
| <td>all ancestors up to root element (recursive) of current |
| nodes. Applicable to same node types as |
| <code class="inline-code">_parent</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_ancestorOrSelf</code></td> |
| |
| |
| <td>all ancestors of current nodes plus current nodes. |
| Applicable to same node types as |
| <code class="inline-code">_parent</code>.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_cname</code></td> |
| |
| |
| <td>the canonical names of current nodes (namespace URI + |
| local name), one string per node (non-recursive). Applicable |
| to elements and attributes</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_content</code></td> |
| |
| |
| <td>the complete content of current nodes, including children |
| elements, text, entity references, and processing instructions |
| (non-recursive). Applicable to elements and documents.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_descendant</code></td> |
| |
| |
| <td>all recursive descendant element children of current |
| nodes. Applicable to document and element nodes.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_descendantOrSelf</code></td> |
| |
| |
| <td>all recursive descendant element children of current nodes |
| plus current nodes. Applicable to document and element |
| nodes.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_document</code></td> |
| |
| |
| <td>all documents the current nodes belong to. Applicable to |
| all nodes except text.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_doctype</code></td> |
| |
| |
| <td>doctypes of the current nodes. Applicable to document |
| nodes only.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_filterType</code></td> |
| |
| |
| <td>is a filter-by-type template method model. When called, it |
| will yield a node list that contains only those current nodes |
| whose type matches one of types passed as argument. You should |
| pass arbitrary number of strings to this method containing the |
| names of types to keep. Valid type names are: "attribute", |
| "cdata", "comment", "document", "documentType", "element", |
| "entity", "entityReference", "processingInstruction", |
| "text".</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_name</code></td> |
| |
| |
| <td>the names of current nodes, one string per node |
| (non-recursive). Applicable to elements and attributes |
| (returns their local names), entities, processing instructions |
| (returns its target), doctypes (returns its public ID)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_nsprefix</code></td> |
| |
| |
| <td>the namespace prefixes of current nodes, one string per |
| node (non-recursive). Applicable to elements and |
| attributes</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_nsuri</code></td> |
| |
| |
| <td>the namespace URIs of current nodes, one string per node |
| (non-recursive). Applicable to elements and attributes</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_parent</code></td> |
| |
| |
| <td>parent elements of current nodes. Applicable to element, |
| attribute, comment, entity, processing instruction.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_qname</code></td> |
| |
| |
| <td>the qualified names of current nodes in |
| <code class="inline-code">[namespacePrefix:]localName</code> form, one |
| string per node (non-recursive). Applicable to elements and |
| attributes</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_registerNamespace(prefix, uri)</code></td> |
| |
| |
| <td>register a XML namespace with the specified prefix and URI |
| for the current node list and all node lists that are derived |
| from the current node list. After registering, you can use the |
| <code class="inline-code">nodelist["prefix:localname"]</code> or |
| <code class="inline-code">nodelist["@prefix:localname"]</code> syntaxes to |
| reach elements and attributes whose names are |
| namespace-scoped. Note that the namespace prefix need not |
| match the actual prefix used by the XML document itself since |
| namespaces are compared solely by their URI.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_text</code></td> |
| |
| |
| <td>the text of current nodes, one string per node |
| (non-recursive). Applicable to elements, attributes, comments, |
| processing instructions (returns its data) and CDATA sections. |
| The reserved XML characters ('<' and '&') are not |
| escaped.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_type</code></td> |
| |
| |
| <td>Returns a node list containing one string per node |
| describing the type of the node. Possible node type names are: |
| Valid type names are: "attribute", "cdata", "comment", |
| "document", "documentType", "element", "entity", |
| "entityReference", "processingInstruction", "text". If the |
| type of the node is unknown, returns "unknown".</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">_unique</code></td> |
| |
| |
| <td>a copy of the current nodes that keeps only the first |
| occurrence of every node, eliminating duplicates. Duplicates |
| can occur in the node list by applying uptree-traversals |
| <code class="inline-code">_parent</code>, <code class="inline-code">_ancestor</code>, |
| <code class="inline-code">_ancestorOrSelf</code>, and |
| <code class="inline-code">_document</code>. I.e. |
| <code class="inline-code">foo._children._parent</code> will return a node |
| list that has duplicates of nodes in foo - each node will have |
| the number of occurrences equal to the number of its children. |
| In these cases, use |
| <code class="inline-code">foo._children._parent._unique</code> to eliminate |
| duplicates. Applicable to all node types.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td>any other key</td> |
| |
| |
| <td>element children of current nodes with name matching the |
| key. This allows for convenience child traversal in |
| <code class="inline-code">book.chapter.title</code> style syntax. Note that |
| <code class="inline-code">nodeset.childname</code> is technically equivalent |
| to <code class="inline-code">nodeset("childname")</code>, but is both |
| shorter to write and evaluates faster. Applicable to document |
| and element nodes.</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_61">TemplateMethodModel</h5> |
| |
| |
| <p>When used as a method model, it returns a node list that is |
| the result of evaluating an XPath expression on the current contents |
| of the node list. For this feature to work, you must have the |
| <code class="inline-code">Jaxen</code> library in your classpath. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign firstChapter=xmldoc("//chapter[first()]")></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_62">Namespace handling</h5> |
| |
| |
| <p>For purposes of traversal of children elements that have |
| namespace-scoped names, you can register namespace prefixes with the |
| node list. You can do it either in Java, calling the</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">public void registerNamespace(String prefix, String uri);</pre></div> |
| |
| <p>method, or inside a template using the</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${<em>nodelist</em>._registerNamespace(<em>prefix</em>, <em>uri</em>)}</pre></div> |
| |
| <p>syntax. From there on, you can refer to children elements in |
| the namespace denoted by the particular URI through the |
| syntax</p> |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><em class="code-color">nodelist</em>["<em class="code-color">prefix</em>:<em class="code-color">localName</em>"]</code></pre> |
| |
| |
| <p>and</p> |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><em class="code-color">nodelist</em>["@<em class="code-color">prefix</em>:<em class="code-color">localName</em>"]</code></pre> |
| |
| |
| <p>as well as use these namespace prefixes in XPath expressions. |
| Namespaces registered with a node list are propagated to all node |
| lists that are derived from the original node list. Note also that |
| namespaces are matched by their URI only, so you can safely use a |
| prefix for a namespace inside your template that differs from the |
| prefix in the actual XML document - a prefix is just a local alias |
| for the URI both in the template and in the XML document.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_ant">Using FreeMarker with Ant</h4> |
| |
| |
| |
| |
| <p>There are two ``FreeMarker Ant tasks'' that we know |
| about:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">FreemarkerXmlTask</code>: It comes with the |
| FreeMarker distribution, packed into the |
| <code class="inline-code">freemarker.jar</code>. This is a lightweight, |
| easy-to-use Ant task for transforming XML documents with |
| FreeMarker templates. Its approach is that the source files (input |
| files) are XML files, which are rendered to corresponding output |
| files, by a single template. That is, for each XML file, the |
| template will be executed (with the XML document in the |
| data-model), and the template output will be written into a file |
| of similar name than the name of the XML file. Thus, the template |
| file plays a similar role as an XSLT style sheet, but it is FTL, |
| not XSLT.</p> |
| </li> |
| |
| <li> |
| <p> FMPP: It's a more heavyweight, less XML centric, |
| third party Ant task (and standalone command-line tool). Its |
| primary approach is that the source files (input files) are |
| template files that generate the corresponding output files |
| themselves, but it also supports the approach of |
| <code class="inline-code">FreemarkerXmlTask</code> for the source files that are |
| XML-s. Also, it has extra features over the |
| <code class="inline-code">FreemarkerXmlTask</code>. What's its drawback then? As |
| it is more complex and more generalized, it's harder to learn and |
| use it.</p> |
| </li> |
| </ul> |
| |
| <p>This section introduces the |
| <code class="inline-code">FreemarkerXmlTask</code>. For more information about FMPP |
| visit its homepage: <a href="http://fmpp.sourceforge.net/">http://fmpp.sourceforge.net/</a>.</p> |
| |
| <p>In order to use the <code class="inline-code">FreemarkerXmlTask</code>, you |
| must first define the |
| <code class="inline-code">freemarker.ext.ant.FreemarkerXmlTask</code> inside your |
| Ant buildfile, then call the task. Suppose you want to transform |
| several XML documents to HTML using the hypothetical "xml2html.ftl" |
| template, with XML documents being located in the directory "xml" and |
| HTML documents generated into directory "html". You would write |
| something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><taskdef name="freemarker" classname="freemarker.ext.ant.FreemarkerXmlTask"> |
| <classpath> |
| <pathelement location="freemarker.jar" /> |
| </classpath> |
| </taskdef> |
| <mkdir dir="html" /> |
| <freemarker basedir="xml" destdir="html" includes="**/*.xml" template="xml2html.ftl" /></pre></div> |
| |
| <p>The task would invoke the template for every XML document. Every |
| document would be parsed into a DOM tree, then wrapped as a FreeMarker |
| node variable. When template processing begins, the special variable, |
| <code class="inline-code">.node</code>, is set to the root node of the XML |
| document.</p> |
| |
| <p>Note that if you are using the legacy (FreeMarker 2.2.x and |
| earlier) XML adapter implementation, that still works, and the root of |
| the XML tree is placed in the data-model as the variable |
| <code class="inline-code">document</code>. That contains an instance of the legacy |
| <code class="inline-code">freemarker.ext.xml.NodeListModel</code> class.</p> |
| |
| <p>Note that all properties defined by the build file would be made |
| available as a hash model named "properties". Several other models are |
| made available; for detailed description of what variables are made |
| available to templates as well as what other attributes can the task |
| accept, see the JavaDoc for |
| <code class="inline-code">freemarker.ext.ant.FreemarkerXmlTask</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="pgui_misc_jythonwrapper">Jython wrapper</h4> |
| |
| |
| |
| |
| |
| |
| <p>The <code class="inline-code">freemarker.ext.jython</code> package consists of |
| models that enable any Jython object to be used as a |
| <code class="inline-code">TemplateModel</code>. In the very basic case, you only |
| need to call the</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">public TemplateModel wrap(Object obj);</pre></div> |
| |
| <p>method of the |
| <code class="inline-code">freemarker.ext.jython.JythonWrapper</code> class. This |
| method will wrap the passed object into an appropriate |
| <code class="inline-code">TemplateModel</code>. Below is a summary of the properties |
| of returned model wrappers. Let's assume that the model that resulted |
| from the <code class="inline-code">JythonWrapper</code> call on object |
| <code class="inline-code">obj</code> is named <code class="inline-code">model</code> in the |
| template model root for the sake of the following discussion.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_63">TemplateHashModel functionality</h5> |
| |
| |
| <p><code class="inline-code">PyDictionary</code> and |
| <code class="inline-code">PyStringMap</code> will be wrapped into a hash model. |
| Key lookups are mapped to the <code class="inline-code">__finditem__</code> |
| method; if an item is not found, a model for <code class="inline-code">None</code> |
| is returned.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_64">TemplateScalarModel functionality</h5> |
| |
| |
| <p>Every python object will implement |
| <code class="inline-code">TemplateScalarModel</code> whose |
| <code class="inline-code">getAsString()</code> method simply delegates to |
| <code class="inline-code">toString()</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_65">TemplateBooleanModel functionality</h5> |
| |
| |
| <p>Every python object will implement |
| <code class="inline-code">TemplateBooleanModel</code> whose |
| <code class="inline-code">getAsBoolean()</code> method simply delegates to |
| <code class="inline-code">__nonzero__()</code> in accordance with Python semantics |
| of true/false.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_66">TemplateNumberModel functionality</h5> |
| |
| |
| <p>Model wrappers for <code class="inline-code">PyInteger</code>, |
| <code class="inline-code">PyLong</code>, and <code class="inline-code">PyFloat</code> objects |
| implement <code class="inline-code">TemplateNumberModel</code> whose |
| <code class="inline-code">getAsNumber()</code> method returns |
| <code class="inline-code">__tojava__(java.lang.Number.class)</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_67">TemplateSequenceModel functionality</h5> |
| |
| |
| <p>Model wrappers for all classes that extend |
| <code class="inline-code">PySequence</code> will implement |
| <code class="inline-code">TemplateSequenceModel</code> and thus their elements |
| will be accessible by index using the <code class="inline-code">model[i]</code> |
| syntax, which will delegate to <code class="inline-code">__finditem__(i)</code>. |
| You can also query the length of the array or the size of the list |
| using the <code class="inline-code">model?size</code> built-in, which will |
| delegate to <code class="inline-code">__len__()</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="xgui">XML Processing Guide</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="xgui_preface">Preface</h3> |
| |
| |
| <p>Although FreeMarker was originally designed as a web page template |
| engine, as of version 2.3 it also targets another application domain: |
| transforming XML into arbitrary textual output (e.g. HTML files). Thus, |
| in many cases, FreeMarker is an XSLT alternative.</p> |
| |
| <p>Technically, there is nothing special in transforming XML |
| documents. It's just like when you do anything else with FreeMarker: you |
| drop the XML document into the data-model (and possibly other |
| variables), and then you merge the data-model with the FTL template(s) |
| that generate the output text. The extra features introduced for better |
| XML processing are the node FTL variable type (symbolizes a node in |
| generic tree structures, usable not only for XML) and the built-ins and |
| directives dealing with them, and the XML wrapper you get out-of-the-box |
| that exposes XML documents as FTL variables for the templates.</p> |
| |
| <p>What's the difference between using FreeMarker or XSLT? The FTL |
| language has the usual imperative/procedural logic. On the other hand, |
| XSLT is a language with declarative style, designed by "too clever" |
| people, so it's not easy to adopt its logic, nor to use it in many |
| cases. Also its syntax is terribly verbose. However, XSLT's |
| "apply-templates" method can be very handy when you process XML |
| documents, thus FreeMarker supports something similar called the |
| ``visitor pattern''. So in many applications, it is much easier to write |
| FTL stylesheets than XSLT style-sheets. Another fundamental difference |
| is that FTL "transforms" the node tree to text, while XSLT transforms |
| the tree to another tree. So you cannot always use FreeMarker where you |
| can use XSLT.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="xgui_expose">Exposing XML documents</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_expose_dom">The DOM tree</h4> |
| |
| |
| <p>We will use this XML document for the examples:</p> |
| |
| <a name="misc.example.bookXml"></a> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><book> |
| <title>Test Book</title> |
| <chapter> |
| <title>Ch1</title> |
| <para>p1.1</para> |
| <para>p1.2</para> |
| <para>p1.3</para> |
| </chapter> |
| <chapter> |
| <title>Ch2</title> |
| <para>p2.1</para> |
| <para>p2.2</para> |
| </chapter> |
| </book></pre></div> |
| |
| <p>W3C DOM models an XML document as a tree of nodes. The node tree |
| of the above XML can be visualized as:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">document |
| | |
| +- element book |
| | |
| +- text "\n " |
| | |
| +- element title |
| | | |
| | +- text "Test Book" |
| | |
| +- text "\n " |
| | |
| +- element chapter |
| | | |
| | +- text "\n " |
| | | |
| | +- element title |
| | | | |
| | | +- text "Ch1" |
| | | |
| | +- text "\n " |
| | | |
| | +- element para |
| | | | |
| | | +- text "p1.1" |
| | | |
| | +- text "\n " |
| | | |
| | +- element para |
| | | | |
| | | +- text "p1.2" |
| | | |
| | +- text "\n " |
| | | |
| | +- element para |
| | | |
| | +- text "p1.3" |
| | |
| +- element |
| | |
| +- text "\n " |
| | |
| +- element title |
| | | |
| | +- text "Ch2" |
| | |
| +- text "\n " |
| | |
| +- element para |
| | | |
| | +- text "p2.1" |
| | |
| +- text "\n " |
| | |
| +- element para |
| | |
| +- text "p2.2"</pre></div> |
| |
| <p>Note that the disturbing <code class="inline-code">"\n "</code>-s are the |
| line-breaks (indicated here with <code class="inline-code">\n</code>, an escape |
| sequence used in FTL string literals) and the indentation spaces |
| between the tags.</p> |
| |
| <p>Notes on the DOM related terminology:</p> |
| |
| <ul> |
| <li> |
| <p>The topmost node of a tree is called the <strong>root</strong>. In the case of XML documents, it is |
| always the ``document'' node, and not the top-most element |
| (<code class="inline-code">book</code> in this example).</p> |
| </li> |
| |
| <li> |
| <p>We say that node B is the <strong>child</strong> of node A, if B is the |
| <em>immediate</em> descendant of A. For example, the |
| two <code class="inline-code">chapter</code> element nodes are the children of |
| the <code class="inline-code">book</code> element node, but the |
| <code class="inline-code">para</code> element nodes are not.</p> |
| </li> |
| |
| <li> |
| <p>We say that node A is the <strong>parent</strong> of node B, if A is the |
| <em>immediate</em> ascendant of node B, that is, if B |
| is the children of A. For example, the <code class="inline-code">book</code> |
| element node is the parent of the two <code class="inline-code">chapter</code> |
| element nodes, but it is not the parent of the |
| <code class="inline-code">para</code> element nodes.</p> |
| </li> |
| |
| <li> |
| <p>There are several kind of components that can occur in XML |
| documents, such as elements, text, comments, processing |
| instructions, etc. All such components are nodes in the DOM tree, |
| so there are element nodes, text nodes, comment nodes, etc. In |
| principle, the attributes of elements are also nodes in the tree |
| -- they are the children of the element --, but still, usually we |
| (and other XML related technologies) exclude them of element |
| children. So basically they don't count as children nodes.</p> |
| </li> |
| </ul> |
| |
| <p>The programmer drops the document node of the DOM tree into the |
| FreeMarker data-model, and then the template author can walk the DOM |
| tree using that variable as the starting-point.</p> |
| |
| <p>The DOM nodes in FTL correspond to <strong>node |
| variables</strong>. This is a variable type, similarly to type |
| string, number, hash, etc. Node variable type makes it possible for |
| FreeMarker to get the parent node and the child nodes of a node. This |
| is technically required to allow the template author to navigate |
| between the nodes, say, to use the <a href="#ref_builtins_node">node built-ins</a> or the <a href="#ref.directive.visit"><code>visit</code></a> and |
| <a href="#ref.directive.recurse"><code>recurse</code></a> |
| directives; we will show the usage of these in the further |
| chapters.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_expose_put">Putting the XML into the data-model</h4> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This section is for programmers.</p> |
| </div> |
| |
| |
| <p>It's easy to create a simple program to try the examples. Just |
| replace the ``Create a data-model'' part of <a href="#pgui_quickstart_all">the example of Programmer's Guide |
| Quickstart</a> with this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">/* Create a data-model */ |
| Map root = new HashMap(); |
| root.put( |
| "doc", |
| freemarker.ext.dom.NodeModel.parse(new File("<em>the/path/of/the.xml</em>")));</pre></div> |
| |
| <p>and then you have a program that outputs the result of the XML |
| transformation to the standard output (usually the terminal |
| screen).</p> |
| |
| <p>Notes:</p> |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">parse</code> method removes comment and |
| processing instruction nodes by default. See the API for more |
| details.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">NodeModel</code> also allows you to wrap |
| <code class="inline-code">org.w3c.dom.Node</code>-s directly. You may want to |
| clean up the DOM tree first with the static utility methods, such |
| as <code class="inline-code">NodeModel.simplify</code> or your own custom |
| cleanup routines.</p> |
| </li> |
| </ul> |
| |
| <p>Note that there are tools available that you can use to generate |
| files from XML documents, so you don't have to write your own for this |
| common task. <a href="#pgui_misc_ant">See here...</a></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="xgui_imperative">Imperative XML processing</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_imperative_learn">Learning by example</h4> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This section uses the DOM tree and the variable made in the |
| <a href="#xgui_expose">previous chapter</a>.</p> |
| </div> |
| |
| |
| <p>Assume that the programmer has put the XML document into the |
| data-model as variable <code class="inline-code">doc</code>. This variable |
| corresponds to the root of the <a href="#xgui_expose_dom">DOM |
| tree</a>, the ``document''. The actual variable structure behind |
| <code class="inline-code">doc</code> is wily enough, and only roughly resembles the |
| DOM tree. So instead of getting lost in the details, let's see how to |
| use it by example.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_68">Accessing elements by name</h5> |
| |
| |
| <p>This FTL prints the title of the book:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book.title}</h1></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><h1>Test Book</h1></pre></div> |
| |
| <p>As you see, both <code class="inline-code">doc</code> and |
| <code class="inline-code">book</code> can be used as hashes; you get their child |
| nodes as subvariables. Basically, you descriptione the path by which |
| you reach the target (element <code class="inline-code">title</code>) in the DOM |
| tree. You may notice that there was some swindle above: with |
| <code class="inline-code">${doc.book.title}</code>, it seems that we instruct |
| FreeMarker to print the <code class="inline-code">title</code> element itself, but |
| we should print its child text node (check the <a href="#xgui_expose_dom">DOM tree</a>). It still works, because |
| elements are not only hash variables, but string variables as well. |
| The scalar value of an element node is the string resulting from the |
| concatenation of all its text child nodes. However, trying to use an |
| element as scalar will cause error if the element has child |
| elements. For example <code class="inline-code">${doc.book}</code> would stop with |
| error.</p> |
| |
| <p>This FTL prints the titles of the two chapters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><h2>${doc.book.chapter[0].title}</h2> |
| <h2>${doc.book.chapter[1].title}</h2></pre></div> |
| |
| <p>Here, as <code class="inline-code">book</code> has 2 |
| <code class="inline-code">chapter</code> element children, |
| <code class="inline-code">doc.book.chapter</code> is a sequence that stores the |
| two element nodes. Thus, we can generalize the above FTL, so it |
| works with any number of chapters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter as ch> |
| <h2>${ch.title}</h2> |
| </#list></pre></div> |
| |
| <p>But what's if there is only one chapter? Actually, when you |
| access an element as hash subvariable, it is |
| <em>always</em> a sequence as well (not only hash and |
| string), but if the sequence contains exactly 1 item, then the |
| variable also acts as that item itself. So, returning to the first |
| example, this would print the book title as well:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book[0].title[0]}</h1></pre></div> |
| |
| <p>But you know that there is exactly 1 <code class="inline-code">book</code> |
| element, and that a book has exactly 1 title, so you can omit the |
| <code class="inline-code">[0]</code>-s. |
| <code class="inline-code">${doc.book.chapter.title}</code> would work too, if the |
| book happen to have only 1 <code class="inline-code">chapter</code>-s (otherwise |
| it is ambiguous: how is it to know if the <code class="inline-code">title</code> |
| of which <code class="inline-code">chapter</code> you want? So it stops with an |
| error.). But since a book can have multiple chapters, you don't use |
| this form. If the element <code class="inline-code">book</code> has no |
| <code class="inline-code">chapter</code> child, then |
| <code class="inline-code">doc.book.chapter</code> will be a 0 length sequence, so |
| the FTL with <code class="inline-code"><#list ...></code> will still |
| work.</p> |
| |
| <p>It is important to realize the consequence that, for example, |
| if <code class="inline-code">book</code> has no <code class="inline-code">chapter</code>-s then |
| <code class="inline-code">book.chapter</code> is an empty sequence, so |
| <code class="inline-code">doc.book.chapter??</code> will <em>not</em> |
| be <code class="inline-code">false</code>, it will be always |
| <code class="inline-code">true</code>! Similarly, |
| <code class="inline-code">doc.book.somethingTotallyNonsense??</code> will not be |
| <code class="inline-code">false</code> either. To check if there was no children |
| found, use <code class="inline-code">doc.book.chapter[0]??</code> (or |
| <code class="inline-code">doc.book.chapter?size == 0</code>). Of course you can |
| use similarly all the <a href="#dgui_template_exp_missing">missing value handler |
| operators</a> (e.g. |
| <code class="inline-code">doc.book.author[0]!"Anonymous"</code>), just don't |
| forget that <code class="inline-code">[0]</code>.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The rule with sequences of size 1 is a convenience feature |
| of the XML wrapper (implemented via multi-type FTL variables). It |
| will not work with other sequences in general.</p> |
| </div> |
| |
| |
| <p>Now we finish the example by printing all the |
| <code class="inline-code">para</code>-s of each chapter:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book.title}</h1> |
| <#list doc.book.chapter as ch> |
| <h2>${ch.title}</h2> |
| <#list ch.para as p> |
| <p>${p} |
| </#list> |
| </#list></pre></div> |
| |
| <p>this will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><h1>Test</h1> |
| <h2>Ch1</h2> |
| <p>p1.1 |
| <p>p1.2 |
| <p>p1.3 |
| <h2>Ch2</h2> |
| <p>p2.1 |
| <p>p2.2</pre></div> |
| |
| <p>The above FTL could be written more nicely as:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign book = doc.book> |
| <h1>${book.title}</h1> |
| <#list book.chapter as ch> |
| <h2>${ch.title}</h2> |
| <#list ch.para as p> |
| <p>${p} |
| </#list> |
| </#list></pre></div> |
| |
| <p>Finally, a ``generalized`` usage of the child selector |
| mechanism: this template lists all <code class="inline-code">para</code>-s of the |
| example XML document:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter.para as p> |
| <p>${p} |
| </#list></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>p1.1 |
| <p>p1.2 |
| <p>p1.3 |
| <p>p2.1 |
| <p>p2.2 |
| </pre></div> |
| |
| <p>This example shows that hash subvariables select the children |
| of a sequence of notes (just in the earlier examples that sequence |
| happened to be of size 1). In this concrete case, subvariable |
| <code class="inline-code">chapter</code> returns a sequence of size 2 (since there |
| are two <code class="inline-code">chapter</code>-s), and then subvariable |
| <code class="inline-code">para</code> selects the <code class="inline-code">para</code> child |
| nodes of all nodes in that sequence.</p> |
| |
| <p>A negative consequence of this mechanism is that things like |
| <code class="inline-code">doc.somethingNonsense.otherNonsesne.totalNonsense</code> |
| will just evaluate to an empty sequence, and you don't get any error |
| messages.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_69">Accessing attributes</h5> |
| |
| |
| <p>This XML is the same as the original, except that it uses |
| attributes for the titles, instead of elements:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><!-- THIS XML IS USED FOR THE "Accessing attributes" CHAPTER ONLY! --> |
| <!-- Outside this chapter examples use the XML from earlier. --> |
| |
| <book title="Test"> |
| <chapter title="Ch1"> |
| <para>p1.1</para> |
| <para>p1.2</para> |
| <para>p1.3</para> |
| </chapter> |
| <chapter title="Ch2"> |
| <para>p2.1</para> |
| <para>p2.2</para> |
| </chapter> |
| </book></pre></div> |
| |
| <p>The attributes of an element can be accessed in the same way |
| as the child elements of the element, except that you put an at-sign |
| (@) before the name of the attribute:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign book = doc.book> |
| <h1>${book.@title}</h1> |
| <#list book.chapter as ch> |
| <h2>${ch.@title}</h2> |
| <#list ch.para as p> |
| <p>${p} |
| </#list> |
| </#list></pre></div> |
| |
| <p>This will print exactly the same as the previous |
| example.</p> |
| |
| <p>Getting attributes follows the same logic as getting child |
| elements, so the result of <code class="inline-code">ch.@title</code> above is a |
| sequence of size 1. If there were no <code class="inline-code">title</code> |
| attribute, then the result would be a sequence of size 0. So be |
| ware, using existence built-ins is tricky here too: if you are |
| curious if <code class="inline-code">foo</code> has attribute |
| <code class="inline-code">bar</code> then you have to write |
| <code class="inline-code">foo.@bar[0]??</code>. (<code class="inline-code">foo.@bar??</code> is |
| wrong, because it always returns <code class="inline-code">true</code>.) |
| Similarly, if you want a default value for the |
| <code class="inline-code">bar</code> attribute, then you have to write |
| <code class="inline-code">foo.@bar[0]!"theDefaultValue"</code>.</p> |
| |
| <p>As with child elements, you can select the attributes of |
| multiple nodes. For example, this template prints the titles of all |
| chapters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter.@title as t> |
| ${t} |
| </#list></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_70">Exploring the tree</h5> |
| |
| |
| <p>This FTL will enumerate all child nodes of the book |
| element:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book?children as c> |
| - ${c?node_type} <#if c?node_type = 'element'>${c?node_name}</#if> |
| </#list></pre></div> |
| |
| <p>this will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- text |
| - element title |
| - text |
| - element chapter |
| - text |
| - element chapter |
| - text</pre></div> |
| |
| <p>The meaning of <code class="inline-code">?node_type</code> is probably clear |
| without explanation. There are several node types that can occur in |
| a DOM tree, such as <code class="inline-code">"element"</code>, |
| <code class="inline-code">"text"</code>, <code class="inline-code">"comment"</code>, |
| <code class="inline-code">"pi"</code>, ...etc.</p> |
| |
| <p>The <code class="inline-code">?node_name</code> returns the name of element |
| for element nodes. For other node types, it also returns something, |
| but that's mainly useful for declarative XML processing, which will |
| be discussed in a <a href="#xgui_declarative">later |
| chapter</a>.</p> |
| |
| <p>If the book element had attributes, they would |
| <em>not</em> appear in the above list, for practical |
| reasons. But you can get a list that contains all attributes of the |
| element, with subvariable <code class="inline-code">@@</code> of the element |
| variable. If you modify the first line of the XML to this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><book foo="Foo" bar="Bar" baaz="Baaz"></pre></div> |
| |
| <p>and run this FTL:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.@@ as attr> |
| - ${attr?node_name} = ${attr} |
| </#list></pre></div> |
| |
| <p>then you get this output (or something similar):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- baaz = Baaz |
| - bar = Bar |
| - foo = Foo</pre></div> |
| |
| <p>Returning to the listing of children, there is a convenience |
| subvariable to list only the element children of an element:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.* as c> |
| - ${c?node_name} |
| </#list></pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- title |
| - chapter |
| - chapter</pre></div> |
| |
| <p>You get the parent of an element with the |
| <code class="inline-code">parent</code> built-in:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign e = doc.book.chapter[0].para[0]> |
| <#-- Now e is the first para of the first chapter --> |
| ${e?node_name} |
| ${e?parent?node_name} |
| ${e?parent?parent?node_name} |
| ${e?parent?parent?parent?node_name}</pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">para |
| chapter |
| book |
| @document</pre></div> |
| |
| <p>In the last line you have reached the root of the DOM tree, |
| the document node. It's not an element, and this is why it has that |
| strange name; don't deal with it now. Obviously, the document node |
| has no parent.</p> |
| |
| <p>You can quickly go back to the document node using the |
| <code class="inline-code">root</code> built-in:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign e = doc.book.chapter[0].para[0]> |
| ${e?root?node_name} |
| ${e?root.book.title}</pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">@document |
| Test Book</pre></div> |
| |
| <p>For the complete list of built-ins you can use to navigate in |
| the DOM tree, read the <a href="#ref_builtins_node">reference |
| of node built-ins</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_71">Using XPath expressions</h5> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>XPath expressions work only if <a href="http://jaxen.org/">Jaxen</a> (recommended, but use |
| at least Jaxen 1.1-beta-8, not older) or <a href="http://xml.apache.org/xalan/">Apache Xalan</a> |
| classes are available. (Apache Xalan classes are included in Sun |
| J2SE 1.4, 1.5 and 1.6 (and maybe later too); no separate Xalan jar |
| is needed.)</p> |
| </div> |
| |
| |
| <p>If a hash key used with a node variable can't be interpreted |
| otherwise (see the <a href="#xgui_imperative_formal">next |
| section</a> for the precise definition), then it will by |
| interpreted as an XPath expression. For more information on XPath, |
| please visit <a href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a>.</p> |
| |
| <p>For example, here we list the <code class="inline-code">para</code> elements |
| of the chapter with title ``Ch1'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list doc["book/chapter[title='Ch1']/para"] as p> |
| <p>${p} |
| </#list></pre></div> |
| |
| <p>It will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>p1.1 |
| <p>p1.2 |
| <p>p1.3</pre></div> |
| |
| <p>The rule with sequences of length 1 (explained in earlier |
| sections) stands for XPath results as well. That is, if the |
| resulting sequence contains exactly 1 node, it also acts as the node |
| itself. For example, print the first paragraph of chapter |
| ``Ch1'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${doc["book/chapter[title='Ch1']/para[1]"]}</pre></div> |
| |
| <p>which prints the same as:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${doc["book/chapter[title='Ch1']/para[1]"][0]}</pre></div> |
| |
| <p>The context node of the XPath expression is the node (or |
| sequence of nodes) whose hash subvariable is used to issue the XPath |
| expression. Thus, this prints the same as the previous |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${doc.book["chapter[title='Ch1']/para[1]"]}</pre></div> |
| |
| <p>Note that currently you can use a sequence of 0 or multiple |
| (more than 1) nodes as context only if the programmer has set up |
| FreeMarker to use Jaxen instead of Xalan.</p> |
| |
| <p>Also note that XPath indexes sequence items from 1, while FTL |
| indexes sequence items from 0. Thus, to select the first chapter, |
| the XPath expression is <code class="inline-code">"/book/chapter[1]"</code>, while |
| the FTL expression is <code class="inline-code">book.chapter[0]</code>.</p> |
| |
| <p>If the programmer has set up FreeMarker to use Jaxen instead |
| of Xalan, then FreeMarker variables are visible with XPath variable |
| references:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign <strong>currentTitle</strong> = "Ch1"> |
| <#list doc["book/chapter[title=<strong>$currentTitle</strong>]/para"] as p> |
| <em>...</em></pre></div> |
| |
| <p>Note that <code class="inline-code">$currentTitle</code> is not a FreeMarker |
| interpolation, as there are no <code class="inline-code">{</code> and |
| <code class="inline-code">}</code> there. That's an XPath expression.</p> |
| |
| <p>The result of some XPath expressions is not a node-set, but a |
| string, a number, or a boolean. For those XPath expressions, the |
| result is an FTL string, number, or boolean variable respectively. |
| For example, the following will count the total number of |
| <code class="inline-code">para</code> elements in the XML document, so the result |
| is a number:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${x["count(//para)"]}</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">5</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_72">XML namespaces</h5> |
| |
| |
| |
| |
| <p>Be default, when you write something like |
| <code class="inline-code">doc.book</code>, then it will select the element with |
| name <code class="inline-code">book</code> that does not belongs to any XML |
| namespace (similarly to XPath). If you want to select an element |
| that is inside an XML namespace, you must register a prefix and use |
| that. For example, if element <code class="inline-code">book</code> is in XML |
| namespace <code class="inline-code">http://example.com/ebook</code>, then you have |
| to associate a prefix with it at the top of the template with the |
| <code class="inline-code">ns_prefixes</code> parameter of the <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={"e":"http://example.com/ebook"}></pre></div> |
| |
| <p>And now you can write expressions as |
| <code class="inline-code">doc["e:book"]</code>. (The usage of square bracket |
| syntax was required because the colon would confuse FreeMarker |
| otherwise.)</p> |
| |
| <p>As the value of <code class="inline-code">ns_prefixes</code> is a hash, you |
| can register multiple prefixes:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={ |
| "e":"http://example.com/ebook", |
| "f":"http://example.com/form", |
| "vg":"http://example.com/vectorGraphics"} |
| ></pre></div> |
| |
| <p>The <code class="inline-code">ns_prefixes</code> parameter affects the whole |
| <a href="#dgui_misc_namespace">FTL namespace</a>. This means |
| in practice that the prefixes you have registered in the main page |
| template will be visible in all <code class="inline-code"><#include |
| ...></code>-d templates, but not in <code class="inline-code"><#imported |
| ...></code>-d templates (often referred as FTL libraries). Or |
| from another point of view, an FTL library can register XML |
| namespace prefixes for it's own use, without interfering with the |
| prefix registrations of the main template and other |
| libraries.</p> |
| |
| <p>Note that, if an input document is dominated by a given XML |
| namespace, you can set that as the default namespace for |
| convenience. This means that if you don't use prefix, as in |
| <code class="inline-code">doc.book</code>, then it selects element that belongs to |
| the default namespace. The setting of the default namespace happens |
| with reserved prefix <code class="inline-code">D</code>, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={"D":"http://example.com/ebook"}></pre></div> |
| |
| <p>Now expression <code class="inline-code">doc.book</code> select the |
| <code class="inline-code">book</code> element that belongs to XML namespace |
| <code class="inline-code">http://example.com/ebook</code>. Unfortunately, XPath |
| does not support this idea of a default namespace. Thus, in XPath |
| expressions, element names without prefixes always select the |
| elements that does not belong to any XML namespace. However, to |
| access elements in the default namespace you can directly use prefix |
| <code class="inline-code">D</code>, for example: |
| <code class="inline-code">doc["D:book/D:chapter[title='Ch1']"]</code>.</p> |
| |
| <p>Note that when you use a default namespace, then you can |
| select elements that does not belong to any node namespace with |
| reserved prefix <code class="inline-code">N</code>, for example |
| <code class="inline-code">doc.book["N:foo"]</code>. It doesn't go for XPath |
| expressions, where the above can be witten as |
| <code class="inline-code">doc["D:book/foo"]</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_73">Don't forget escaping!</h5> |
| |
| |
| <p>We have made a big mistake in all examples. We generate output |
| of HTML format, and HTML format reserves characters as |
| <code class="inline-code"><</code>, <code class="inline-code">&</code>, etc. So when we |
| print plain text (as the titles and paragraphs), we have to escape |
| it. Thus, the correct version of the example is:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#escape x as x?html></strong> |
| <#assign book = doc.book> |
| <h1>${book.title}</h1> |
| <#list book.chapter as ch> |
| <h2>${ch.title}</h2> |
| <#list ch.para as p> |
| <p>${p} |
| </#list> |
| </#list> |
| <strong></#escape></strong></pre></div> |
| |
| <p>So if the book title is "Romeo & Julia", the resulting |
| HTML output will be correctly:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><em>...</em> |
| <h1>Romeo &amp; Julia</h1> |
| <em>...</em></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_imperative_formal">Formal description</h4> |
| |
| |
| <p>Every variable that corresponds to a single node in the DOM tree |
| is a multi-type variable of type node and type hash (for programmers: |
| implements both <code class="inline-code">TemplateNodeModel</code> and |
| <code class="inline-code">TemplateHashModel</code>). Thus, you can use the <a href="#ref_builtins_node">node built-ins</a> with them. Hash keys |
| are interpreted as XPath expressions, except the special keys shown in |
| the table below. Some of the node variables also have string type, so |
| you can use them as string variables (for programmers: they implement |
| <code class="inline-code">TemplateScalarModel</code>).</p> |
| |
| <a name="misc.xguiTable"></a> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Node type (<code class="inline-code">?node_type</code>)</th> |
| |
| |
| <th>Node name (<code class="inline-code">?node_name</code>)</th> |
| |
| |
| <th>String value (e.g. <code class="inline-code"><p>${node}</code>)</th> |
| |
| |
| <th>Special hash keys</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">"document"</code></td> |
| |
| |
| <td><code class="inline-code">"@document"</code></td> |
| |
| |
| <td>No string value. (Error when you try to use it as |
| string.)</td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"*"</code>, <code class="inline-code">"**"</code>, |
| <code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"element"</code></td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">name</em>"</code>: the |
| name of the element. This is the local name (i.e. name without |
| namespace prefix).</td> |
| |
| |
| <td>If it has no element children, the text of all text node |
| children concatenated together. Error otherwise, when you try to |
| use it as string.</td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"*"</code>, <code class="inline-code">"**"</code>, |
| <code class="inline-code">"@<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@@"</code>, <code class="inline-code">"@*"</code>, |
| <code class="inline-code">"@@start_tag"</code>, |
| <code class="inline-code">"@@end_tag"</code>, |
| <code class="inline-code">"@@attributes_markup"</code>, |
| <code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code>, <code class="inline-code">"@@qname"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"text"</code></td> |
| |
| |
| <td><code class="inline-code">"@text"</code></td> |
| |
| |
| <td>The text itself.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"pi"</code></td> |
| |
| |
| <td><code class="inline-code">"@pi$<em class="code-color">target</em>"</code></td> |
| |
| |
| <td>The part between the target name and the |
| <code class="inline-code">?></code>.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"comment"</code></td> |
| |
| |
| <td><code class="inline-code">"@comment"</code></td> |
| |
| |
| <td>The text of the comment, without the delimiters |
| <code class="inline-code"><!--</code> and <code class="inline-code">--></code>.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"attribute"</code></td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">name</em>"</code>: the |
| name of the attribute. This is the local name (i.e. name without |
| namespace prefix).</td> |
| |
| |
| <td>The value of the attribute.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code>, <code class="inline-code">"@@qname"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"document_type"</code></td> |
| |
| |
| <td><code class="inline-code">"@document_type$<em class="code-color">name</em>"</code>: |
| <code class="inline-code"><em class="code-color">name</em></code> is the name |
| of the document element.</td> |
| |
| |
| <td>No string value. (Error when you try to use it as |
| string.)</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>Notes:</p> |
| |
| <ul> |
| <li> |
| <p>There is no CDATA type. CDATA nodes are transparently |
| considered as text nodes.</p> |
| </li> |
| |
| <li> |
| <p>Variables do <em>not</em> support |
| <code class="inline-code">?keys</code> and <code class="inline-code">?values</code>.</p> |
| </li> |
| |
| <li> |
| <p>Element and attribute node names are local names, that is, |
| they do not contain the namespace prefix. The URI of the namespace |
| the node belongs to can be queried with the |
| <code class="inline-code">?node_namespace</code> built-in.</p> |
| </li> |
| |
| <li> |
| <p>XPath expression needs Jaxen (recommended, but please use |
| 1.1-beta-8 or later; <a href="http://jaxen.org/">download |
| it here</a>) or Apache Xalan classes available, or an error |
| will stop template execution. Note, however, that as some special |
| hash keys hide the XPath expressions of the same meaning, those |
| XPath expressions will work even if there is no XPath |
| implementation available. <span class="marked-for-programmers">If both |
| Xalan and Jaxen is available, FreeMarker will use Xalan, unless |
| you choose Jaxen by calling |
| <code class="inline-code">freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</code> |
| from Java.</span></p> |
| </li> |
| |
| <li> |
| <p>If Jaxen is used for the XPath support (not Xalan), then |
| FreeMarker variables are visible with XPath variable references |
| (e.g. |
| <code class="inline-code">doc["book/chapter[title=$currentTitle]"]</code>).</p> |
| </li> |
| </ul> |
| |
| <p>Meaning of special hash keys:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>: |
| Returns the sequence of child nodes that are elements of name |
| <code class="inline-code"><em class="code-color">elementName</em></code>. (Note |
| that the term ``child'' means <em>immediate</em> |
| descendant.) The selection is XML name-space aware, unless the XML |
| document was persed with an XML parser that was not in namespace |
| aware mode. In XML name-space aware mode, names without prefix |
| (<em>elementName</em>) selects only elements |
| that doesn't belong to any XML name-space (unless you have |
| registered a default XML namespace), and names with prefix |
| (<em>prefix</em>:<em>elementName</em>) |
| selects only elements that are belonging to the XML namespace |
| denoted by the prefix. The registarion of prefixes and the setting |
| of the default XML namespace is done with the |
| <code class="inline-code">ns_prefixes</code> parameter of the <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"*"</code>: Returns the sequence of all child |
| (direct descedant) <em>element</em> nodes. The |
| sequence will contain the elements in the ``document order'', that |
| is, in the order in which the first character of the XML |
| representation of each node occurs (after expansion of general |
| entities).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"**"</code>: Returns the sequence of all |
| descendant <em>element</em> nodes. The sequence will |
| contain the elements in the document order.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@<em class="code-color">attName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code>: |
| Returns the attribute |
| <code class="inline-code"><em class="code-color">attName</em></code> of the |
| element as a sequence of size 1 that contains the attribute node, |
| or as an empty sequence if the attribute does not exist (so to |
| check if an attribute exists use |
| <code class="inline-code">foo.@<em class="code-color">attName</em>[0]??</code>, |
| <em>not</em> |
| <code class="inline-code">foo.@<em class="code-color">attName</em>??</code>). As |
| with special key |
| <code class="inline-code">"<em class="code-color">elementName</em>"</code>, if |
| the length of the sequence is 1, then it also acts as its first |
| subvariable. If no |
| <code class="inline-code"><em class="code-color">prefix</em></code> is used, then |
| it returns only attribute that does not use XML namespace (even if |
| you have set a default XML namespace). If a |
| <code class="inline-code"><em class="code-color">prefix</em></code> is used, it |
| returns only the attribute that belongs to the XML namespace |
| associated with the |
| <code class="inline-code"><em class="code-color">prefix</em></code>. The |
| registarion of prefixes is done with the |
| <code class="inline-code">ns_prefixes</code> parameter of the <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@"</code> or <code class="inline-code">"@*"</code>: Returns |
| the sequence of attribute nodes belonging to the parent element. |
| This is the same as XPath <code class="inline-code">@*</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@qname"</code>: Returns the full-qualified |
| name of the element (such as <code class="inline-code">e:book</code>, in |
| contrast to the local name returned by |
| <code class="inline-code">?node_name</code> that is <code class="inline-code">book</code>) . |
| The prefix used (as <code class="inline-code">e</code>) is chosen based on the |
| prefix registered in the current namespace with the |
| <code class="inline-code">ns_prefixes</code> parameter of the |
| <code class="inline-code">ftl</code> directive, and not influenced by the prefix |
| used in the source XML document. If you have set a default XML |
| namespace, then for nodes that use that, prefix |
| <code class="inline-code">D</code> will be used. For nodes that does not belong |
| to an XML namespace, no prefix is used (even if you have set a |
| default namespace). If there is no prefix registered for the |
| namespace of the node, the result is a non-existent variable |
| (<code class="inline-code">node.@@qname??</code> is |
| <code class="inline-code">false</code>).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@markup"</code>: This returns the full XML |
| markup of a node, as a string. (Full XML markup means that it also |
| contains the markup of the child nodes, and the markup of the |
| children of the child nodes, and so on.) The markup you get is not |
| necessary the same as the markup in the source XML file, it's just |
| semantically identical. Especially, note that CDATA sections will |
| become to plain text. Also note that depending on how did you |
| wrapped the original XML document with FreeMarker, comment or |
| processing instruction nodes may were removed, and then they will |
| be missing from the output of course. The first outputted start |
| tag will contain |
| <code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes for each XML name-spaces used in the outputted XML |
| fragment, and those prefixes will be used in the outputted element |
| and attribute names. These prefixes will be the same as the |
| prefixes registered with the <code class="inline-code">ns_prefixes</code> |
| parameter of the <code class="inline-code">ftl</code> directive (no prefix will |
| be used for <code class="inline-code">D</code>, as it will be registered as the |
| default name-space with an <code class="inline-code">xmlns</code> attribute), or |
| if no prefix was assigned for a XML name-space with that, then an |
| arbitrary chosen unused prefix is used.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@nested_markup"</code>: This is similar to |
| <code class="inline-code">"@@markup"</code>, but it returns the XML markup of an |
| element without its opening and closing tags. For the document |
| node, it returns the same as <code class="inline-code">"@@markup"</code>. For |
| other node types (text, processing instruction, etc.), it returns |
| an empty string. Unlike with <code class="inline-code">"@@markup"</code>, no |
| <code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes will be placed into the ouput, but regarding the |
| prefixes used in element and attribute names the rules are the |
| same.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@text"</code>: This returns the value of all |
| text nodes that occur within the node (all descendant text nodes, |
| not just direct children), concatenated together into a single |
| string. If the node has no text node children, then the result is |
| an empty string.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@start_tag"</code>: Returns the markup of the |
| <a href="#gloss.startTag">start-tag</a> of the element |
| node. As with <code class="inline-code">@@markup</code>, the output is not |
| necessary the same as in the original XML document, but it is |
| semantically equivalent with that. Regarding the XML name-spaces |
| (<code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes in the output, etc.) the rules are the same as with |
| <code class="inline-code">"@@markup"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@end_tag"</code>: Returns the markup of the |
| <a href="#gloss.endTag">end-tag</a> of the element node. |
| As with <code class="inline-code">@@markup</code>, the output is not necessary |
| the same as in the original XML document, but it is semantically |
| equivalent with that.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">@@attributes_markup</code>: Returns the markup |
| of the <a href="#gloss.attribute">attributes</a> of the |
| element node. As with <code class="inline-code">@@markup</code>, the output is |
| not necessary the same as in the original XML document, but it is |
| semantically equivalent with that.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_74">Node sequences</h5> |
| |
| |
| <p>Many of the special hash keys (indicated in the above list), |
| and XPath expressions that result in node-sets (see the <a href="http://www.w3.org/TR/xpath">XPath recommendation</a>) |
| return a sequence of nodes.</p> |
| |
| <p>These node sequences, if they store exactly 1 subvariable, |
| will also act as the subvariable itself. For example, |
| <code class="inline-code">${book.title[0]}</code> will do the same as |
| <code class="inline-code">${book.title}</code>, if there is only one |
| <code class="inline-code">title</code> element child of element |
| <code class="inline-code">book</code>.</p> |
| |
| <p>Returning an empty node sequence is a normal situation. For |
| example, if in a concrete XML document, element |
| <code class="inline-code">book</code> has no child element |
| <code class="inline-code">chapter</code>, then <code class="inline-code">book.chapter</code> |
| results in an empty node sequence. Beware! This also means, that |
| <code class="inline-code">book.chaptre</code> (note the typo) will also return |
| empty node sequence, and will not stop with error. Also, |
| <code class="inline-code">book.chaptre??</code> (note the typo) will return |
| <code class="inline-code">true</code> because the empty sequence exists, so you |
| have to use <code class="inline-code">book.chaptre[0]??</code> for the |
| check.</p> |
| |
| <p>Node sequences that store not 1 nodes (but 0 or more than 1 |
| nodes) also support some of the hash keys described above. Namely, |
| the following special keys are supported:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@text"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"*"</code>, <code class="inline-code">"**"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@"</code>, <code class="inline-code">"@*"</code></p> |
| </li> |
| </ul> |
| |
| <p>When you apply one of the above special keys on a node |
| sequence that contains more than 1 or 0 nodes, then for each node in |
| the sequence (where the special key does make sense, e.g. text nodes |
| will be skipped for key <code class="inline-code">*</code> or |
| <code class="inline-code">@foo</code>), the special key will be applied as it was |
| explained for single nodes, and the results will be concatenated to |
| form the final result. The results will be concatenated in the order |
| as the corresponding nodes occur in the node sequence. The |
| concatenation means string or sequence concatenation depending on |
| the type of the results. If the special key would result in a string |
| for a single node, then for multiple nodes the result is a single |
| string too (the results for the single nodes concatenated), and if |
| the special key would return a sequence for a single node, then for |
| multiple nodes the result is a single sequence too. If there are 0 |
| nodes in the sequence you apply the special key on, the string |
| result is an empty string or an empty sequence respectively.</p> |
| |
| <p>XPath expressions can be used with node sequences. However, |
| for 0 or more than 1 nodes it will work only if you use Jaxen |
| instead of Xalan, because of the limitations of the Xalan XPath |
| implementation.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="xgui_declarative">Declarative XML Processing</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_declarative_basics">Basics</h4> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This section uses the DOM tree and the variable made in <a href="#xgui_expose">a previous chapter</a>.</p> |
| </div> |
| |
| |
| <p>With the imperative approach of XML processing -- this was shown |
| in the previous chapter -- you write an FTL program that walks the |
| tree to find the different kind of nodes. With the declarative |
| approach, you rather define how to handle the different kind of nodes, |
| and then let FreeMarker walk the tree an call the handlers you have |
| defined. This approach is useful for complex XML schemas, where the |
| same element can occur as the child of many other elements. Examples |
| of such schemas are XHTML and XDocBook.</p> |
| |
| <p>The directive you most often use with the declarative approach |
| is the <a href="#ref.directive.recurse"><code>recurse</code> |
| directive</a>. This directive gets a node variable as parameter, |
| and ``visits'' all its children nodes, one after the other, starting |
| with the first child. ``Visiting'' a node means that it calls a |
| user-defined directive (like a macro) that has the same name as the |
| name of the child node (<code class="inline-code">?node_name</code>). We say on |
| this, that the user-defined directive <em>handles</em> the |
| node. The node that the user-defined directive just handles is |
| available as special variable <code class="inline-code">.node</code>. For example, |
| this FTL:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#recurse doc> |
| |
| <#macro book> |
| I'm the book element handler, and the title is: ${.node.title} |
| </#macro></pre></div> |
| |
| <p>will print (I have removed some disturbing white-space form the |
| output):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">I'm the book element handler, and the title is: Test Book</pre></div> |
| |
| <p>If you call <code class="inline-code">recurse</code> without parameter, then |
| it uses <code class="inline-code">.node</code>, that is, it visits all children |
| nodes of the node being handled currently. So this FTL:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#recurse doc> |
| |
| <#macro book> |
| Book element with title ${.node.title} |
| <#recurse> |
| End book |
| </#macro> |
| |
| <#macro title> |
| Title element |
| </#macro> |
| |
| <#macro chapter> |
| Chapter element with title: ${.node.title} |
| </#macro></pre></div> |
| |
| <p>will print (I have removed disturbing white-space form the |
| output):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Book element with title Test Book |
| Title element |
| Chapter element with title: Ch1 |
| Chapter element with title: Ch2 |
| End book</pre></div> |
| |
| <p>You have seen how to define handlers for element nodes, but not |
| how to define handler for the text nodes. Since the name of the |
| handler is the same as the node-name of nodes it handles, and as the |
| node-name of all text nodes is <code class="inline-code">@text</code> (see <a href="#misc.xguiTable">the table</a>), you define handler for the |
| text nodes like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> |
| <#macro @text>${.node?html}</#macro></pre></div> |
| |
| <p>Note the <code class="inline-code">?html</code>. You have to HTML-escape the |
| text, since you generate output of HTML format.</p> |
| |
| <p>Here it is the template that transforms the XML to complete |
| HTML:</p> |
| |
| <a name="misc.example.declarativeBookProcessor"></a> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#recurse doc> |
| |
| <#macro book> |
| <html> |
| <head> |
| <title><#recurse .node.title></title> |
| </head> |
| <body> |
| <h1><#recurse .node.title></h1> |
| <#recurse> |
| </body> |
| </html> |
| </#macro> |
| |
| <#macro chapter> |
| <h2><#recurse .node.title></h2> |
| <#recurse> |
| </#macro> |
| |
| <#macro para> |
| <p><#recurse> |
| </#macro> |
| |
| <#macro title> |
| <#-- |
| We have handled this element imperatively, |
| so we do nothing here. |
| --> |
| </#macro> |
| |
| <#macro @text>${.node?html}</#macro></pre></div> |
| |
| <p>and the output will be (now I will honestly include the annoying |
| white-space...):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <html> |
| <head> |
| <title>Test Book</title> |
| </head> |
| <body> |
| <h1>Test Book</h1> |
| |
| |
| <h2>Ch1</h2> |
| |
| |
| <p>p1.1 |
| |
| <p>p1.2 |
| |
| <p>p1.3 |
| |
| |
| <h2>Ch2</h2> |
| |
| |
| <p>p2.1 |
| |
| <p>p2.2 |
| |
| |
| </body> |
| </html> |
| |
| </pre></div> |
| |
| <p>Note that you can reduce substantially the amount of superfluous |
| whitespace in the output by using the <a href="#ref_directive_t">trim directives</a>, as |
| <code class="inline-code"><#t></code>. See also: <a href="#dgui_misc_whitespace">Template Author's Guide/Miscellaneous/White-space handling</a></p> |
| |
| <p>You may say that the FTL that did it with imperative approach |
| was much shorter. That's true, but the example XML uses a very simple |
| schema, and as I said, the declarative approach brings its form with |
| XML schemas that are not that firm about what element can occur where. |
| Say, introduce element <code class="inline-code">mark</code>, that should color text |
| to red, does not mater where do you use it; in a |
| <code class="inline-code">title</code>, or in a <code class="inline-code">para</code>. For this, |
| with the declarative approach, you just add a macro:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro mark><font color=red><#recurse></font></#macro></pre></div> |
| |
| <p>And then <code class="inline-code"><mark>...</mark></code> will |
| automatically work everywhere. So for certain XML schemas, declarative |
| XML processing will actually result in shorter, and what is even more |
| important, much clearer FTL-s, than imperative XML processing. It's up |
| to you to decide which approach to use when; don't forget that you can |
| mix the two approaches freely. Say, in an element handler, you can use |
| imperative approach to process the contents of that element.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="xgui_declarative_details">Details</h4> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_75">Default handlers</h5> |
| |
| |
| <p>For some XML node types, there is a default handler, which |
| will handle the node if you haven't defined a handler for the node |
| (i.e. if there is no user-defined directive available with name |
| identical to the node name). Here are these node types, and what the |
| default handler does:</p> |
| |
| <ul> |
| <li> |
| <p>Text node: prints the text as it. Note, that in most |
| applications, this will not be good for you, because you should |
| escape the text before you send it to the output (with |
| <code class="inline-code">?html</code> or <code class="inline-code">?xml</code> or |
| <code class="inline-code">?rtf</code>, ...etc. depends on the output |
| format).</p> |
| </li> |
| |
| <li> |
| <p>Processing instruction node: call handler called |
| <code class="inline-code">@pi</code> if you have created such user-defined |
| directive, otherwise do nothing (ignore the node).</p> |
| </li> |
| |
| <li> |
| <p>Comment node, document type node: Do nothing (ignore the |
| node).</p> |
| </li> |
| |
| <li> |
| <p>Document node: Call <code class="inline-code">recurse</code>, that is, |
| visit all children of the document node.</p> |
| </li> |
| </ul> |
| |
| <p>Element and attribute nodes will be handled according to the |
| usual, XML independent mechanism. That is, |
| <code class="inline-code">@<em class="code-color">node_type</em></code> will be |
| called as handler, and if that's not defined, then an error stops |
| template processing.</p> |
| |
| <p>In the case of element nodes, this means that if you define a |
| macro (or other kind of user-defined directive) called |
| <code class="inline-code">@element</code>, that will catch all element nodes, |
| which has no more specific handler. If you have no |
| <code class="inline-code">@element</code> handler, then you |
| <em>must</em> define a handler for all possible |
| elements.</p> |
| |
| <p>Attribute nodes are not visited by the |
| <code class="inline-code">recurse</code> directive, so you don't need to write |
| handlers for them.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_76">Visiting a single node</h5> |
| |
| |
| <p>With the <a href="#ref.directive.visit"><code>visit</code> |
| directive</a> you can visit a single node, instead of the |
| children of the node: |
| <code class="inline-code"><#visit <em class="code-color">nodeToVisist</em>></code>. |
| This can be useful sometimes.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_77">XML namespaces</h5> |
| |
| |
| |
| |
| <p>We said that the name of the handler user-defined directive |
| (like a macro) for an element is the name of the element. In fact, |
| it is the full-qualified name of the element: |
| <code class="inline-code"><em class="code-color">prefix</em>:<em class="code-color">elementName</em></code>. |
| The rules regarding the usage of |
| <code class="inline-code"><em class="code-color">prefix</em></code>-es is the same |
| as with imperative processing. Thus, the user-defined |
| <code class="inline-code">book</code> directive handles only element |
| <code class="inline-code">book</code> that does not belong to any XML namespace |
| (unless you have specified a default XML namespace). So if the |
| example XML would use XML namespace |
| <code class="inline-code">http://example.com/ebook</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified"><book xmlns="http://example.com/ebook"> |
| <em>...</em></pre></div> |
| |
| <p>Then the FTL should look as this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#ftl ns_prefixes={"e":"http://example.com/ebook"}></strong> |
| |
| <#recurse doc> |
| |
| <#macro "<strong>e:</strong>book"> |
| <html> |
| <head> |
| <title><#recurse .node["<strong>e:</strong>title"]></title> |
| </head> |
| <body> |
| <h1><#recurse .node["<strong>e:</strong>title"]></h1> |
| <#recurse> |
| </body> |
| </html> |
| </#macro> |
| |
| <#macro "<strong>e:</strong>chapter"> |
| <h2><#recurse .node["<strong>e:</strong>title"]></h2> |
| <#recurse> |
| </#macro> |
| |
| <#macro "<strong>e:</strong>para"> |
| <p><#recurse> |
| </#macro> |
| |
| <#macro "<strong>e:</strong>title"> |
| <#-- |
| We have handled this element imperatively, |
| so we do nothing here. |
| --> |
| </#macro> |
| |
| <#macro @text>${.node?html}</#macro></pre></div> |
| |
| <p>Or, you can define a default XML namespace, and then the |
| further part of the template remains the same as in the original XML |
| namespace free example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={"<strong>D</strong>":"http://example.com/ebook"}> |
| |
| <#recurse doc> |
| |
| <#macro book> |
| <em>...</em></pre></div> |
| |
| <p>But in this case don't forge that in XPath expressions (we |
| didn't used any in the example) the default XML namespace must be |
| accessed with an explicit <code class="inline-code">D:</code> since names without |
| prefix always refer to nodes with no XML namespace in XPath. Also |
| note that with the same logic as with imperative XML processing, the |
| name of handlers for elements that has no XML namespace is |
| <code class="inline-code">N:<em class="code-color">elementName</em></code> if (and |
| only if) there is a default XML namespace. However, for nodes that |
| are not of type element (such as text nodes), you never use the |
| <code class="inline-code">N</code> prefix in the handler name, because those nodes |
| are free of the idea of XML namespaces. So for example, the handler |
| for text nodes is always just <code class="inline-code">@text</code>.</p> |
| |
| <p>For more detailed information, please read <a href="#ref_directive_visit">the reference of |
| <code>recurse</code> and <code>visit</code></a> |
| directives.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="ref">Reference</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="ref_builtins">Built-in Reference</h3> |
| |
| |
| |
| |
| <p>Alphabetical index of built-ins:</p> |
| |
| <ul> |
| <li> |
| <a href="#ref_builtin_ancestors">ancestors</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">byte</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_c">c</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_cap_first">cap_first</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_capitalize">capitalize</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_rounding">ceiling</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_children">children</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_chop_linebreak">chop_linebreak</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_chunk">chunk</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_contains">contains</a> |
| </li> |
| |
| <li> |
| date <a href="#ref_builtin_date_datetype">for |
| dates</a>, <a href="#ref_builtin_string_date">for |
| strings</a> |
| </li> |
| |
| <li> |
| datetime <a href="#ref_builtin_date_datetype">for |
| dates</a>, <a href="#ref_builtin_string_date">for |
| strings</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">double</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_ends_with">ends_with</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_eval">eval</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_first">first</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_rounding">floor</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_groups">groups</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">float</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_has_content">has_content</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_html">html</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_index_of">index_of</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">int</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_interpret">interpret</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_isType">is_...</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_j_string">j_string</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_js_string">js_string</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_keys">keys</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_last">last</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_last_index_of">last_index_of</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_left_pad">left_pad</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_length">length</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">long</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_lower_case">lower_case</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_matches">matches</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_namespace">namespace</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_new">new</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_node_namespace">node_namespace</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_node_name">node_name</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_node_type">node_type</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_number">number</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_parent">parent</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_replace">replace</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_reverse">reverse</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_right_pad">right_pad</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_rounding">round</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_root">root</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_rtf">rtf</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_numType">short</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_size">size</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_sort">sort</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_seq_contains">seq_contains</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_seq_index_of">seq_index_of</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_seq_last_index_of">seq_last_index_of</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_sort_by">sort_by</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_split">split</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_starts_with">starts_with</a> |
| </li> |
| |
| <li> |
| string: <a href="#ref_builtin_string_for_string">for |
| strings</a>, <a href="#ref_builtin_string_for_number">for |
| numbers</a>, <a href="#ref_builtin_string_for_boolean">for |
| booleans</a>, <a href="#ref_builtin_string_for_date">for |
| date/times</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_substring">substring</a> |
| </li> |
| |
| <li> |
| time <a href="#ref_builtin_date_datetype">for |
| dates</a>, <a href="#ref_builtin_string_date">for |
| strings</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_trim">trim</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_uncap_first">uncap_first</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_upper_case">upper_case</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_url">url</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_values">values</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_word_list">word_list</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_xhtml">xhtml</a> |
| </li> |
| |
| <li> |
| <a href="#ref_builtin_xml">xml</a> |
| </li> |
| </ul> |
| |
| <p>If you don't find a built-in here that you have seen in a working |
| template, probably you will find it here: <a href="#ref_deprecated">Deprecated FTL constructs</a></p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_string">Built-ins for strings</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_substring">substring</h5> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.7.</p> |
| </div> |
| |
| |
| <p>Synopsis: |
| <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>, |
| <em class="code-color">toExclusive</em>)</code>, also callable as |
| <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>)</code></p> |
| |
| <p>A substring of the string. |
| <code class="inline-code"><em class="code-color">from</em></code> is the index of |
| the first character. It must be a number that is at least 0 and less |
| than or equal with |
| <code class="inline-code"><em class="code-color">toExclusive</em></code>, or else |
| an error will abort the template processing. The |
| <code class="inline-code"><em class="code-color">toExclusive</em></code> is the |
| index of the character position after the last character of the |
| substring, or with other words, it is one greater than the index of |
| the last character. It must be a number that is at least 0 and less |
| than or equal to the length of the string, or else an error will |
| abort the template processing. If the |
| <code class="inline-code"><em class="code-color">toExclusive</em></code> is |
| omitted, then it defaults to the length of the string. If a |
| parameter is a number that is not an integer, only the integer part |
| of the number will be used.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">- ${'abc'?substring(0)} |
| - ${'abc'?substring(1)} |
| - ${'abc'?substring(2)} |
| - ${'abc'?substring(3)} |
| |
| - ${'abc'?substring(0, 0)} |
| - ${'abc'?substring(0, 1)} |
| - ${'abc'?substring(0, 2)} |
| - ${'abc'?substring(0, 3)} |
| |
| - ${'abc'?substring(0, 1)} |
| - ${'abc'?substring(1, 2)} |
| - ${'abc'?substring(2, 3)}</pre></div> |
| |
| <p>The output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- abc |
| - bc |
| - c |
| - |
| |
| - |
| - a |
| - ab |
| - abc |
| |
| - a |
| - b |
| - c</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_cap_first">cap_first</h5> |
| |
| |
| |
| |
| <p>The string with the very first word of the string capitalized. |
| For the precise meaning of ``word'' see the <a href="#ref_builtin_word_list">word_list built-in</a>. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?cap_first} |
| ${"GreEN mouse"?cap_first} |
| ${"- green mouse"?cap_first}</pre></div> |
| |
| <p>The output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Green mouse |
| GreEN mouse |
| - green mouse</pre></div> |
| |
| <p>In the case of <code class="inline-code">"- green mouse"</code>, the first |
| word is the <code class="inline-code">-</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_uncap_first">uncap_first</h5> |
| |
| |
| |
| |
| <p>The opposite of <a href="#ref_builtin_cap_first"><code>cap_first</code></a>. |
| The string with the very first word of the string |
| un-capitalized.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_capitalize">capitalize</h5> |
| |
| |
| |
| |
| <p>The string with all words capitalized. For the precise meaning |
| of ``word'' see the <a href="#ref_builtin_word_list">word_list |
| built-in</a>. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?capitalize} |
| ${"GreEN mouse"?capitalize}</pre></div> |
| |
| <p>The output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Green Mouse |
| Green Mouse</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_chop_linebreak">chop_linebreak</h5> |
| |
| |
| |
| |
| <p>The string without the <a href="#gloss.lineBreak">line-break</a> at its very end if there |
| was a line-break, otherwise the unchanged string.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_date">date, time, datetime</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>The string converted to a date value. It is recommended to |
| specify a parameter that specifies the format. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign test1 = "10/25/1995"?date("MM/dd/yyyy")> |
| <#assign test2 = "15:05:30"?time("HH:mm:ss")> |
| <#assign test3 = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")> |
| ${test1} |
| ${test2} |
| ${test3}</pre></div> |
| |
| <p>will print something like (depends on the output locale |
| (language) and on other settings):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Oct 25, 1995 |
| 3:05:30 PM |
| Oct 25, 1995 3:05:00 PM</pre></div> |
| |
| <p>Note that the dates was converted back to string according to |
| the <code class="inline-code">date_format</code>, <code class="inline-code">time_format</code> |
| and <code class="inline-code">datetime_format</code> <a href="#ref.directive.setting">settings</a> (for more |
| information about converting dates to strings read: <a href="#ref_builtin_string_for_date">string built-in for |
| dates</a>, <a href="#dgui_template_valueinserion_universal_date">date |
| interpolations</a>). It does not mater what format did you use |
| when you have converted the strings to dates.</p> |
| |
| <p>You don't have to use the format parameter, if you know what |
| the default date/time/datetime format will be when the template is |
| processed:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign test1 = "Oct 25, 1995"?date> |
| <#assign test2 = "3:05:30 PM"?time> |
| <#assign test3 = "Oct 25, 1995 03:05:00 PM"?datetime> |
| ${test1} |
| ${test2} |
| ${test3}</pre></div> |
| |
| <p>If the string is not in the appropriate format, an error will |
| abort template processing when you try to access this |
| built-in.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_ends_with">ends_with</h5> |
| |
| |
| |
| |
| <p>Returns if this string ends with the specified substring. For |
| example <code class="inline-code">"redhead"?ends_with("head")</code> returns |
| boolean true. Also, <code class="inline-code">"head"?ends_with("head")</code> will |
| return true.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_html">html</h5> |
| |
| |
| |
| |
| |
| |
| <p>The string as HTML markup. That is, the string with |
| all:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><</code> replaced with |
| <code class="inline-code">&lt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">></code> replaced with |
| <code class="inline-code">&gt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">&</code> replaced with |
| <code class="inline-code">&amp;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">"</code> replaced with |
| <code class="inline-code">&quot;</code> |
| </li> |
| </ul> |
| |
| <p>Note that if you want to insert an attribute value securely, |
| you must quote the attribute value in the HTML template with |
| quotation mark (with <code class="inline-code">"</code>, not with |
| <code class="inline-code">'</code>):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><input type=text name=user value=<strong>"</strong>${user?html}<strong>"</strong>></pre></div> |
| |
| <p>Note that in HTML pages usually you want to use this built-in |
| for all interpolations. So you can spare a lot of typing and lessen |
| the chances of accidental mistakes by using the <a href="#ref_directive_escape"><code>escape</code> |
| directive</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_groups">groups</h5> |
| |
| |
| |
| |
| <p>This is used only with the result of the |
| <code class="inline-code">matches</code> built-in. See <a href="#ref_builtin_matches">there...</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_index_of">index_of</h5> |
| |
| |
| |
| |
| <p>Returns the index within this string of the first occurrence |
| of the specified substring. For example, |
| <code class="inline-code">"abcabc"?index_of("bc")</code> will return 1 (don't |
| forget that the index of the first character is 0). Also, you can |
| specify the index to start the search from: |
| <code class="inline-code">"abcabc"?index_of("bc", 2)</code> will return 4. There |
| is no restriction on the numerical value of the second parameter: if |
| it is negative, it has the same effect as if it were zero, and if it |
| is greater than the length of this string, it has the same effect as |
| if it were equal to the length of this string. Decimal values will |
| be truncated to integers.</p> |
| |
| <p>If the 1st parameter does not occur as a substring in this |
| string (starting from the given index, if you use the second |
| parameter), then it returns -1.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_j_string">j_string</h5> |
| |
| |
| |
| |
| <p>Escapes the string with the escaping rules of Java language |
| string literals, so it is safe to insert the value into a string |
| literal. In additional, all characters under <a href="#gloss.UCS">UCS</a> code point 0x20, that has no |
| dedicated escape sequence in Java language, will be replaced with |
| UNICODE escape |
| (<code class="inline-code">\u<em class="code-color">XXXX</em></code>).</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign beanName = 'The "foo" bean.'> |
| String BEAN_NAME = "${beanName?j_string}";</pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">String BEAN_NAME = "The \"foo\" bean.";</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_js_string">js_string</h5> |
| |
| |
| |
| |
| <p>Escapes the string with the escaping rules of JavaScript |
| language string literals, so it is safe to insert the value into a |
| string literal. Both quotation mark (<code class="inline-code">"</code>) and |
| apostrophe-quoate (<code class="inline-code">'</code>) are escaped. Starting from |
| FreeMarker 2.3.1, it also escapes <code class="inline-code">></code> as |
| <code class="inline-code">\></code> (to avoid |
| <code class="inline-code"></script></code>). Furthermore, all characters |
| under <a href="#gloss.UCS">UCS</a> code point 0x20, that has |
| no dedicated escape sequence in JavaScript language, will be |
| replaced with hexadecimal escape |
| (<code class="inline-code">\x<em class="code-color">XX</em></code>). (Of course, |
| according the JavaScript language string literal syntax, backslash |
| (<code class="inline-code">\</code>) will be escaped too, line-feed will be |
| escaped as <code class="inline-code">\n</code>, ...etc.)</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign user = "Big Joe's \"right hand\""> |
| <script> |
| alert("Welcome ${user?js_string}!"); |
| </script></pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><script> |
| alert("Welcome Big Joe\'s \"right hand\"!"); |
| </script></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_last_index_of">last_index_of</h5> |
| |
| |
| |
| |
| <p>Returns the index within this string of the last (rightmost) |
| occurrence of the specified substring. It returns the index of the |
| first (leftmost) character of the substring. For example: |
| <code class="inline-code">"abcabc"?last_index_of("ab")</code> will return 3. Also, |
| you can specify the index to start the search from. For example, |
| <code class="inline-code">"abcabc"?last_index_of("ab", 2)</code> will return 0. |
| Note that the second parameter indicates the maximum index of the |
| start of the substring. There is no restriction on the numerical |
| value of the second parameter: if it is negative, it has the same |
| effect as if it were zero, and if it is greater than the length of |
| this string, it has the same effect as if it were equal to the |
| length of this string. Decimal values will be truncated to |
| inegers.</p> |
| |
| <p>If the 1st parameter does not occur as a substring in this |
| string (before the given index, if you use the second parameter), |
| then it returns -1.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_length">length</h5> |
| |
| |
| |
| |
| <p>The number of characters in the string.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_lower_case">lower_case</h5> |
| |
| |
| |
| |
| <p>The lower case version of the string. For example |
| <code class="inline-code">"GrEeN MoUsE"</code> will be <code class="inline-code">"green |
| mouse"</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_left_pad">left_pad</h5> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <p>If it's used with 1 parameter, then it inserts spaces on the |
| beginning of the string until it reaches the length that is |
| specified as the parameter. If the string is already as long or |
| longer than the specified length, then it does nothing. For example, |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(5)}] |
| [${"a"?left_pad(5)}] |
| [${"ab"?left_pad(5)}] |
| [${"abc"?left_pad(5)}] |
| [${"abcd"?left_pad(5)}] |
| [${"abcde"?left_pad(5)}] |
| [${"abcdef"?left_pad(5)}] |
| [${"abcdefg"?left_pad(5)}] |
| [${"abcdefgh"?left_pad(5)}]</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">[ ] |
| [ a] |
| [ ab] |
| [ abc] |
| [ abcd] |
| [abcde] |
| [abcdef] |
| [abcdefg] |
| [abcdefgh]</pre></div> |
| |
| <p>If it's used with 2 parameters, then the 1st parameter means |
| the same as if you were using the built-in with only 1 parameter, |
| and the second parameter specifies what to insert instead of space |
| characters. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(5, "-")}] |
| [${"a"?left_pad(5, "-")}] |
| [${"ab"?left_pad(5, "-")}] |
| [${"abc"?left_pad(5, "-")}] |
| [${"abcd"?left_pad(5, "-")}] |
| [${"abcde"?left_pad(5, "-")}]</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">[-----] |
| [----a] |
| [---ab] |
| [--abc] |
| [-abcd] |
| [abcde]</pre></div> |
| |
| <p>The 2nd parameter can be a string whose length is greater than |
| 1. Then the string will be inserted periodically, for |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(8, ".oO")}] |
| [${"a"?left_pad(8, ".oO")}] |
| [${"ab"?left_pad(8, ".oO")}] |
| [${"abc"?left_pad(8, ".oO")}] |
| [${"abcd"?left_pad(8, ".oO")}]</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">[.oO.oO.o] |
| [.oO.oO.a] |
| [.oO.oOab] |
| [.oO.oabc] |
| [.oO.abcd]</pre></div> |
| |
| <p>The 2nd parameter must be a string value, and it must be at |
| least 1 character long.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_right_pad">right_pad</h5> |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <p>This is the same as <a href="#ref_builtin_left_pad"><code>left_pad</code></a>, |
| but it inserts the characters at the end of the string instead of |
| the beginning of the string.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">[${""?right_pad(5)}] |
| [${"a"?right_pad(5)}] |
| [${"ab"?right_pad(5)}] |
| [${"abc"?right_pad(5)}] |
| [${"abcd"?right_pad(5)}] |
| [${"abcde"?right_pad(5)}] |
| [${"abcdef"?right_pad(5)}] |
| [${"abcdefg"?right_pad(5)}] |
| [${"abcdefgh"?right_pad(5)}] |
| |
| [${""?right_pad(8, ".oO")}] |
| [${"a"?right_pad(8, ".oO")}] |
| [${"ab"?right_pad(8, ".oO")}] |
| [${"abc"?right_pad(8, ".oO")}] |
| [${"abcd"?right_pad(8, ".oO")}]</pre></div> |
| |
| <p>This will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">[ ] |
| [a ] |
| [ab ] |
| [abc ] |
| [abcd ] |
| [abcde] |
| [abcdef] |
| [abcdefg] |
| [abcdefgh] |
| |
| [.oO.oO.o] |
| [aoO.oO.o] |
| [abO.oO.o] |
| [abc.oO.o] |
| [abcdoO.o]</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_contains">contains</h5> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <p>Returns if the substring specified as the parameter to this |
| built-in occurrs in the string. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if "piceous"?contains("ice")>It contains "ice"</#if></pre></div> |
| |
| <p>This will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">It contains "ice"</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_matches">matches</h5> |
| |
| |
| |
| |
| <p>This is a ``power user'' built-in. Ignore it if you don't know |
| <a href="#gloss.regularExpression">regular |
| expressions</a>.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in will work only if you use Java2 platform 1.4 |
| or later. Otherwise it will stop template processing with |
| error.</p> |
| </div> |
| |
| |
| <p>This built-in determines if the string exactly matches the |
| pattern. Also, it returns the list of matching sub-strings. The |
| return value is a multi-type value:</p> |
| |
| <ul> |
| <li> |
| <p>Boolean: <code class="inline-code">true</code>, if it the string exactly |
| matches the pattern, otherwise <code class="inline-code">false</code>. For |
| example, <code class="inline-code">"fooo"?matches('fo*')</code> is |
| <code class="inline-code">true</code>, but |
| <code class="inline-code">"fooo bar"?matches('fo*')</code> is |
| <code class="inline-code">false</code>.</p> |
| </li> |
| |
| <li> |
| <p>Sequence: the list of matched substrings of the string. |
| Possibly a 0 length sequence.</p> |
| </li> |
| </ul> |
| |
| <p>For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if> |
| |
| <#assign res = "foo bar fyo"?matches("f.?o")> |
| <#if res>Matches.<#else>Does not match.</#if> |
| Matching sub-strings: |
| <#list res as m> |
| - ${m} |
| </#list></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Matches. |
| |
| Does not match. |
| Matching sub-strings: |
| - foo |
| - fyo</pre></div> |
| |
| <p>If the regular expression contains groups (parentheses), then |
| you can access them with the <code class="inline-code">groups</code> |
| built-in:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign res = "aa/rx; ab/r;"?matches("(\\w[^/]+)/([^;]+);")> |
| <#list res as m> |
| - ${m} is ${m?groups[1]} per ${m?groups[2]} |
| </#list></pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- aa/rx; is aa per rx |
| - ab/r; is ab per r</pre></div> |
| |
| <p><code class="inline-code">matches</code> accepts an optional 2nd parameter, |
| the <a href="#ref_builtin_string_flags">flags</a>. Note that |
| it does not support flag <code class="inline-code">r</code>, because it always |
| uses regular expressions.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_number">number</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>The string converted to numerical value. The number must be in |
| the same format as you specify numerical values directly in FTL. |
| That is, it must be in the locale independent form, where the |
| decimal separator is dot. In additional the built-in recognizes |
| scientific notation (e.g. <code class="inline-code">"1.23E6"</code>, |
| <code class="inline-code">"1.5e-8"</code>).</p> |
| |
| <p>If the string is not in the appropriate format, an error will |
| abort template processing when you try to access this |
| built-in.</p> |
| |
| <p>Known problem: If you use earlier Java2 platform than v1.3, |
| the built-ins will not recognize + prefix and scientific |
| notation.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_replace">replace</h5> |
| |
| |
| |
| |
| <p>It is used to replace all occurrences of a string in the |
| original string with another string. It does not deal with word |
| boundaries. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"this is a car acarus"?replace("car", "bulldozer")}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">this is a bulldozer abulldozerus</pre></div> |
| |
| <p>The replacing occurs in left-to-right order. This means that |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${"aaaaa"?replace("aaa", "X")}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Xaa</pre></div> |
| |
| <p>If the 1st parameter is an empty string, then all occurrences |
| of the empty string will be replaced, like |
| <code class="inline-code">"foo"?replace("","|")</code> will evaluate to |
| <code class="inline-code">"|f|o|o|"</code>.</p> |
| |
| <p><code class="inline-code">replace</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its |
| 3rd parameter.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_rtf">rtf</h5> |
| |
| |
| |
| |
| |
| |
| <p>The string as Rich text (RTF text). That is, the string with |
| all:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">\</code> replaced with |
| <code class="inline-code">\\</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">{</code> replaced with |
| <code class="inline-code">\{</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">}</code> replaced with |
| <code class="inline-code">\}</code></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_url">url</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <p>The string after URL escaping. This means that all |
| non-US-ASCII and reserved URL characters will be escaped with |
| <code class="inline-code">%<em class="code-color">XX</em></code>. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = 'a/b c'> |
| ${x?url}</pre></div> |
| |
| <p>The output will be (assuming that the charset used for the |
| escaping is an US-ASCII compatible charset):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">a%2Fb%20c</pre></div> |
| |
| <p>Note that it escapes <em>all</em> reserved URL |
| characters (<code class="inline-code">/</code>, <code class="inline-code">=</code>, |
| <code class="inline-code">&</code>, ...etc), so this encoding can be used for |
| encoding query parameter values, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a></pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>Above no HTML encoding (<code class="inline-code">?htm</code>) was needed, |
| because URL escaping escapes all reserved HTML characters anyway. |
| But watch: always quote the attribute value, and always with |
| normal quotation mark (<code class="inline-code">"</code>), never with |
| apostrophe quotation mark (<code class="inline-code">'</code>), because |
| apostrophe quotation mark is not escaped by the URL |
| escaping.</p> |
| </div> |
| |
| |
| <p>To do URL escaping a <a href="#gloss.charset">charset</a> must be chosen that will be |
| used for calculating the escaped parts |
| (<code class="inline-code">%<em class="code-color">XX</em></code>). If you are HTML |
| page author and you don't really understand this, don't worry: the |
| programmers should configure FreeMarker so that it uses the proper |
| charset by default (<span class="marked-for-programmers">programmers: see |
| more below...</span>). If you are a more technical minded user, |
| then you may want to know that the charset used is specified by the |
| <code class="inline-code">url_escaping_charset</code> setting, that can be set in |
| template execution time (or, preferably, earlier by the |
| programmers). For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- |
| This will use the charset specified by the programmers |
| before the template execution has started. |
| --> |
| <a href="foo.cgi?x=${x?url}">foo</a> |
| |
| <#-- Use UTF-8 charset for URL escaping from now: --> |
| <strong><#setting url_escaping_charset="UTF-8"></strong> |
| |
| <#-- This will surely use UTF-8 charset --> |
| <a href="bar.cgi?x=${x?url}">bar</a></pre></div> |
| |
| <p>Furthermore, you can explicitly specify a charset for a single |
| URL escaping as the parameter to the built-in:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url<strong>('ISO-8895-2')</strong>}">foo</a></pre></div> |
| |
| <p><span class="marked-for-programmers">If the <code class="inline-code">url</code> built-in has no |
| parameter, then it will use the charset specified as the value of |
| the <code class="inline-code">url_escaping_charset</code> setting. This setting |
| should be set by the software that encloses FreeMarker (e.g. a Web |
| application framework), because it is not set |
| (<code class="inline-code">null</code>) by default. If it is not set, then |
| FreeMarker falls back using the value of the |
| <code class="inline-code">output_encoding</code> setting, which is also not set by |
| default, so it is again the task of the enclosing software. If the |
| <code class="inline-code">output_encoding</code> setting is not set either, then |
| the parameterless <code class="inline-code">url</code> built-in can't be executed, |
| and it will cause execution time error. Of course, the |
| <code class="inline-code">url</code> built-in with parameter always |
| works.</span></p> |
| |
| <p><span class="marked-for-programmers">It's possible to set |
| <code class="inline-code">url_escaping_charset</code> in the template with the |
| <code class="inline-code">setting</code> directive, but it is bad practice, at |
| least in true MVC applications. The |
| <code class="inline-code">output_encoding</code> setting can't be set with the |
| <code class="inline-code">setting</code> directive, so that's surely the task of |
| the enclosing software. You may find more information regarding this |
| <a href="#pgui_misc_charset">here...</a></span></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_split">split</h5> |
| |
| |
| |
| |
| <p>It is used to split a string into a sequence of strings along |
| the occurrences of another string. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list "someMOOtestMOOtext"?split("MOO") as x> |
| - ${x} |
| </#list></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- some |
| - test |
| - text</pre></div> |
| |
| <p>Note that it is assumed that all occurrences of the separator |
| is before a new item, thus:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list "some,,test,text,"?split(",") as x> |
| - "${x}" |
| </#list></pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">- "some" |
| - "" |
| - "test" |
| - "text" |
| - ""</pre></div> |
| |
| <p><code class="inline-code">split</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its |
| 2nd parameter.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_starts_with">starts_with</h5> |
| |
| |
| |
| |
| <p>Returns if this string starts with the specified substring. |
| For example <code class="inline-code">"redhead"?starts_with("red")</code> returns |
| boolean true. Also, <code class="inline-code">"red"?starts_with("red")</code> will |
| return true.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_for_string">string (when used with a string value)</h5> |
| |
| |
| <p>Does nothing, just returns the string as-is. The exception is |
| that if the value is a multi-type value (e.g. it is both string and |
| sequence at the same time), then the resulting value will be only a |
| simple string, not a multi-type value. This can be utilized to |
| prevent the artifacts of multi-typing.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_trim">trim</h5> |
| |
| |
| |
| |
| <p>The string without leading and trailing white-space. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">(${" green mouse "?trim})</pre></div> |
| |
| <p>The output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">(green mouse)</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_upper_case">upper_case</h5> |
| |
| |
| |
| |
| <p>The upper case version of the string. For example |
| <code class="inline-code">"GrEeN MoUsE"</code> will be <code class="inline-code">"GREEN |
| MOUSE"</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_word_list">word_list</h5> |
| |
| |
| |
| |
| <p>A sequence that contains all words of the string in the order |
| as they appear in the string. Words are continual character |
| sequences that contain any character but <a href="#gloss.whiteSpace">white-space</a>. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign words = " a bcd, . 1-2-3"?word_list> |
| <#list words as word>[${word}]</#list></pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">[a][bcd,][.][1-2-3]</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_xhtml">xhtml</h5> |
| |
| |
| |
| |
| |
| |
| <p>The string as XHTML text. That is, the string with all:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><</code> replaced with |
| <code class="inline-code">&lt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">></code> replaced with |
| <code class="inline-code">&gt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">&</code> replaced with |
| <code class="inline-code">&amp;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">"</code> replaced with |
| <code class="inline-code">&quot;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">'</code> replaced with |
| <code class="inline-code">&#39;</code> |
| </li> |
| </ul> |
| |
| <p>The only difference between this built-in and the |
| <code class="inline-code">xml</code> built-in is that the <code class="inline-code">xhtml</code> |
| built-in escapes <code class="inline-code">'</code> as |
| <code class="inline-code">&#39;</code> instead of as |
| <code class="inline-code">&apos;</code>, because some older browsers don't |
| interpret <code class="inline-code">&apos;</code> correctly.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_xml">xml</h5> |
| |
| |
| |
| |
| |
| |
| <p>The string as XML text. That is, the string with all:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><</code> replaced with |
| <code class="inline-code">&lt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">></code> replaced with |
| <code class="inline-code">&gt;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">&</code> replaced with |
| <code class="inline-code">&amp;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">"</code> replaced with |
| <code class="inline-code">&quot;</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">'</code> replaced with |
| <code class="inline-code">&apos;</code> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_flags">Common flags</h5> |
| |
| |
| <p>Many string built-ins accept an optional string parameter, the |
| so called ``flags''. In this string, each letter influences a |
| certain aspect of the behavior of the built-in. For example, letter |
| <code class="inline-code">i</code> means that the built-in should not |
| differentiate the lower and upper-case variation of the same letter. |
| The order of the letters in the flags string is not |
| significant.</p> |
| |
| <p>This is the complete list of letters (flags):</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">i</code>: Case insensitive: do not |
| differentiate the lower and upper-case variation of the same |
| letter.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">f</code>: First only. That is, |
| replace/find/etc. only the first occurrence of something.</p> |
| </li> |
| |
| <li> |
| <p> <code class="inline-code">r</code>: The substring to find is a |
| <a href="#gloss.regularExpression">regular |
| expression</a>. FreeMarker uses the variation of regular |
| expressions described at <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html</a>. |
| <em>This flag will work only if you use Java2 platform 1.4 |
| or later. Otherwise it will cause template processing to stop |
| with error.</em></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">m</code>: Multi-line mode for regular |
| expressions. In multi-line mode the expressions |
| <code class="inline-code">^</code> and <code class="inline-code">$</code> match just after |
| or just before, respectively, a line terminator or the end of |
| the string. By default these expressions only match at the |
| beginning and the end of the entire string.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">s</code>: Enables dotall mode for regular |
| expressions (same as Perl singe-line mode). In dotall mode, the |
| expression <code class="inline-code">.</code> matches any character, including |
| a line terminator. By default this expression does not match |
| line terminators.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">c</code>: Permits whitespace and comments in |
| regular expressions.</p> |
| </li> |
| </ul> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign s = 'foo bAr baar'> |
| ${s?replace('ba', 'XY')} |
| i: ${s?replace('ba', 'XY', 'i')} |
| if: ${s?replace('ba', 'XY', 'if')} |
| r: ${s?replace('ba*', 'XY', 'r')} |
| ri: ${s?replace('ba*', 'XY', 'ri')} |
| rif: ${s?replace('ba*', 'XY', 'rif')}</pre></div> |
| |
| <p>This outputs this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">foo bAr XYar |
| i: foo XYr XYar |
| if: foo XYr baar |
| r: foo XYAr XYr |
| ri: foo XYr XYr |
| rif: foo XYr baar</pre></div> |
| |
| <p>This is the table of built-ins that use these common flags, |
| and which supports which flags:</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Built-in</th> |
| |
| |
| <th><code class="inline-code">i</code></th> |
| |
| |
| <th><code class="inline-code">r</code></th> |
| |
| |
| <th><code class="inline-code">m</code></th> |
| |
| |
| <th><code class="inline-code">s</code></th> |
| |
| |
| <th><code class="inline-code">c</code></th> |
| |
| |
| <th><code class="inline-code">f</code></th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">replace</code></td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>Yes</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">split</code></td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>Only with <code class="inline-code">r</code></td> |
| |
| |
| <td>No</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">match</code></td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>No</td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>Yes</td> |
| |
| |
| <td>No</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_number">Built-ins for numbers</h4> |
| |
| |
| |
| |
| <p>Related FAQs: Do you have things like 1,000,000 or 1 000 000 |
| instead of 1000000, or something like 3.14 instead of 3,14 or vice |
| versa? See <a href="#faq_number_grouping">this</a> and <a href="#faq_number_decimal_point">this</a> FAQ entry, also note |
| the <code class="inline-code">c</code> built-in above.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_c">c</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.3.</p> |
| </div> |
| |
| |
| <p>This built-in converts a number to string for ``computer |
| audience'' as opposed to human audience. That is, it formats with |
| the rules that programming languages used to use, which is |
| independent of all the locale and number format settings of |
| FreeMarker. It always uses dot as decimal separator, and it never |
| uses grouping separators (like 3,000,000), nor exponential form |
| (like 5E20), nor superfluous leading or trailing 0-s (like 03 or |
| 1.0), nor + sign (like +1). It will print at most 16 digits after |
| the decimal dot, and thus numbers whose absolute value is less than |
| 1E-16 will be shown as 0. This built-in is crucial because be |
| default (like with <code class="inline-code">${x}</code>) numbers are converted to |
| strings with the locale (language, country) specific number |
| formatting, which is for human readers (like 300000 is possibly |
| printed as 3,000,000). When the number is printed not for human |
| audience (e.g., for a database record ID used as the part of an URL, |
| or as invisible field value in a HTML form, or for printing |
| CSS/JavaScript numerical literals) this built-in must be used to |
| print the number (i.e., use <code class="inline-code">${x?c}</code> instead of |
| <code class="inline-code">${x}</code>), or else the output will be possibly broken |
| depending on the current number formatting settings and locale (like |
| the decimal point is not dot, but comma in many countries) and the |
| value of the number (like big numbers are possibly ``damaged'' by |
| grouping separators).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_for_number">string (when used with a numerical value)</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Converts a number to a string. It uses the default format that |
| the programmer has specified. You can also specify a number format |
| explicitly with this built-in, as it will be shown later.</p> |
| |
| <p>There are four predefined number formats: |
| <code class="inline-code">computer</code>, <code class="inline-code">currency</code>, |
| <code class="inline-code">number</code>, and <code class="inline-code">percent</code>. The exact |
| meaning of these is locale (nationality) specific, and is controlled |
| by the Java platform installation, rather than by FreeMarker, except |
| for <code class="inline-code">computer</code>, which uses the same formatting as |
| <a href="#ref_builtin_c">the <code>c</code> |
| built-in</a>. You can use these predefined formats like |
| this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x=42> |
| ${x} |
| ${x?string} <#-- the same as ${x} --> |
| ${x?string.number} |
| ${x?string.currency} |
| ${x?string.percent} |
| ${x?string.computer}</pre></div> |
| |
| <p>If your locale is US English, this will certainly |
| produce:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">42 |
| 42 |
| 42 |
| $42.00 |
| 4,200% |
| 42</pre></div> |
| |
| <p>The output of first three expressions is identical because the |
| first two expressions use the default format, which is "number" |
| here. You can change this default using a setting:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#setting number_format="currency"> |
| <#assign x=42> |
| ${x} |
| ${x?string} <#-- the same as ${x} --> |
| ${x?string.number} |
| ${x?string.currency} |
| ${x?string.percent}</pre></div> |
| |
| <p>Will now output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">$42.00 |
| $42.00 |
| 42 |
| $42.00 |
| 4,200%</pre></div> |
| |
| <p>since the default number format was set to "currency".</p> |
| |
| <p>Beside the three predefined formats, you can use arbitrary |
| number format patterns written in <a href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java |
| decimal number format syntax</a>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = 1.234> |
| ${x?string("0")} |
| ${x?string("0.#")} |
| ${x?string("0.##")} |
| ${x?string("0.###")} |
| ${x?string("0.####")} |
| |
| ${1?string("000.00")} |
| ${12.1?string("000.00")} |
| ${123.456?string("000.00")} |
| |
| ${1.2?string("0")} |
| ${1.8?string("0")} |
| ${1.5?string("0")} <-- 1.5, rounded towards even neighbor |
| ${2.5?string("0")} <-- 2.5, rounded towards even neighbor |
| |
| ${12345?string("0.##E0")}</pre></div> |
| |
| <p>outputs this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1 |
| 1.2 |
| 1.23 |
| 1.234 |
| 1.234 |
| |
| 001.00 |
| 012.10 |
| 123.46 |
| |
| 1 |
| 2 |
| 2 <-- 1.5, rounded towards even neighbor |
| 2 <-- 2.5, rounded towards even neighbor |
| |
| 1.23E4</pre></div> |
| |
| <p>Following the financial and statistics practice, the rounding |
| goes according the so called half-even rule, which means rounding |
| towards the nearest ``neighbor'', unless both neighbors are |
| equidistant, in which case, it rounds towards the even neighbor. |
| This was visible in the above example if you look at the rounding of |
| 1.5 and of 2.5, as both were rounded to 2, since 2 is even, but 1 |
| and 3 are odds.</p> |
| |
| <p>Appart from the Java decimal syntax patterns, you can also |
| write <code class="inline-code">${aNumber?string("currency")}</code> and like, |
| that will do the same as |
| <code class="inline-code">${aNumber?string.currency}</code> and like.</p> |
| |
| <p>As it was shown for the predefined formats earlier, the |
| default formatting of the numbers can be set in the template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#setting number_format="0.##"> |
| ${1.234}</pre></div> |
| |
| <p>outputs this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1.23</pre></div> |
| |
| <p>Note that the number formatting is locale sensitive:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#setting locale="en_US"> |
| US people write: ${12345678?string(",##0.00")} |
| <#setting locale="hu"> |
| Hungarian people write: ${12345678?string(",##0.00")}</pre></div> |
| |
| <p>outputs this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">US people write: 12,345,678.00 |
| Hungarian people write: 12 345 678,00</pre></div> |
| |
| <p>You can find information about the formatting of dates <a href="#ref_builtin_string_for_date">here</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_rounding">round, floor, ceiling</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The rounding built-ins exist since FreeMarker 2.3.13.</p> |
| </div> |
| |
| |
| <p>Converts a number to a whole number using the specified |
| rounding rule:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">round</code>: Rounds to the nearest whole |
| number. If the number ends with .5, then it rounds upwards |
| (i.e., towards positive infinity)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">floor</code>: Rounds the number downwards |
| (i.e., towards neagative infinity)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ceiling</code>: Rounds the number upwards |
| (i.e., towards positive infinity)</p> |
| </li> |
| </ul> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign testlist=[ |
| 0, 1, -1, 0.5, 1.5, -0.5, |
| -1.5, 0.25, -0.25, 1.75, -1.75]> |
| <#list testlist as result> |
| ${result} ?floor=${result?floor} ?ceiling=${result?ceiling} ?round=${result?round} |
| </#list></pre></div> |
| |
| <p>Prints:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 0 ?floor=0 ?ceiling=0 ?round=0 |
| 1 ?floor=1 ?ceiling=1 ?round=1 |
| -1 ?floor=-1 ?ceiling=-1 ?round=-1 |
| 0.5 ?floor=0 ?ceiling=1 ?round=1 |
| 1.5 ?floor=1 ?ceiling=2 ?round=2 |
| -0.5 ?floor=-1 ?ceiling=0 ?round=0 |
| -1.5 ?floor=-2 ?ceiling=-1 ?round=-1 |
| 0.25 ?floor=0 ?ceiling=1 ?round=0 |
| -0.25 ?floor=-1 ?ceiling=0 ?round=0 |
| 1.75 ?floor=1 ?ceiling=2 ?round=2 |
| -1.75 ?floor=-2 ?ceiling=-1 ?round=-2</pre></div> |
| |
| <p>These built-ins may be useful in pagination operations and |
| like. If you just want to <em>display</em> numbers in |
| rounded form, then you should rather use the <a href="#ref_builtin_string_for_number"><code>string</code> |
| built-in</a> or the <a href="#ref.setting.number_format"><code>number_format</code> |
| setting</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_date">Built-ins for dates</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_for_date">string (when used with a date value)</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>This built-in converts a date to a string, with the specified |
| formatting. (when the default format dictated by the |
| <code class="inline-code">date_format</code>, <code class="inline-code">time_format</code> and |
| <code class="inline-code">datetime_format</code> <a href="#ref.directive.setting">settings</a> of FreeMarker are |
| good for you, then you do not need this built-in.)</p> |
| |
| <p>The format can be one of the predefined formats, or you can |
| specify the formatting pattern explicitly.</p> |
| |
| <p>The predefined formats are <code class="inline-code">short</code>, |
| <code class="inline-code">medium</code>, <code class="inline-code">long</code>, and |
| <code class="inline-code">full</code> which define how verbose the resulting text |
| will be. For example, if the locale of the output is U.S. English, |
| and the time zone is the U.S. Pacific Time zone, then this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${openingTime?string.short} |
| ${openingTime?string.medium} |
| ${openingTime?string.long} |
| ${openingTime?string.full} |
| |
| ${nextDiscountDay?string.short} |
| ${nextDiscountDay?string.medium} |
| ${nextDiscountDay?string.long} |
| ${nextDiscountDay?string.full} |
| |
| ${lastUpdated?string.short} |
| ${lastUpdated?string.medium} |
| ${lastUpdated?string.long} |
| ${lastUpdated?string.full}</pre></div> |
| |
| <p>will prints something like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">12:45 PM |
| 12:45:09 PM |
| 12:45:09 PM CEST |
| 12:45:09 PM CEST |
| |
| 4/20/07 |
| Apr 20, 2007 |
| April 20, 2007 |
| Friday, April 20, 2007 |
| |
| 4/20/07 12:45 PM |
| Apr 20, 2007 12:45:09 PM |
| April 20, 2007 12:45:09 PM CEST |
| Friday, April 20, 2007 12:45:09 PM CEST</pre></div> |
| |
| <p>The exact meaning of <code class="inline-code">short</code>, |
| <code class="inline-code">medium</code>, <code class="inline-code">long</code>, and |
| <code class="inline-code">full</code> depends on the current locale (language). |
| Furthermore, it is specified not by FreeMarker, but the Java |
| platform implementation you run FreeMarker on.</p> |
| |
| <p>For dates that contains both date and time part, you can |
| specify the length of the date and time part independently:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${lastUpdated?string.short_long} <#-- short date, long time --> |
| ${lastUpdated?string.medium_short} <#-- medium date, short time --></pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">4/8/03 9:24:44 PM PDT |
| Apr 8, 2003 9:24 PM</pre></div> |
| |
| <p>Note that <code class="inline-code">?string.short</code> is the same as |
| <code class="inline-code">?string.short_short</code>, |
| <code class="inline-code">?string.medium</code> is the same as |
| <code class="inline-code">?string.medium_medium</code>, etc.</p> |
| |
| <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>Unfortunately, because of the limitations of the Java |
| platform, it can happen that you have date variables in the |
| data-model, where FreeMarker can't decide if the variable stores |
| only date part (year, month, day), only time part (hour, minute, |
| second, millisecond) or both. In this case, FreeMarker don't know |
| how to display the date when you write something like |
| <code class="inline-code">${lastUpdated?string.short}</code> or simply |
| <code class="inline-code">${lastUpdated}</code>, and thus it will stop with |
| error. To prevent this, you can help FreeMarker with the <a href="#ref_builtin_date_datetype"><code>?date</code>, |
| <code>?time</code> and <code>?datetime</code> |
| built-ins</a>. For example: |
| <code class="inline-code">${lastUpdated?datetime?string.short}</code>. Ask the |
| programmer if certain variables of the data-model has this |
| problem, or always use <code class="inline-code">?date</code>, |
| <code class="inline-code">?time</code> and <code class="inline-code">?datetime</code> |
| built-ins.</p> |
| </div> |
| |
| |
| <p>Instead of using the predefined formats, you can specify the |
| formatting pattern explicitly with |
| <code class="inline-code">?string(<em class="code-color">pattern_string</em>)</code>. |
| The pattern uses <a href="http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html">Java |
| date format syntax</a>. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")} |
| ${lastUpdated?string("EEE, MMM d, ''yy")} |
| ${lastUpdated?string("EEEE, MMMM dd, yyyy, hh:mm:ss a '('zzz')'")}</pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">2003-04-08 21:24:44 Pacific Daylight Time |
| Tue, Apr 8, '03 |
| Tuesday, April 08, 2003, 09:24:44 PM (PDT)</pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>Unlike with the predefined formats, you never need to use |
| <code class="inline-code">?date</code>, <code class="inline-code">?time</code> and |
| <code class="inline-code">?datetime</code> with explicitly given patterns, since |
| with the pattern you tell FreeMarker what parts of the date to |
| show. However, FreeMarker will trust you blindly, so you can show |
| "noise" if you display parts that are actually not stored in the |
| variable. For example, <code class="inline-code">${openingTime?string("yyyy-MM-dd |
| hh:mm:ss a")}</code>, where <code class="inline-code">openingTime</code> |
| stores only time, will display <code class="inline-code">1970-01-01 09:24:44 |
| PM</code>.</p> |
| </div> |
| |
| |
| <p>The pattern string also can be <code class="inline-code">"short"</code>, |
| <code class="inline-code">"medium"</code>, ..., <code class="inline-code">"short_medium"</code>, |
| ...etc. These are the same as if you would use the predefined |
| formats with the dot syntax: |
| <code class="inline-code">someDate?string("short")</code> and |
| <code class="inline-code">someDate?string.short</code> are equivalent.</p> |
| |
| <p>See also: <a href="#dgui_template_valueinserion_universal_date">the |
| interpolation of dates</a></p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_date_datetype">date, time, datetime</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>These built-ins can be used to specify which parts of the date |
| variable are in use:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">date</code>: Only the year, month and day |
| parts are used.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">time</code>: Only the hour, minute, second and |
| millisecond parts are used.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">datetime</code>: Both the date and the time |
| parts are used.</p> |
| </li> |
| </ul> |
| |
| <p>In optimal case, you do not need to use these built-ins. |
| Unfortunately, because of the technical limitations of the Java |
| platform, FreeMarker sometimes can't find out which parts of the |
| date are in use (i.e. only the year+month+day, or only |
| hour+minute+second+millisecond, or both); ask the programmers which |
| variables has this problem. If FreeMarker has to execute an |
| operation where this information is needed -- such as displaying the |
| date as text -- but it does not know which parts are in use, it will |
| stop with error. This is when you have to use these built-ins. For |
| example, assume <code class="inline-code">openingTime</code> is a such problematic |
| variable:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = openingTime> <#-- no problem can occur here --> |
| ${openingTime?time} <#-- without ?time it would fail --> |
| <#-- For the sake of better understanding, consider this: --> |
| <#assign openingTime = openingTime?time> |
| ${openingTime} <#-- this will work now --></pre></div> |
| |
| <p>There is another usage of these built-ins: to truncate dates. |
| For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">Last updated: ${lastUpdated} <#-- assume that lastUpdated is a date-time value --> |
| Last updated date: ${lastUpdated?date} |
| Last updated time: ${lastUpdated?time}</pre></div> |
| |
| <p>will output something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Last updated: 04/25/2003 08:00:54 PM |
| Last updated date: 04/25/2003 |
| Last updated time: 08:00:54 PM</pre></div> |
| |
| <p>If the left side of the <code class="inline-code">?</code> is string, then |
| these built-ins <a href="#ref_builtin_string_date">convert |
| strings to date variable</a>.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_boolean">Built-ins for booleans</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_string_for_boolean">string (when used with a boolean value)</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>Converts a boolean to a string. You can use it in two |
| ways:</p> |
| |
| <ul> |
| <li> |
| <p>As <code class="inline-code">foo?string</code>: This will convert the |
| boolean to string using the default strings for representing |
| true and false values. By default, true is rendered as |
| <code class="inline-code">"true"</code> and false is rendered as |
| <code class="inline-code">"false"</code>. This is mostly useful if you |
| generate source code with FreeMarker, since the values are not |
| locale (language, country) sensitive. To change these default |
| strings, you can use the <code class="inline-code">boolean_format</code> <a href="#ref_directive_setting">setting</a>. Note, that if |
| the variable is multi-type variable that is both boolean and |
| string, then the string value of the variable will be |
| returned.</p> |
| </li> |
| |
| <li> |
| <p>As <code class="inline-code">foo?string("yes", "no")</code>: This will |
| return the first parameter (here: <code class="inline-code">"yes"</code>) if |
| the boolean is true, otherwise the second parameter (here: |
| <code class="inline-code">"no"</code>). Note that the return value is always a |
| string; if the parameters were numbers, they would be converted |
| to strings first.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_sequence">Built-ins for sequences</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_first">first</h5> |
| |
| |
| |
| |
| <p>The first subvariable of the sequence. Template processing |
| will die with error if the sequence is empty.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_last">last</h5> |
| |
| |
| |
| |
| <p>The last subvariable of the sequence. Template processing will |
| die with error if the sequence is empty.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_seq_contains">seq_contains</h5> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="#ref_builtin_contains"><code>contains</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Tells if the sequence contains the specified value. It has 1 |
| parameter, the value to find. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = ["red", 16, "blue", "cyan"]> |
| "blue": ${x?seq_contains("blue")?string("yes", "no")} |
| "yellow": ${x?seq_contains("yellow")?string("yes", "no")} |
| 16: ${x?seq_contains(16)?string("yes", "no")} |
| "16": ${x?seq_contains("16")?string("yes", "no")}</pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">"blue": yes |
| "yellow": no |
| 16: yes |
| "16": no</pre></div> |
| |
| <p>To find the value the built-in uses FreeMarker's comparison |
| rules (as if you was using <a href="#dgui_template_exp_comparison"><code>==</code> |
| operator</a>), except that comparing two values of different |
| types or of types for which FreeMarker doesn't support comparison |
| will not cause error, just will be evaluated as the two values are |
| not equal. Thus, you can use it only to find scalar values (i.e. |
| string, number, boolean or date/time values). For other types the |
| result will be always <code class="inline-code">false</code>.</p> |
| |
| <p>For fault tolerance, this built-in also works with |
| collections.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_seq_index_of">seq_index_of</h5> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="#ref_builtin_index_of"><code>index_of</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Returns the index of the first occurrence of a value in the |
| sequence, or <code class="inline-code">-1</code> if the sequence doesn't contain |
| the specified value. The value to find is specified as the first |
| parameter. For example this template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign colors = ["red", "green", "blue"]> |
| ${colors?seq_index_of("blue")} |
| ${colors?seq_index_of("red")} |
| ${colors?seq_index_of("purple")}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">2 |
| 0 |
| -1</pre></div> |
| |
| <p>To find the value the built-in uses FreeMarker's comparison |
| rules (as if you was using <a href="#dgui_template_exp_comparison"><code>==</code> |
| operator</a>), except that comparing two values of different |
| types or of types for which FreeMarker doesn't support comparison |
| will not cause error, just will be evaluated as the two values are |
| not equal. Thus, you can use it only to find scalar values (i.e. |
| string, number, boolean or date/time values). For other types the |
| result will be always <code class="inline-code">-1</code>.</p> |
| |
| <p>The index where the searching is started can be optionally |
| given as the 2nd parameter. This may be useful if the same item can |
| occur for multiple times in the same sequence. There is no |
| restriction on the numerical value of the second parameter: if it is |
| negative, it has the same effect as if it were zero, and if it is |
| greater than the length of the sequence, it has the same effect as |
| if it were equal to the length of the sequence. Decimal values will |
| be truncated to integers. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]> |
| No 2nd param: ${names?seq_index_of("Joe")} |
| -2: ${names?seq_index_of("Joe", -2)} |
| -1: ${names?seq_index_of("Joe", -1)} |
| 0: ${names?seq_index_of("Joe", 0)} |
| 1: ${names?seq_index_of("Joe", 1)} |
| 2: ${names?seq_index_of("Joe", 2)} |
| 3: ${names?seq_index_of("Joe", 3)} |
| 4: ${names?seq_index_of("Joe", 4)}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">No 2nd param: 0 |
| -2: 0 |
| -1: 0 |
| 0: 0 |
| 1: 2 |
| 2: 2 |
| 3: -1 |
| 4: -1</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_seq_last_index_of">seq_last_index_of</h5> |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in is available since FreeMarker 2.3.1. It |
| doesn't exist in 2.3.</p> |
| </div> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The <code class="inline-code">seq_</code> prefix is required in the |
| built-in name to differentiate it from the <a href="#ref_builtin_last_index_of"><code>last_index_of</code> |
| built-in</a> that searches a substring in a string (since a |
| variable can be both string and sequence on the same time).</p> |
| </div> |
| |
| |
| <p>Returns the index of the last occurrence of a value in the |
| sequence, or <code class="inline-code">-1</code> if the sequence doesn't contain |
| the specified value. That is, it is the same as <a href="#ref_builtin_seq_index_of"><code>seq_index_of</code></a>, |
| just it searches backward starting from the last item of the |
| sequence. It also supports the optional 2nd parameter that specifies |
| the index where the searching is started. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign names = ["Joe", "Fred", "Joe", "Susan"]> |
| No 2nd param: ${names?seq_last_index_of("Joe")} |
| -2: ${names?seq_last_index_of("Joe", -2)} |
| -1: ${names?seq_last_index_of("Joe", -1)} |
| 0: ${names?seq_last_index_of("Joe", 0)} |
| 1: ${names?seq_last_index_of("Joe", 1)} |
| 2: ${names?seq_last_index_of("Joe", 2)} |
| 3: ${names?seq_last_index_of("Joe", 3)} |
| 4: ${names?seq_last_index_of("Joe", 4)}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">No 2nd param: 2 |
| -2: -1 |
| -1: -1 |
| 0: 0 |
| 1: 0 |
| 2: 2 |
| 3: 2 |
| 4: 2</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_reverse">reverse</h5> |
| |
| |
| |
| |
| <p>The sequence with reversed order.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_size">size</h5> |
| |
| |
| |
| |
| <p>The number of subvariables in sequence (as a numerical value). |
| The highest possible index in sequence <code class="inline-code">s</code> is |
| <code class="inline-code">s?size - 1</code> (since the index of the first |
| subvariable is 0) assuming that the sequence has at least one |
| subvariable.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_sort">sort</h5> |
| |
| |
| |
| |
| |
| |
| <p>Returns the sequence sorted in ascending order. This will work |
| only if all subvariables are strings, or if all subvariables are |
| numbers, or, since FreeMarker 2.3.1, if all subvariables are date |
| values (date, time, or date+time). If the subvariables are strings, |
| it uses locale (language) specific lexical sorting (which is usually |
| not case sensitive). For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort> |
| <#list ls as i>${i} </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">aardvark Barbara beetroot whale zeppelin</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_sort_by">sort_by</h5> |
| |
| |
| |
| |
| |
| |
| <p>Returns the sequence of hashes sorted by the given hash |
| subvariable in ascending order. The rules are the same as with the |
| <code class="inline-code">sort</code> built-in, except that the subvariables of |
| the sequence must be hashes, and you have to give the name of a hash |
| subvariable that will decide the order. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign ls = [ |
| {"name":"whale", "weight":2000}, |
| {"name":"Barbara", "weight":53}, |
| {"name":"zeppelin", "weight":-200}, |
| {"name":"aardvark", "weight":30}, |
| {"name":"beetroot", "weight":0.3} |
| ]> |
| Order by name: |
| <#list ls?sort_by("name") as i> |
| - ${i.name}: ${i.weight} |
| </#list> |
| |
| Order by weight: |
| <#list ls?sort_by("weight") as i> |
| - ${i.name}: ${i.weight} |
| </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Order by name: |
| - aardvark: 30 |
| - Barbara: 53 |
| - beetroot: 0.3 |
| - whale: 2000 |
| - zeppelin: -200 |
| |
| Order by weight: |
| - zeppelin: -200 |
| - beetroot: 0.3 |
| - aardvark: 30 |
| - Barbara: 53 |
| - whale: 2000</pre></div> |
| |
| <p>Since FreeMarker 2.3.1, if the subvariable that you want to |
| use for the sorting is on a deeper level (that is, if it is a |
| subvariable of a subvariable and so on), then you can use a sequence |
| as parameter, that specifies the names of the subvariables that lead |
| down to the desired subvariable. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign members = [ |
| {"name": {"first": "Joe", "last": "Smith"}, "age": 40}, |
| {"name": {"first": "Fred", "last": "Crooger"}, "age": 35}, |
| {"name": {"first": "Amanda", "last": "Fox"}, "age": 25}]> |
| Sorted by name.last: |
| <#list members?sort_by(['name', 'last']) as m> |
| - ${m.name.last}, ${m.name.first}: ${m.age} years old |
| </#list></pre></div> |
| |
| <p>will print (with US locale at least):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Sorted by name.last: |
| - Crooger, Fred: 35 years old |
| - Fox, Amanda: 25 years old |
| - Smith, Joe: 40 years old</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_chunk">chunk</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This built-in exists since FreeMarker 2.3.3.</p> |
| </div> |
| |
| |
| <p>This built-in splits a sequence into multiple sequences of the |
| size given with the 1st parameter to the built-in (like |
| <code class="inline-code">mySeq?chunk(3)</code>). The result is the sequence of |
| these sequences. The last sequence is possibly shorter than the |
| given size, unless the 2nd parameter is given (like |
| <code class="inline-code">mySeq?chunk(3, '-')</code>), that is the item used to |
| make up the size of the last sequence to the given size. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign seq = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']> |
| |
| <#list seq?chunk(4) as row> |
| <#list row as cell>${cell} </#list> |
| </#list> |
| |
| <#list seq?chunk(4, '-') as row> |
| <#list row as cell>${cell} </#list> |
| </#list></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> |
| a b c d |
| e f g h |
| i j |
| |
| a b c d |
| e f g h |
| i j - - |
| </pre></div> |
| |
| <p>This built in is mostly for outputting sequnces in |
| tabular/columnar format. When used with HTML tables, the 2nd |
| parameter is often <code class="inline-code">"\xA0"</code> (that is the code of |
| the no-break space character, also known as ``nbsp''), so the border |
| of the empty TD-s will not be missing.</p> |
| |
| <p>The 1st parameter must be a number that is at least 1. If the |
| number is not integer, it will be silently rounded down to integer |
| (i.e. both 3.1 and 3.9 will be rounded to 3). The 2nd parameter can |
| be of any type and value.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_hash">Built-ins for hashes</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_keys">keys</h5> |
| |
| |
| |
| |
| <p>A sequence that contains all the lookup keys in the hash. Note |
| that not all hashes support this (ask the programmer if a certain |
| hash allows this or not).</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign h = {"name":"mouse", "price":50}> |
| <#assign keys = h?keys> |
| <#list keys as key>${key} = ${h[key]}; </#list></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">name = mouse; price = 50;</pre></div> |
| |
| <p>Since hashes do not define an order for their subvariables in |
| general, the order in which key names are returned can be arbitrary. |
| However, some hashes maintain a meaningful order (ask the programmer |
| if a certain hash does that or not). For example, hashes created |
| with the above <code class="inline-code">{<em class="code-color">...</em>}</code> |
| syntax preserve the same order as you have specified the |
| subvariables.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_values">values</h5> |
| |
| |
| |
| |
| <p>A sequence that contains all the variables in the hash. Note |
| that not all hashes support this (ask the programmer if a certain |
| hash allows this or not).</p> |
| |
| <p>As of the order in which the values are returned, the same |
| applies as with the <code class="inline-code">keys</code> built-in; see |
| there.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_node">Built-ins for nodes (for XML)</h4> |
| |
| |
| |
| |
| <p>Note that the variables returned by these built-ins are |
| generated by the node variable implementation it is used with. This |
| means that the returned variables can have extra features in |
| additional to what it stated here, for example, with the <a href="#xgui_expose_dom">XML DOM nodes</a> the sequence retuned by |
| the <code class="inline-code">children</code> built-in also can be used as hash and |
| maybe as string, as it is described in the <a href="#xgui">part |
| about XML processing</a>.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_children">children</h5> |
| |
| |
| |
| |
| <p>A sequence that contains all of this node's child nodes (i.e. |
| immediate descendant nodes).</p> |
| |
| <p>XML: This is almost the same as special hash key |
| <code class="inline-code">*</code>, except that it returns all nodes, not only |
| elements. So the possible children are element nodes, text nodes, |
| comment nodes, processing instruction nodes, etc. but |
| <em>not</em> attribute nodes. Attribute nodes are |
| excluded from the sequence.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_parent">parent</h5> |
| |
| |
| |
| |
| <p>The node that is this node's immediate parent in the node |
| tree. The root node has no parent node, so for the root node, the |
| expression |
| <code class="inline-code"><em class="code-color">node</em>?parent??</code> |
| evaluates to <code class="inline-code">false</code>.</p> |
| |
| <p>XML: Note that the value returned by this built-in is also a |
| sequence (same as the result of XPath expression |
| <code class="inline-code">..</code>, when you write |
| <code class="inline-code">someNode[".."]</code>). Also note that for attribute |
| nodes, it returns the element the attribute belongs to, despite that |
| attribute nodes are not counted as children of the element.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_root">root</h5> |
| |
| |
| |
| |
| <p>The node that is the root of the tree of nodes to which this |
| node belongs.</p> |
| |
| <p>XML: According to W3C, the root of an XML document is not the |
| topmost element node, but the document itself, which is the parent |
| of the topmost element. For example, if you want to get the topmost |
| <em>element</em> of the XML (the so called ``document |
| element''; do not mix it with the ``document''), which is called |
| <code class="inline-code">foo</code>, then you have to write |
| <code class="inline-code">someNode?root.foo</code>. If you write just |
| <code class="inline-code">someNode?root</code>, then you get the document itself, |
| and not the document element.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_ancestors">ancestors</h5> |
| |
| |
| |
| |
| <p>A sequence that contains all the node's ancestors, starting |
| with the immediate parent and ending with the root node. The result |
| of this built-in is also a method, by which you can filter the |
| result with the <a href="#gloss.fullQualifiedName">full-qualified name</a> of the |
| node. For example as <code class="inline-code">node?ancestors("section")</code> to |
| get the sequence of all ancestors with name |
| <code class="inline-code">section</code>.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_node_name">node_name</h5> |
| |
| |
| |
| |
| <p>Returns the string that is used to determine what user-defined |
| directive to invoke to handle this node when it is ``visited''. See: |
| the <a href="#ref.directive.visit">visit</a> and <a href="#ref.directive.recurse">recurse</a> directives.</p> |
| |
| <p>XML: If the node is an element or attribute, then the string |
| will be the local (prefix free) name of the element or attribute. |
| Otherwise the name usually starts with <code class="inline-code">@</code> followed |
| by the node type. See <a href="#misc.xguiTable">this |
| table</a>. Note that this node name is not the same as the node |
| name returned in the DOM API; the goal of FreeMarker node names is |
| to give the name of the used-defined directive that will process the |
| node.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_node_type">node_type</h5> |
| |
| |
| |
| |
| <p>A string that describes the type of node this is. FreeMarker |
| does not define the exact meaning of node type; it depends on what |
| your variables are modeling. It's possible that a node doesn't |
| support node type at all. In this case, the built-in evaluates to an |
| undefined value, so you can't use the returned value. (You can still |
| check if a node supports the type property with |
| <code class="inline-code"><em class="code-color">node</em>?node_type??</code>.)</p> |
| |
| <p>XML: The possible values are: <code class="inline-code">"attribute"</code>, |
| <code class="inline-code">"text"</code>, <code class="inline-code">"comment"</code>, |
| <code class="inline-code">"document_fragment"</code>, |
| <code class="inline-code">"document"</code>, <code class="inline-code">"document_type"</code>, |
| <code class="inline-code">"element"</code>, <code class="inline-code">"entity"</code>, |
| <code class="inline-code">"entity_reference"</code>, |
| <code class="inline-code">"notation"</code>, <code class="inline-code">"pi"</code>. Note that a |
| there is no <code class="inline-code">"cdata"</code> type, because CDATA is |
| considered as plain text node.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_node_namespace">node_namespace</h5> |
| |
| |
| |
| |
| <p>Returns the namespace string of the node. FreeMarker does not |
| define the exact meaning of node namespace; it depends on what your |
| node variables are modeling. It's possible that a node doesn't have |
| any node namespace defined. In this case, the built-in should |
| evaluate to undefined variable (i.e. |
| <code class="inline-code">node?<em class="code-color">node_namespace</em>??</code> |
| is <code class="inline-code">false</code>), so you can't use the returned |
| value.</p> |
| |
| <p>XML: In the case of XML, it's the XML namespace URI (such as |
| <code class="inline-code">"http://www.w3.org/1999/xhtml"</code>). If an element or |
| attribute node does not use XML namespace, then this built-in |
| evaluates to an empty string. For other XML nodes this built-in |
| always return undefined variable.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_builtins_expert">Seldom used and expert built-ins</h4> |
| |
| |
| <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> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_numType">byte, double, float, int, long, short</h5> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <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, except for resolving ambiguity in |
| overloaded method invocation.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_eval">eval</h5> |
| |
| |
| |
| |
| |
| |
| <p>This built-in evaluates a string as an FTL expression. For |
| example <code class="inline-code">"1+2"?eval</code> returns number 3.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_has_content">has_content</h5> |
| |
| |
| |
| |
| <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, sequence or hash with |
| no subvariables, a collection which has passed the last element. If |
| the value is not a string or sequence or hash or collection, 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_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> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_interpret">interpret</h5> |
| |
| |
| |
| |
| <p>This built-in interprets a string as a FTL template, and |
| returns an user-defined directive that - when applied to any block - |
| executes the template just as if it was included at that point. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#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-wrapper"><pre class="code-block code-output">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 that |
| was generated on-the-fly using the |
| <code class="inline-code">interpret</code>.</p> |
| |
| <p>You can also apply this built-in to a two-element sequence. In |
| this case the first element of the sequence is the template source, |
| and the second element is a name for the inline template. It can be |
| useful to give an explicit name to the inline template for debugging |
| purposes. So, you could have written:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign inlineTemplate = [templateSource, "myInlineTemplate"]?interpret></pre></div> |
| |
| <p>as well in the above template. Note that giving the inline |
| template a name has no immediate effect - it is only useful as an |
| extra bit of information if you get an error report.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_isType">is_...</h5> |
| |
| |
| |
| |
| |
| |
| <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>date (all types: date-only, time-only and 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</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_hash</code></td> |
| |
| |
| <td>hash</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_hash_ex</code></td> |
| |
| |
| <td>extended hash (i.e. 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</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_collection</code></td> |
| |
| |
| <td>collection</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</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>)</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">is_node</code></td> |
| |
| |
| <td>node</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_namespace">namespace</h5> |
| |
| |
| |
| |
| <p>This built-in returns the namespace (i.e. the ``gate'' hash to |
| the namespace) associated with a macro variable. You can use it with |
| macros only.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="ref_builtin_new">new</h5> |
| |
| |
| |
| |
| |
| |
| <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-wrapper"><pre class="code-block code-template"><#-- 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">Programmer's Guide/Miscellaneous/Bean wrapper</a></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="ref_directives">Directive Reference</h3> |
| |
| |
| |
| |
| <p>Alphabetical index of directives:</p> |
| |
| <ul> |
| <li> |
| break: <a href="#ref.directive.switch.break">in |
| switch</a>, <a href="#ref.directive.list.break">in |
| list</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.assign">assign</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.attempt">attempt</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.case">case</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.compress">compress</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.default">default</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.else">else</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.elseif">elseif</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.escape">escape</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.fallback">fallback</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.function">function</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.flush">flush</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.ftl">ftl</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.global">global</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.if">if</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.import">import</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.include">include</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.list">list</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.local">local</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.lt">lt</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.macro">macro</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.nested">nested</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.noescape">noescape</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.noescape">noescape</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.nt">nt</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.attempt">recover</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.recurse">recurse</a> |
| </li> |
| |
| <li> |
| return: <a href="#ref.directive.macro.return">in |
| macro</a>, <a href="#ref.directive.function.return">in |
| function</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.rt">lt</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.setting">setting</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.stop">stop</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.switch">switch</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.t">t</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.userDefined">User-defined |
| directive (<@...>)</a> |
| </li> |
| |
| <li> |
| <a href="#ref.directive.visit">visit</a> |
| </li> |
| </ul> |
| |
| <p>If you don't find a directive here that you have seen in a working |
| template, probably you will find it in: <a href="#ref_deprecated">Deprecated FTL constructs</a></p> |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_if">if, else, elseif</h4> |
| |
| |
| <a name="ref.directive.if"></a> |
| |
| <a name="ref.directive.else"></a> |
| |
| <a name="ref.directive.elseif"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_78">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#if <em class="code-color">condition</em>> |
| <em class="code-color">...</em> |
| <#elseif <em class="code-color">condition2</em>> |
| <em class="code-color">...</em> |
| <#elseif <em class="code-color">condition3</em>> |
| <em class="code-color">...</em> |
| <em class="code-color">...</em> |
| <#else> |
| <em class="code-color">...</em> |
| </#if></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">condition</em></code>, |
| <code class="inline-code"><em class="code-color">condition2</em></code>, |
| ...etc.: Expression evaluates to a boolean value. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_79">Description</h5> |
| |
| |
| <p>You can use <code class="inline-code">if</code>, <code class="inline-code">elseif</code> |
| and <code class="inline-code">else</code> directives to conditionally skip a |
| section of the template. The |
| <code class="inline-code"><em class="code-color">condition</em></code>-s must |
| evaluate to a boolean value, or else an error will abort template |
| processing. The <code class="inline-code">elseif</code>-s and |
| <code class="inline-code">else</code>-s must occur inside <code class="inline-code">if</code> |
| (that is, between the <code class="inline-code">if</code> start-tag and end-tag). |
| The <code class="inline-code">if</code> can contain any number of |
| <code class="inline-code">elseif</code>-s (including 0) and at the end optionally |
| one <code class="inline-code">else</code>. Examples:</p> |
| |
| <p><code class="inline-code">if</code> with 0 <code class="inline-code">elseif</code> and no |
| <code class="inline-code">else</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x == 1> |
| x is 1 |
| </#if></pre></div> |
| |
| <p><code class="inline-code">if</code> with 0 <code class="inline-code">elseif</code> and |
| <code class="inline-code">else</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x == 1> |
| x is 1 |
| <#else> |
| x is not 1 |
| </#if></pre></div> |
| |
| <p><code class="inline-code">if</code> with 2 <code class="inline-code">elseif</code> and no |
| <code class="inline-code">else</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x == 1> |
| x is 1 |
| <#elseif x == 2> |
| x is 2 |
| <#elseif x == 3> |
| x is 3 |
| </#if></pre></div> |
| |
| <p><code class="inline-code">if</code> with 3 <code class="inline-code">elseif</code> and |
| <code class="inline-code">else</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x == 1> |
| x is 1 |
| <#elseif x == 2> |
| x is 2 |
| <#elseif x == 3> |
| x is 3 |
| <#elseif x == 4> |
| x is 4 |
| <#else> |
| x is not 1 nor 2 nor 3 nor 4 |
| </#if></pre></div> |
| |
| <p>To see more about boolean expressions, see: <a href="#dgui_template_exp">Template Author's Guide/The Template/Expressions</a>.</p> |
| |
| <p>You can nest <code class="inline-code">if</code> directives (of |
| course):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#if x == 1> |
| x is 1 |
| <#if y == 1> |
| and y is 1 too |
| <#else> |
| but y is not |
| </#if> |
| <#else> |
| x is not 1 |
| <#if y < 0> |
| and y is less than 0 |
| </#if> |
| </#if></pre></div> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>How to test if x is greater than 1? <code class="inline-code"><#if x > |
| 1></code> will be <em>wrong</em>, as FreeMarker |
| will interpret the first <code class="inline-code">></code> as the end of the |
| tag. Thus, either write <code class="inline-code"><#if (x > 1)></code> |
| or <code class="inline-code"><#if x &gt; 1></code>.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_switch">switch, case, default, break</h4> |
| |
| |
| <a name="ref.directive.switch"></a> |
| |
| <a name="ref.directive.case"></a> |
| |
| <a name="ref.directive.default"></a> |
| |
| <a name="ref.directive.switch.break"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_80">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#switch <em class="code-color">value</em>> |
| <#case <em class="code-color">refValue1</em>> |
| <em class="code-color">...</em> |
| <#break> |
| <#case <em class="code-color">refValue2</em>> |
| <em class="code-color">...</em> |
| <#break> |
| <em class="code-color">...</em> |
| <#case <em class="code-color">refValueN</em>> |
| <em class="code-color">...</em> |
| <#break> |
| <#default> |
| <em class="code-color">...</em> |
| </#switch> |
| </code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>, |
| <code class="inline-code"><em class="code-color">refValue1</em></code>, etc.: |
| Expressions evaluates to scalars of the same type. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_81">Description</h5> |
| |
| |
| <p>The usage of this directive is not recommended, as it is |
| error-prone because of the fall-through behavior. Use <a href="#ref.directive.elseif"><code>elseif</code></a>-s |
| instead unless you want to exploit the fall-through behavior.</p> |
| |
| <p>Switch is used to choose a fragment of template depending on |
| the value of an expression:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#switch being.size> |
| <#case "small"> |
| This will be processed if it is small |
| <#break> |
| <#case "medium"> |
| This will be processed if it is medium |
| <#break> |
| <#case "large"> |
| This will be processed if it is large |
| <#break> |
| <#default> |
| This will be processed if it is neither |
| </#switch></pre></div> |
| |
| <p>Inside the <code class="inline-code">switch</code> must be one or more |
| <code class="inline-code"><#case <em class="code-color">value</em>></code>, |
| and after all such <code class="inline-code">case</code> tags optionally one |
| <code class="inline-code"><#default></code>. When FM reaches the |
| <code class="inline-code">switch</code> directive, it chooses a |
| <code class="inline-code">case</code> directive where |
| <code class="inline-code"><em class="code-color">refValue</em></code> equals with |
| <code class="inline-code"><em class="code-color">value</em></code> and continues |
| the processing of the template there. If there is no |
| <code class="inline-code">case</code> directive with appropriate value then it |
| continues processing at the <code class="inline-code">default</code> directive if |
| that exists, otherwise it continues the processing after the end-tag |
| of <code class="inline-code">switch</code>. And now comes the confusing thing: |
| when it has chosen a <code class="inline-code">case</code> directive, it will |
| continue the processing there, and will go ahead until it reaches a |
| <code class="inline-code">break</code> directive. That is, it will not |
| automatically leave the <code class="inline-code">switch</code> directive when it |
| reaches another <code class="inline-code">case</code> directive or the |
| <code class="inline-code"><#default></code> tag. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#switch x> |
| <#case x = 1> |
| 1 |
| <#case x = 2> |
| 2 |
| <#default> |
| d |
| </#switch></pre></div> |
| |
| <p>If <code class="inline-code">x</code> is 1, then it will print 1 2 d; if |
| <code class="inline-code">x</code> is 2 then it will print 2 d; if |
| <code class="inline-code">x</code> is 3 then it will print d. This is the |
| mentioned fall-through behavior. The <code class="inline-code">break</code> tag |
| instructs FM to immediately skip past the <code class="inline-code">switch</code> |
| end-tag.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_list">list, break</h4> |
| |
| |
| <a name="ref.directive.list"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_82">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#list <em class="code-color">sequence</em> as <em class="code-color">item</em>> |
| <em class="code-color">...</em> |
| </#list></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">sequence</em></code>: |
| Expressions evaluates to a sequence or collection |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">item</em></code>: Name |
| of the <a href="#dgui_misc_var">loop variable</a> (not |
| an expression) |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_83">Description</h5> |
| |
| |
| <p>You can use the <code class="inline-code">list</code> directive to process a |
| section of template for each variable contained within a sequence. |
| The code between the start-tag and end-tag will be processed for the |
| 1st subvariable, then for the 2nd subvariable, then for the 3rd |
| subvariable, etc until it passes the last one. For each such |
| iteration the loop variable will contain the current |
| subvariable.</p> |
| |
| <p>There are two special loop variables available inside the list |
| loop:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code"><em class="code-color">item</em>_index</code>: |
| This is a numerical value that contains the index of the current |
| item being stepped over in the loop.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"><em class="code-color">item</em>_has_next</code>: |
| Boolean value that tells if the current item the last in the |
| sequence or not.</p> |
| </li> |
| </ul> |
| |
| <p>Example 1:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign seq = ["winter", "spring", "summer", "autumn"]> |
| <#list seq as x> |
| ${<strong>x_index</strong> + 1}. ${x}<#if <strong>x_has_next</strong>>,</#if> |
| </#list></pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1. winter, |
| 2. spring, |
| 3. summer, |
| 4. autumn</pre></div> |
| |
| <p>Example 2: You can use <code class="inline-code">list</code> to count |
| between two numbers, using a <a href="#dgui_template_exp_direct_seuqence">numerical range sequence |
| expression</a>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x=3> |
| <#list 1..x as i> |
| ${i} |
| </#list></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1 |
| 2 |
| 3 |
| </pre></div> |
| |
| <p>Note that the above example will not work as you may expected |
| if <code class="inline-code">x</code> is 0, as then it will print 0 and -1.</p> |
| |
| <a name="ref.directive.list.break"></a> |
| |
| <p>You can leave the <code class="inline-code">list</code> loop before it |
| passes the last subvariable of the sequence with the |
| <code class="inline-code">break</code> directive. For example this will print |
| ``winter'' and ``spring'' only:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list seq as x> |
| ${x} |
| <#if x = "spring"><strong><#break></strong></#if> |
| </#list></pre></div> |
| |
| <p><span class="marked-for-programmers">Note that if you turn on the |
| classic compatible mode, then the <code class="inline-code">list</code> accepts a |
| scalar as well and treats it as a single-element |
| sequence.</span></p> |
| |
| <p><span class="marked-for-programmers">In general, it is best to avoid |
| using collection that wraps an <code class="inline-code">Iterator</code> as |
| parameters to <code class="inline-code">list</code> and use collection that wraps |
| <code class="inline-code">java.util.Collection</code> or sequence whenever |
| possible. There are situations however, when you only have an |
| <code class="inline-code">Iterator</code> at your disposal. Note that if you pass |
| an collection that wraps an <code class="inline-code">Iterator</code> to the |
| <code class="inline-code">list</code>, you can iterate over its elements only once |
| since <code class="inline-code">Iterator</code>s are by their nature one-off |
| objects. When you try to list a such collection variable for the |
| second time, an error will abort template |
| processing.</span></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_include">include</h4> |
| |
| |
| <a name="ref.directive.include"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_84">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#include <em class="code-color">path</em>></code> |
| or |
| <code class="inline-code"><#include <em class="code-color">path</em> <em class="code-color">options</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">path</em></code>: The |
| path of the file to include; an expression that evaluates to a |
| string. (With other words, it doesn't have to be a fixed string, |
| it can also be something like, for example, |
| <code class="inline-code">profile.baseDir + "/menu.ftl"</code>.) |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">options</em></code>: One |
| or more of these: |
| <code class="inline-code">encoding=<em class="code-color">encoding</em></code>, |
| <code class="inline-code">parse=<em class="code-color">parse</em></code> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">encoding</em></code>: |
| Expression evaluates to string |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">parse</em></code>: |
| Expression evaluates to boolean (also accepts a few string |
| values for backward compatibility) |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_85">Description</h5> |
| |
| |
| <p>You can use it to insert another FreeMarker template file |
| (specified by the <code class="inline-code"><em class="code-color">path</em></code> |
| parameter) into your template. The output from the included template |
| is inserted at the point where the <code class="inline-code">include</code> tag |
| occurs. The included file shares the variables with the including |
| template, similarly like if it was copy-pased into it. The |
| <code class="inline-code">include</code> directive is not replaced by the content |
| of the included file, it just processes the included file each time |
| when FreeMarker reaches the <code class="inline-code">include</code> directive in |
| the course of template processing. So for example if the |
| <code class="inline-code">include</code> is inside a <code class="inline-code">list</code>loop, |
| you can specify different file names in each cycle.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This directive is not be confused with the JSP (Servlet) |
| include, as it doesn't involve the Servlet container at all, just |
| processes another FreeMarker template, without "leaving" |
| FreeMarker. Regarding how to do a "JSP include" <a href="#faq_servlet_include">read this...</a></p> |
| </div> |
| |
| |
| <p>The <code class="inline-code"><em class="code-color">path</em></code> |
| parameter can be a relative path like <code class="inline-code">"foo.ftl"</code> |
| and <code class="inline-code">"../foo.ftl"</code>, or an absolute like |
| <code class="inline-code">"/foo.ftl"</code>. Relative paths are relative to the |
| directory of the template that uses the <code class="inline-code">import</code> |
| directive. Absolute paths are relative to a base (often referred as |
| the ''root directory of the templates'') that the programmer defines |
| when he configures FreeMarker.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This is different than the way it worked prior FreeMarker |
| 2.1, where the path was always absolute. To preserve the old |
| behavior, enable the classic compatible mode in the |
| <code class="inline-code">Configuration</code> object.</p> |
| </div> |
| |
| |
| <p>Always use <code class="inline-code">/</code> (slash) to separate path |
| components, never <code class="inline-code">\</code> (backslash). If you are |
| loading templates from your local file system and it uses |
| backslashes (like under. Windows), FreeMarker will convert them |
| automatically.</p> |
| |
| <p>Example:</p> |
| |
| <p>Assume /common/copyright.ftl contains:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">Copyright 2001-2002 ${me}<br> |
| All rights reserved.</pre></div> |
| |
| <p>Then this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign me = "Juila Smith"> |
| <h1>Some test</h1> |
| <p>Yeah. |
| <hr> |
| <strong><#include "/common/copyright.ftl"></strong></pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><h1>Some test</h1> |
| <p>Yeah. |
| <hr> |
| <strong>Copyright 2001-2002 Juila Smith |
| All rights reserved.</strong></pre></div> |
| |
| <p>The supported |
| <code class="inline-code"><em class="code-color">options</em></code> are:</p> |
| |
| <ul> |
| <li> |
| <p>parse: If it is true, then the included file will be |
| parsed as FTL, otherwise the whole file will be considered as |
| simple text (i.e, no FreeMarker constructs will be searched in |
| it). If you omit this option, then it defaults to true.</p> |
| </li> |
| |
| <li> |
| <p>encoding: The included file inherits the encoding (in |
| practice: the charset) of the including template, unless you |
| specify an encoding with this option. <span class="marked-for-programmers">Encoding names are the same as the ones |
| supported be java.io.InputStreamReader (as of Java API 1.3: |
| MIME-preferred charset names from the IANA Charset |
| Registry).</span> Examples of valid names: ISO-8859-2, UTF-8, |
| Shift_JIS, Big5, EUC-KR, GB2312.</p> |
| </li> |
| </ul> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "/common/navbar.html" parse=false encoding="Shift_JIS"></pre></div> |
| |
| <p><span class="marked-for-programmers">Note, that it is possible to |
| automatically do the commonly used inclusions for all templates, |
| with the "auto includes" setting of |
| <code class="inline-code">Configuration</code>.</span></p> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="ref_directive_include_acquisition">Using acquisition</h6> |
| |
| |
| |
| |
| <p>There's a special path component represented by an asterisk |
| (<code class="inline-code">*</code>). It is interpreted as "this directory or |
| any of its parents". Therefore, if the template located in |
| <code class="inline-code">/foo/bar/template.ftl</code> has the following |
| line:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "*/footer.ftl"></pre></div> |
| |
| <p>then the engine will look for the template in following |
| locations, in this order:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">/foo/bar/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/footer.ftl</code> |
| </li> |
| </ul> |
| |
| <p>This mechanism is called <strong>acquisition</strong> and allows the designers to |
| place commonly included files in a parent directory, and redefine |
| them on a per-subdirectory basis as needed. We say that the |
| including template acquires the template to include from the first |
| parent directory that has it. Note that you can specify not only a |
| template name to the right of the asterisk, but a subpath as well. |
| I.e. if the previous template instead read:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "*/commons/footer.ftl"></pre></div> |
| |
| <p>then the engine would look for the template in following |
| locations, in this order:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">/foo/bar/commons/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/commons/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/commons/footer.ftl</code> |
| </li> |
| </ul> |
| |
| <p>Finally, the asterisk needn't be the first element of the |
| path:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "commons/*/footer.ftl"></pre></div> |
| |
| <p>would cause the engine to look for the template in following |
| locations, in this order:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">/foo/bar/commons/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/bar/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/footer.ftl</code> |
| </li> |
| </ul> |
| |
| <p>However, there can be at most one asterisk in the path. |
| Specifying more than one asterisk will result in a template not |
| being found.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="ref_directive_include_localized">Localized lookup</h6> |
| |
| |
| |
| |
| <p>Whenever a template is loaded, it is assigned a locale. A |
| locale is a language and an optional country or dialect |
| identifier. A template is typically loaded by some code that the |
| programmer wrote and he chooses a locale for the template based on |
| some aspect. For example, when the |
| <code class="inline-code">FreemarkerServlet</code> loads templates, it always |
| requests the template with locale matching the language preference |
| of the browser that requested the web page.</p> |
| |
| <p>Whenever a template is loaded, it is assigned a locale. A |
| locale is a language and an optional country or dialect |
| identifier. A template is typically loaded by some code that the |
| programmer wrote and he chooses a locale for the template based on |
| some aspect. For example, when the |
| <code class="inline-code">FreeMarkerServlet</code> loads templates, it always |
| requests the template with locale matching the language preference |
| of the browser that requested the web page.</p> |
| |
| <p>When a template includes another template, it attempts to |
| load a template with the same locale. Suppose your template was |
| loaded with locale <code class="inline-code">en_US</code>, which means U.S. |
| English. When you include another template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><include "footer.ftl"></pre></div> |
| |
| <p>the engine will in fact look for several templates, in this |
| order:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">footer_en_US.ftl</code>, |
| </li> |
| |
| <li> |
| <code class="inline-code">footer_en.ftl</code>, and finally |
| </li> |
| |
| <li> |
| <code class="inline-code">footer.ftl</code> |
| </li> |
| </ul> |
| |
| <p><span class="marked-for-programmers">Note that you can disable |
| localized lookup feature with the |
| <code class="inline-code">setLocalizedLookup</code> method of |
| <code class="inline-code">Configuration</code>.</span></p> |
| |
| <p>When you use both acquisition and localized template lookup, |
| the template with more specific locale in a parent directory takes |
| precedence over template with less specific locale in a child |
| directory. Suppose you use the following include from |
| <code class="inline-code">/foo/bar/template.ftl</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#include "*/footer.ftl"></pre></div> |
| |
| <p>the engine will look for these templates, in this |
| order:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">/foo/bar/footer_en_US.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/footer_en_US.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/footer_en_US.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/bar/footer_en.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/footer_en.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/footer_en.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/bar/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/foo/footer.ftl</code> |
| </li> |
| |
| <li> |
| <code class="inline-code">/footer.ftl</code> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_import">import</h4> |
| |
| |
| <a name="ref.directive.import"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_86">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#import <em class="code-color">path</em> as <em class="code-color">hash</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">path</em></code>: The |
| path of a template. This is an expression that evaluates to a |
| string. (With other words, it doesn't have to be a fixed string, |
| it can also be something like, for example, |
| <code class="inline-code">profile.baseDir + "/menu.ftl"</code>.) |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">hash</em></code>: The |
| unquoted name of hash variable by which you can access the |
| namespace. Not an expression. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_87">Description</h5> |
| |
| |
| <p>Imports a library. That is, it creates a new empty namespace, |
| and then executes the template given with |
| <code class="inline-code"><em class="code-color">path</em></code> parameter in that |
| namespace so the template populates the namespace with variables |
| (macros, functions, ...etc.). Then it makes the newly created |
| namespace available to the caller with a hash variable. The hash |
| variable will be created as a plain variable in the namespace used |
| by the caller of <code class="inline-code">import</code> (as if you would create |
| it with <code class="inline-code">assign</code> directive), with the name given |
| with the <code class="inline-code"><em class="code-color">hash</em></code> |
| parameter.</p> |
| |
| <p>If you call <code class="inline-code">import</code> with the same |
| <code class="inline-code"><em class="code-color">path</em></code> for multiple |
| times, it will create the namespace and run the template for the |
| very first call of <code class="inline-code">import</code> only. The later calls |
| will just create a hash by which you can access the |
| <em>same</em> namespace.</p> |
| |
| <p>The output printed by the imported template will be ignored |
| (will not be inserted at the place of importing). The template is |
| executed to populate the namespace with variables, and not to write |
| to the output.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/libs/mylib.ftl" as my> |
| |
| <@my.copyright date="1999-2002"/></pre></div> |
| |
| <p>The <code class="inline-code"><em class="code-color">path</em></code> |
| parameter can be a relative path like <code class="inline-code">"foo.ftl"</code> |
| and <code class="inline-code">"../foo.ftl"</code>, or an absolute like |
| <code class="inline-code">"/foo.ftl"</code>. Relative paths are relative to the |
| directory of the template that uses the <code class="inline-code">import</code> |
| directive. Absolute paths are relative to a base (often referred as |
| the ''root directory of the templates'') that the programmer defines |
| when he configures FreeMarker.</p> |
| |
| <p>Always use <code class="inline-code">/</code> (slash) to separate path |
| components, never <code class="inline-code">\</code> (backslash). If you are |
| loading templates from your local file system and it uses |
| backslashes (like under. Windows), FreeMarker will convert them |
| automatically.</p> |
| |
| <p>Like with the <code class="inline-code">include</code> directive, <a href="#ref_directive_include_acquisition">acquisition</a> and |
| <a href="#ref_directive_include_localized">localized |
| lookup</a> may be used for resolving the path.</p> |
| |
| <p><span class="marked-for-programmers">Note, that it is possible to |
| automatically do the commonly used imports for all templates, with |
| the "auto imports" setting of |
| <code class="inline-code">Configuration</code>.</span></p> |
| |
| <p>If you are new to namespaces, you should read: <a href="#dgui_misc_namespace">Template Author's Guide/Miscellaneous/Namespaces</a></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_noparse">noparse</h4> |
| |
| |
| <a name="ref.directive.noparse"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_88">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#noparse> |
| <em class="code-color">...</em> |
| </#noparse></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_89">Description</h5> |
| |
| |
| <p>FreeMarker will not search FTL tags and interpolations and |
| other special character sequences in the body of this directive, |
| except the noparse end-tag.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">Example: |
| -------- |
| |
| <strong><#noparse></strong> |
| <#list animals as being> |
| <tr><td>${being.name}<td>${being.price} Euros |
| </#list> |
| <strong></#noparse></strong></pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Example: |
| -------- |
| |
| <#list animals as being> |
| <tr><td>${being.name}<td>${being.price} Euros |
| </#list> |
| </pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_compress">compress</h4> |
| |
| |
| <a name="ref.directive.compress"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_90">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#compress> |
| <em class="code-color">...</em> |
| </#compress></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_91">Description</h5> |
| |
| |
| <p>The compress directive is useful for removing superfluous |
| <a href="#gloss.whiteSpace">white-space</a> when you use a |
| white-space insensitive format (e.g. HTML or XML). It captures the |
| output generated inside its body (i.e. between its start-tag and |
| end-tag), and reduces all unbroken white-space sequences to a single |
| white-space character. The inserted character will be a <a href="#gloss.lineBreak">line break</a> if the replaced sequence |
| contains line breaks, or a space otherwise. The very first and very |
| last unbroken white-space sequences will be completely |
| removed.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = " moo \n\n "> |
| (<#compress> |
| 1 2 3 4 5 |
| ${moo} |
| test only |
| |
| I said, test only |
| |
| </#compress>)</pre></div> |
| |
| <p>will output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">(1 2 3 4 5 |
| moo |
| test only |
| I said, test only)</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_escape">escape, noescape</h4> |
| |
| |
| <a name="ref.directive.escape"></a> |
| |
| <a name="ref.directive.noescape"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_92">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#escape <em class="code-color">identifier</em> as <em class="code-color">expression</em>> |
| <em class="code-color">...</em> |
| <#noescape>...</#noescape> |
| <em class="code-color">...</em> |
| </#escape></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_93">Description</h5> |
| |
| |
| <p>When you surround a part of the template with an escape |
| directive, interpolations |
| (<code class="inline-code">${<em class="code-color">...</em>}</code>) that occur |
| inside the block are combined with the escaping expression |
| automatically. This is a convenience method for avoiding writing |
| similar expressions all over. It does not affect interpolations in |
| string literals (as in <code class="inline-code"><#assign x = |
| "Hello ${user}!"></code>). Also, it does not affect numerical |
| interpolations |
| (<code class="inline-code">#{<em class="code-color">...</em>}</code>).</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#escape x as x?html></strong> |
| First name: ${firstName} |
| Last name: ${lastName} |
| Maiden name: ${maidenName} |
| <strong></#escape></strong></pre></div> |
| |
| <p>is actually equivalent to:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> First name: ${firstName<strong>?html</strong>} |
| Last name: ${lastName<strong>?html</strong>} |
| Maiden name: ${maidenName<strong>?html</strong>}</pre></div> |
| |
| <p>Note that it is irrelevant what identifier you use in the |
| directive - it just serves as a formal parameter to the escaping |
| expression.</p> |
| |
| <p>When you are calling macros or the <code class="inline-code">include</code> |
| directive, it is important to understand that escape has effect only |
| on interpolations that occur between the <code class="inline-code"><#escape |
| <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#escape></code> <em>in the template |
| text</em>. That is, it will not escape anything that is before |
| <code class="inline-code"><#escape <em class="code-color">...</em>></code> in |
| the text, or after the <code class="inline-code"></#escape></code> in the |
| text, not even if that part is called from inside the |
| <code class="inline-code">escape</code>-d section.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x = "<test>"> |
| <#macro m1> |
| m1: ${x} |
| </#macro> |
| <#escape x as x?html> |
| <#macro m2>m2: ${x}</#macro> |
| ${x} |
| <@m1/> |
| </#escape> |
| ${x} |
| <@m2/></pre></div> |
| |
| <p>the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> &lt;test&gt; |
| m1: <test> |
| <test> |
| m2: &lt;test&gt;</pre></div> |
| |
| <p><span class="marked-for-programmers">More technically, the effects of |
| <code class="inline-code">escape</code> directive are applied at template parsing |
| time rather than at template processing time. This means that if you |
| call a macro or include another template from within an escape |
| block, it won't affect the interpolations in the macro/included |
| template, since macro calls and template includes are evaluated at |
| template processing time. On the other hand, if you surround one or |
| more macro declarations (which are evaluated at template parsing |
| time, as opposed to macro calls) with an escape block, the |
| interpolations in those macros will be combined with the escaping |
| expression.</span></p> |
| |
| <p>Sometimes there is a need to temporarily turn off escaping for |
| one or two interpolations in an escape block. You can achieve this |
| by closing and later reopening the escape block, but then you have |
| to write the escaping expression twice. You can instead use the |
| noescape directive:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#escape x as x?html> |
| From: ${mailMessage.From} |
| Subject: ${mailMessage.Subject} |
| <strong><#noescape></strong>Message: ${mailMessage.htmlFormattedBody}<strong></#noescape></strong> |
| <em>...</em> |
| </#escape></pre></div> |
| |
| <p>is equivalent to:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> From: ${mailMessage.From?html} |
| Subject: ${mailMessage.Subject?html} |
| Message: ${mailMessage.htmlFormattedBody} |
| ...</pre></div> |
| |
| <p>Escapes can be nested (although you will do it only in rare |
| circumstances). Therefore, you can write something like the below |
| code (the example is admittedly a bit stretched, as you'd probably |
| place item codes in a sequence and use <code class="inline-code">list</code> to |
| iterate over them, but we're now doing it this way just to |
| illustrate the point):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#escape x as x?html></strong> |
| Customer Name: ${customerName} |
| Items to ship: |
| <strong><#escape x as itemCodeToNameMap[x]></strong> |
| ${itemCode1} |
| ${itemCode2} |
| ${itemCode3} |
| ${itemCode4} |
| <strong></#escape></strong> |
| <strong></#escape></strong></pre></div> |
| |
| <p>is actually equivalent to:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> Customer Name: ${customerName?html} |
| Items to ship: |
| ${itemCodeToNameMap[itemCode1]?html} |
| ${itemCodeToNameMap[itemCode2]?html} |
| ${itemCodeToNameMap[itemCode3]?html} |
| ${itemCodeToNameMap[itemCode4]?html}</pre></div> |
| |
| <p>When you use the noescape directive in a nested escape block, |
| it undoes only a single level of escaping. Therefore, to completely |
| turn off escaping in a two-level deep escaped block, you need to use |
| two nested noescape directives as well.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_assign">assign</h4> |
| |
| |
| <a name="ref.directive.assign"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_94">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#assign <em class="code-color">name</em>=<em class="code-color">value</em>></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">name1</em>=<em class="code-color">value1</em> <em class="code-color">name2</em>=<em class="code-color">value2</em> <em class="code-color">... nameN</em>=<em class="code-color">valueN</em>></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">same as above...</em> in <em class="code-color">namespacehash</em>></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">name</em>> |
| <em class="code-color">capture this</em> |
| </#assign></code> |
| or |
| <code class="inline-code"><#assign <em class="code-color">name</em> in <em class="code-color">namespacehash</em>> |
| <em class="code-color">capture this</em> |
| </#assign></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of the variable. It is not expression. However, it can be |
| written as a string literal, which is useful if the variable |
| name contains reserved characters, for example |
| <code class="inline-code"><#assign "foo-bar" = 1></code>. Note that this |
| string literal does not expand interpolations (as |
| <code class="inline-code">"${foo}"</code>). |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>: the |
| value to store. Expression. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">namespacehash</em></code>: |
| a hash that was created for a namespace (by <a href="#ref.directive.import"><code>import</code></a>). |
| Expression. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_95">Description</h5> |
| |
| |
| <p>With this you can create a new variable, or replace an |
| existing variable. Note that only top-level variables can be |
| created/replaced (i.e. you can't create/replace |
| <code class="inline-code">some_hash.subvar</code>, but |
| <code class="inline-code">some_hash</code>).</p> |
| |
| <p>For more information about variables, read this: <a href="#dgui_misc_var">Template Author's Guide/Miscellaneous/Defining variables in the template</a></p> |
| |
| <p>Example: variable <code class="inline-code">seasons</code> will store a |
| sequence:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign seasons = ["winter", "spring", "summer", "autumn"]></pre></div> |
| |
| <p>Example: Increments the numerical value stored in variable |
| <code class="inline-code">test</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign test = test + 1></pre></div> |
| |
| <p>As a convenience feature, you can do more assignments with one |
| <code class="inline-code">assign</code> tag. For example this will do the same as |
| the two previous examples:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign |
| seasons = ["winter", "spring", "summer", "autumn"] |
| test = test + 1 |
| ></pre></div> |
| |
| <p>If you know what namespaces are: <code class="inline-code">assign</code> |
| directive creates variables in namespaces. Normally it creates the |
| variable in the current namespace (i.e. in the namespace associated |
| with the template where the tag is). However, if you use <code class="inline-code">in |
| <em class="code-color">namespacehash</em></code> then you can |
| create/replace a variable of another <a href="#dgui_misc_namespace">namespace</a> than the current |
| namespace. For example, here you create/replace variable |
| <code class="inline-code">bgColor</code> of the namespace used for |
| <code class="inline-code">/mylib.ftl</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/mylib.ftl" as my> |
| <#assign bgColor="red" in my></pre></div> |
| |
| <p>An extreme usage of <code class="inline-code">assign</code> is when it |
| captures the output generated between its start-tag and end-tag. |
| That is, things that are printed between the tags will not be shown |
| on the page, but will be stored in the variable. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro myMacro>foo</#macro> |
| <#assign x> |
| <#list 1..3 as n> |
| ${n} <@myMacro /> |
| </#list> |
| </#assign> |
| Number of words: ${x?word_list?size} |
| ${x}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Number of words: 6 |
| 1 foo |
| 2 foo |
| 3 foo |
| </pre></div> |
| |
| <p>Please note that you should not to use this to insert |
| variables into strings:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x>Hello ${user}!</#assign> <#-- BAD PRACTICE! --></pre></div> |
| |
| <p>You should simply write:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign x="Hello ${user}!"></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_global">global</h4> |
| |
| |
| <a name="ref.directive.global"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_96">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#global <em class="code-color">name</em>=<em class="code-color">value</em>></code> |
| or |
| <code class="inline-code"><#global <em class="code-color">name1</em>=<em class="code-color">value1</em> <em class="code-color">name2</em>=<em class="code-color">value2</em> <em class="code-color">... nameN</em>=<em class="code-color">valueN</em>></code> |
| or |
| <code class="inline-code"><#global <em class="code-color">name</em>> |
| <em class="code-color">capture this</em> |
| </#global></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of the variable. It is not expression. However, it can be |
| written as a string literal, which is useful if the variable |
| name contains reserved characters, for example |
| <code class="inline-code"><#global "foo-bar" = 1></code>. Note that this |
| string literal does not expand interpolations (as |
| <code class="inline-code">"${foo}"</code>). |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>: the |
| value to store. Expression. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_97">Description</h5> |
| |
| |
| <p>This directive is similar to <a href="#ref.directive.assign"><code>assign</code></a>, but |
| the variable created will be visible in all <a href="#dgui_misc_namespace">namespaces</a>, and will not be |
| inside any namespace. Exactly as if you would create (or replace) a |
| variable of the data-model. Hence, the variable is global. If a |
| variable with the same name already exists in the data-model, it |
| will be hidden by the variable created with this directive. If a |
| variable with the same name already exists in the current namespace, |
| that will hide the variable created with <code class="inline-code">global</code> |
| directive.</p> |
| |
| <p>For example, with <code class="inline-code"><#global x = 1></code> you |
| create a variable that is visible as <code class="inline-code">x</code> in all |
| namespaces, unless another variable called <code class="inline-code">x</code> |
| hides it (for example a variable what you have created as |
| <code class="inline-code"><#assign x = 2></code>). In this case, you can use |
| <a href="#dgui_template_exp_var_special">special |
| variable</a> <code class="inline-code">globals</code>, like |
| <code class="inline-code">${.globals.x}</code>. Note that with |
| <code class="inline-code">globals</code> you see all globally accessible |
| variables; not only the variables that were created with |
| <code class="inline-code">global</code> directive, but also the variables of the |
| data-model.</p> |
| |
| <p>Note for custom JSP tag users: The set of variables created |
| with this directive corresponds to the JSP page-scope. This means, |
| that if a custom JSP tag wants to get a page-scope attribute |
| (page-scope bean), a variable with the same name in the current |
| namespace will not hide it from the viewpoint of the JSP tag.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_local">local</h4> |
| |
| |
| <a name="ref.directive.local"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_98">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#local <em class="code-color">name</em>=<em class="code-color">value</em>></code> |
| or |
| <code class="inline-code"><#local <em class="code-color">name1</em>=<em class="code-color">value1</em> <em class="code-color">name2</em>=<em class="code-color">value2</em> <em class="code-color">... nameN</em>=<em class="code-color">valueN</em>></code> |
| or |
| <code class="inline-code"><#local <em class="code-color">name</em>> |
| <em class="code-color">capture this</em> |
| </#local> |
| </code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: the |
| name of the local object in the root. It is not an expression. |
| However, it can be written as a string literal, which is useful |
| if the variable name contains reserved characters, for example |
| <code class="inline-code"><#local "foo-bar" = 1></code>. Note that this |
| string literal does not expand interpolations (as |
| <code class="inline-code">"${foo}"</code>). |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>: the |
| value to store. Expression. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_99">Description</h5> |
| |
| |
| <p>It is similar to <a href="#ref.directive.assign">assign |
| directive</a>, but it creates or replaces local variables. This |
| only works inside macro definitions and function definitons.</p> |
| |
| <p>For more information about variables, read this: <a href="#dgui_misc_var">Template Author's Guide/Miscellaneous/Defining variables in the template</a></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_setting">setting</h4> |
| |
| |
| <a name="ref.directive.setting"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_100">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#setting <em class="code-color">name</em>=<em class="code-color">value</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of the setting. It is not expression! |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value</em></code>: New |
| value of the setting. Expression |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_101">Description</h5> |
| |
| |
| <p>Sets a setting for the further part of processing. Settings |
| are values that influence the behavior of FreeMarker. The new value |
| will be present only in the template processing where it was set, |
| and does not touch the template itself. The initial value of |
| settings is set by the programmer <span class="marked-for-programmers">(see: <a href="#pgui_config_settings">Programmer's Guide/The Configuration/Settings</a>)</span>.</p> |
| |
| <p>The supported settings are:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">locale</code>: The locale (language) |
| of the output. It can influence the presentation format of |
| numbers, dates, etc. The value is a string which consist of a |
| language code (lowercase two-letter ISO-639 code) plus optional |
| county code (uppercase two-letter ISO-3166 code) separated from |
| the language code with underscore, and if we have specified the |
| country then an optional variant code (not standardized) |
| separated from the country with underscore. Examples of valid |
| values: <code class="inline-code">en</code>, <code class="inline-code">en_US</code>, |
| <code class="inline-code">en_US_MAC</code>. FreeMarker will try to use the |
| most specific available locale, so if you specify |
| <code class="inline-code">en_US_MAC</code> but that is not known, then it will |
| try <code class="inline-code">en_US</code>, and then <code class="inline-code">en</code>, |
| and then the default locale of the computer (which is may set by |
| the programmer).</p> |
| </li> |
| |
| <li> |
| <p><a name="ref.setting.number_format"></a><code class="inline-code">number_format</code>: The number |
| format that is used to convert numbers to strings when no |
| explicit format is specified. Can be one of predefined values |
| <code class="inline-code">number</code> (the default), |
| <code class="inline-code">computer</code>, <code class="inline-code">currency</code>, or |
| <code class="inline-code">percent</code>. Additionally, arbitrary format |
| pattern written in <a href="http://java.sun.com/j2se/1.4/docs/api/java/text/DecimalFormat.html">Java |
| decimal number format syntax</a> can also be specified. More |
| information about format patterns:<a href="#ref_builtin_string_for_number"><code>string</code> |
| built-in</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">boolean_format</code>: The |
| comma-separated pair of strings for representing true and false |
| values respectively that is used to convert booleans to strings |
| when no explicit format is specified. Default value is |
| <code class="inline-code">"true,false"</code>. See also:<a href="#ref_builtin_string_for_boolean"><code>string</code> |
| built-in</a>.</p> |
| </li> |
| |
| <li> |
| <p> <code class="inline-code">date_format</code>, |
| <code class="inline-code">time_format</code>, |
| <code class="inline-code">datetime_format</code>: The date/time format used to |
| convert dates to strings when no explicit format is specified, |
| as in the case of <code class="inline-code">${someDate}</code>. |
| <code class="inline-code">date_format</code> affects only the formatting of |
| date-only dates (year, month, day), |
| <code class="inline-code">time_format</code> affects only the formatting of |
| time-only dates (hour,minute, second, millisecond), |
| <code class="inline-code">datetime_format</code> affects only the formatting |
| of date-time dates (year, month, day, hour, minute, second, |
| millisecond). The possible values of the settings are similar to |
| the parameters of <a href="#ref_builtin_string_for_date"><code>string</code> |
| built-in</a> of dates; see more explanation there. Examples: |
| <code class="inline-code">"short"</code>, <code class="inline-code">"long_medium"</code>, |
| <code class="inline-code">"MM/dd/yyyy"</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">time_zone</code>: The name of the time |
| zone used to format times for display. By default, the system |
| time zone is used. Can be any value that is accepted by <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/TimeZone.html">Java |
| TimeZone API</a>. Examples: <code class="inline-code">"GMT"</code>, |
| <code class="inline-code">"GMT+2"</code>, <code class="inline-code">"GMT-1:30"</code>, |
| <code class="inline-code">"CET"</code>, <code class="inline-code">"PST"</code>, |
| <code class="inline-code">"America/Los_Angeles"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">url_escaping_charset</code>: The |
| charset used for URL escaping (e.g. for |
| <code class="inline-code">${foo?url}</code>) to calculate the escaped |
| (<code class="inline-code">%<em class="code-color">XX</em></code>) parts. |
| Usually the framework that encloses FreeMarker should set it, so |
| you hardly ever should set this setting in templates. <span class="marked-for-programmers">(Programmers can read more about this |
| <a href="#pgui_misc_charset">here...</a>)</span></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">classic_compatible</code>: This is for |
| experts. Its value should be a boolean. See the documentation of |
| <code class="inline-code">freemarker.template.Configurable</code> for more |
| information.</p> |
| </li> |
| </ul> |
| |
| <p>Example: Assume that the initial locale of template is hu |
| (Hungarian). Then this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">${1.2} |
| <#setting locale="en_US"> |
| ${1.2}</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">1,2 |
| 1.2</pre></div> |
| |
| <p>because Hungarian people use the comma as their decimal |
| separator, while US people use the dot.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_userDefined">User-defined directive (<@...>)</h4> |
| |
| |
| <a name="ref.directive.userDefined"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_102">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><@<em class="code-color">user_def_dir_exp</em> <em class="code-color">param1</em>=<em class="code-color">val1</em> <em class="code-color">param2</em>=<em class="code-color">val2</em> <em class="code-color">...</em> <em class="code-color">paramN</em>=<em class="code-color">valN</em>/></code> |
| (Note the XML-style <code class="inline-code">/</code> before the <code class="inline-code">></code>) |
| or if you need loop variables (<a href="#ref_directive_userDefined_loopVar">more details...</a>) |
| <code class="inline-code"><@<em class="code-color">user_def_dir_exp</em> <em class="code-color">param1</em>=<em class="code-color">val1</em> <em class="code-color">param2</em>=<em class="code-color">val2</em> <em class="code-color">...</em> <em class="code-color">paramN</em>=<em class="code-color">valN</em> ; <em class="code-color">lv1</em>, <em class="code-color">lv2</em>, <em class="code-color">...</em>, <em class="code-color">lvN</em>/></code> |
| |
| Or the same as the above two but with end-tag (<a href="#ref_directive_userDefined_entTag">more details...</a>): |
| |
| <code class="inline-code"><@<em class="code-color">user_def_dir_exp</em> <em class="code-color">...</em>> |
| ... |
| </@<em class="code-color">user_def_dir_exp</em>></code> |
| or |
| <code class="inline-code"><@<em class="code-color">user_def_dir_exp</em> <em class="code-color">...</em>> |
| ... |
| </@></code> |
| |
| Or all above but with positional parameter passing (<a href="#ref_directive_userDefined_positionalParam">more details...</a>): |
| |
| <code class="inline-code"><@<em class="code-color">user</em> <em class="code-color">val1</em>, <em class="code-color">val2</em>, <em class="code-color">...</em>, <em class="code-color">valN</em>/></code> |
| ...etc. |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">user_def_dir_exp</em></code>: |
| Expression evaluates to an user-defined directive (for example a |
| macro), that will be called. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">param1</em></code>, |
| <code class="inline-code"><em class="code-color">param2</em></code>, ...etc.: |
| The name of parameters. They are <em>not</em> |
| expressions. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">val1</em></code>, |
| <code class="inline-code"><em class="code-color">val2</em></code>, ...etc.: The |
| value of parameters. They <em>are</em> |
| expressions. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">lv1</em></code>, |
| <code class="inline-code"><em class="code-color">lv2</em></code>, ...etc.: The |
| name of <a href="#dgui_misc_var">loop variables</a>. |
| They are <em>not</em> expressions. |
| </li> |
| </ul> |
| |
| <p>The number of parameters can be 0 (i.e. no parameters).</p> |
| |
| <p>The order of parameters is not significant (unless you use |
| positional parameter passing). The name of parameters must be |
| unique. Lower- and uppercase letters are considered as different |
| letters in parameter names (i.e. <code class="inline-code">Color</code> and |
| <code class="inline-code">color</code> is not the same).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_103">Description</h5> |
| |
| |
| <p>This will call an user-defined directive, for example a macro. |
| The meaning of parameters, and the set of supported and required |
| parameters depend on the concrete user-defined directive.</p> |
| |
| <p>You may read <a href="#dgui_misc_userdefdir">the tutorial |
| about user-defined directives</a>.</p> |
| |
| <p>Example 1: Calls the directive that is stored in the variable |
| <code class="inline-code">html_escape</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@html_escape> |
| a < b |
| Romeo & Juliet |
| </@html_escape></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> a &lt; b |
| Romeo &amp; Juliet</pre></div> |
| |
| <p>Example 2: Calls a macro with parameters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@list items=["mouse", "elephant", "python"] title="Animals"/> |
| <em>...</em> |
| <#macro list title items> |
| <p>${title?cap_first}: |
| <ul> |
| <#list items as x> |
| <li>${x?cap_first} |
| </#list> |
| </ul> |
| </#macro></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>Animals: |
| <ul> |
| <li>Mouse |
| <li>Elephant |
| <li>Python |
| </ul> |
| |
| <em>...</em></pre></div> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="ref_directive_userDefined_entTag">End-tag</h6> |
| |
| |
| <p>You can omit the |
| <code class="inline-code"><em class="code-color">user_def_dir_exp</em></code> in |
| the <a href="#gloss.endTag">end-tag</a>. That is, you can |
| always write <code class="inline-code"></@></code> instead of |
| <code class="inline-code"></@<em class="code-color">anything</em>></code>. |
| This rule is mostly useful when the |
| <code class="inline-code"><em class="code-color">user_def_dir_exp</em></code> |
| expression is too complex, because you don't have to repeat the |
| expression in the end-tag. Furthermore, if the expression contains |
| other than simple variable names and dots, you are not allowed to |
| repeat the expression. For example, |
| <code class="inline-code"><@a_hash[a_method()]><em class="code-color">...</em></@a_hash[a_method()]></code> |
| is an error; you must write |
| <code class="inline-code"><@a_hash[a_method()]><em class="code-color">...</em></@></code>. |
| But |
| <code class="inline-code"><@a_hash.foo><em class="code-color">...</em></@a_hash.foo></code> |
| is OK.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="ref_directive_userDefined_loopVar">Loop variables</h6> |
| |
| |
| <p>Some user-defined directives create loop variables |
| (similarly to <code class="inline-code">list</code> directive). As with the |
| predefined directives (as <code class="inline-code">list</code>) the |
| <em>name</em> of loop variables is given when you call |
| the directive (as <code class="inline-code">foo</code> in <code class="inline-code"><#list |
| foos as |
| foo><em class="code-color">...</em></#list></code>), |
| while the <em>value</em> of the variable is set by the |
| directive itself. In the case of user-defined directives the |
| syntax is that the name of loop variables is given after a |
| semicolon. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@myRepeatMacro count=4 ; <strong>x, last</strong>> |
| ${<strong>x</strong>}. Something... <#if <strong>last</strong>> This was the last!</#if> |
| </@myRepeatMacro></pre></div> |
| |
| <p>Note that the number of loop variable created by the |
| user-defined directive and the number of loop variables specified |
| after the semicolon need not match. Say, if you are not interested |
| if the repetition is the last, you can simply write:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@myRepeatMacro count=4 ; <strong>x</strong>> |
| ${<strong>x</strong>}. Something... |
| </@myRepeatMacro></pre></div> |
| |
| <p>or you can even:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@myRepeatMacro count=4> |
| Something... |
| </@myRepeatMacro></pre></div> |
| |
| <p>Furthermore, it does not cause error if you specify more |
| loop variables after the semicolon than the user-defined directive |
| creates, just the last few loop variables will not be created |
| (i.e. those will be undefined in the nested content). Trying to |
| use the undefined loop variables, however, will cause error |
| (unless you use built-ins like <code class="inline-code">?default</code>), since |
| you try to access a non-existing variable.</p> |
| |
| <p>See the <a href="#dgui_misc_userdefdir">the tutorial |
| about user-defined directives</a> for more explanation.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="ref_directive_userDefined_positionalParam">Positional parameter passing</h6> |
| |
| |
| |
| |
| <p>Positional parameter passing (as <code class="inline-code"><@heading |
| "Preface", 1/></code>) is a shorthand form of normal named |
| parameter passing (as <code class="inline-code"><@heading title="Preface" |
| level=1/></code>), where you omit the parameter name. This |
| shorthand form should be used if a user-defined directive has only |
| one parameter, or if it is easy to remember the order of |
| parameters for a frequently used user-defined directive. To use |
| this form, you have to know the order in which the named |
| parameters are declared (trivial if the directive has only one |
| parameter). Say, if <code class="inline-code">heading</code> was created as |
| <code class="inline-code"><#macro heading title |
| level><em class="code-color">...</em></code>, then |
| <code class="inline-code"><@heading "Preface", 1/></code> is equivalent |
| with <code class="inline-code"><@heading title="Preface" level=1/></code> |
| (or <code class="inline-code"><@heading level=1 title="Preface"/></code>; |
| if you use parameter names, the order is not important). Note that |
| positional parameter passing is currently only supported for |
| macros.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_macro">macro, nested, return</h4> |
| |
| |
| <a name="ref.directive.macro"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_104">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#macro <em class="code-color">name</em> <em class="code-color">param1</em> <em class="code-color">param2</em> <em class="code-color">... paramN</em>> |
| <em class="code-color">...</em> |
| <#nested <em class="code-color">loopvar1</em>, <em class="code-color">loopvar2</em>, <em class="code-color">...</em>, <em class="code-color">loopvarN</em>> |
| <em class="code-color">...</em> |
| <#return> |
| <em class="code-color">...</em> |
| </#macro></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of macro variable. It's not an expression. However, it can be |
| written as a string literal, which is useful if the macro name |
| contains reserved characters, for example <code class="inline-code"><#macro |
| "foo-bar"><em class="code-color">...</em></code>. Note that |
| this string literal does not expand interpolations (as |
| <code class="inline-code">"${foo}"</code>). |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">param1</em></code>, |
| <code class="inline-code"><em class="code-color">param2</em></code>, ...etc.: |
| the name of the <a href="#dgui_misc_var">local |
| variables</a> store the parameter values (not expression), |
| optionally followed by <code class="inline-code">=</code> and the default |
| value (that's an expression). The default value can even be |
| another parameter, for example <code class="inline-code"><#macro section title |
| label=title></code>. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">paramN</em></code>, the |
| last parameter, may optionally include a trailing ellipsis |
| (<code class="inline-code">...</code>), which indicates the macro takes a |
| variable number of parameters. If called using named parameters, |
| <code class="inline-code"><em class="code-color">paramN</em></code> will be a |
| hash containing all of the undeclared key/value pairs passed to |
| the macro. If called using positional parameters, |
| <code class="inline-code"><em class="code-color">paramN</em></code> will be a |
| sequence of the extra parameters. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">loopvar1</em></code>, |
| <code class="inline-code"><em class="code-color">loopvar2</em></code>, ...etc.: |
| Optional. The values of <a href="#dgui_misc_var">loop |
| variables</a> that the <code class="inline-code">nested</code> directive |
| wants to create for the nested content. These are |
| expressions. |
| </li> |
| </ul> |
| |
| <p>The <code class="inline-code">return</code> and <code class="inline-code">nested</code> |
| directives are optional and can be used anywhere and for any times |
| between the <code class="inline-code"><#macro |
| <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#macro></code>.</p> |
| |
| <p>Parameters without default value must precede parameters with |
| default value |
| (<code class="inline-code"><em class="code-color">paramName</em>=<em class="code-color">defaultValue</em></code>).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_105">Description</h5> |
| |
| |
| <p>Creates a macro variable (in the current namespace, if you |
| know namespace feature). If you are new to macros and user-defined |
| directives you should read the <a href="#dgui_misc_userdefdir">the tutorial about user-defined |
| directives</a>.</p> |
| |
| <p>Macro variable stores a template fragment (called macro |
| definition body) that can be used as <a href="#ref.directive.userDefined">user-defined directive</a>. |
| The variable also stores the name of allowed parameters to the |
| user-defined directive. You must give value for all of those |
| parameters when you use the variable as directive, except for |
| parameters that has a default value. The default value will be used |
| if and only if you don't give value for the parameter when you call |
| the macro.</p> |
| |
| <p>The variable will be created at the beginning of the template; |
| it does not mater where the <code class="inline-code">macro</code> directive is |
| placed in the template. Thus, this will work:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- call the macro; the macro variable is already created: --> |
| <@test/> |
| ... |
| |
| <#-- create the macro variable: --> |
| <#macro test> |
| Test text |
| </#macro></pre></div> |
| |
| <p>However, if the macro definitions are inserted with |
| <code class="inline-code">include</code> directive, they will not be available |
| until FreeMarker has executed the <code class="inline-code">include</code> |
| directive.</p> |
| |
| <p>Example: Macro without parameters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test> |
| Test text |
| </#macro> |
| <#-- call the macro: --> |
| <@test/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Test text |
| </pre></div> |
| |
| <p>Example: Macro with parameters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test foo bar baaz> |
| Test text, and the params: ${foo}, ${bar}, ${baaz} |
| </#macro> |
| <#-- call the macro: --> |
| <@test foo="a" bar="b" baaz=5*5-2/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Test text, and the params: a, b, 23 |
| </pre></div> |
| |
| <p>Example: Macro with parameters and default parameter |
| values:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test foo bar="Bar" baaz=-1> |
| Test text, and the params: ${foo}, ${bar}, ${baaz} |
| </#macro> |
| <@test foo="a" bar="b" baaz=5*5-2/> |
| <@test foo="a" bar="b"/> |
| <@test foo="a" baaz=5*5-2/> |
| <@test foo="a"/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Test text, and the params: a, b, 23 |
| Test text, and the params: a, b, -1 |
| Test text, and the params: a, Bar, 23 |
| Test text, and the params: a, Bar, -1 |
| </pre></div> |
| |
| <p>Example: A more complex macro.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro list title items> |
| <p>${title?cap_first}: |
| <ul> |
| <#list items as x> |
| <li>${x?cap_first} |
| </#list> |
| </ul> |
| </#macro> |
| <@list items=["mouse", "elephant", "python"] title="Animals"/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <p>Animals: |
| <ul> |
| <li>Mouse |
| <li>Elephant |
| <li>Python |
| </ul> |
| </pre></div> |
| |
| <p>Example: A macro with support for a variable number of named |
| parameters:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro img src extra...> |
| <img src="/context${src?html}" |
| <#list extra?keys as attr> |
| ${attr}="${extra[attr]?html}" |
| </#list> |
| > |
| </#macro> |
| <@img src="/images/test.png" width=100 height=50 alt="Test"/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <img src="/context/images/test.png" |
| alt="Test" |
| height="50" |
| width="100" |
| ></pre></div> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_106">nested</h6> |
| |
| |
| <a name="ref.directive.nested"></a> |
| |
| <p>The <code class="inline-code">nested</code> directive executes the |
| template fragment between the start-tag and end-tags of the |
| user-defined directive. The nested part can contain anything what |
| is valid in templates; interpolations, directives, ...etc. It is |
| executed in the context where the macro was called from, rather |
| than in the context of the macro definition body. Thus, for |
| example, you don't see the local variables of the macro in the |
| nested part. If you don't call the <code class="inline-code">nested</code> |
| directive, the part between the start-tag and end-tags of the |
| user-defined directive will be ignored.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro do_twice> |
| 1. <#nested> |
| 2. <#nested> |
| </#macro> |
| <@do_twice>something</@do_twice></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1. something |
| 2. something |
| </pre></div> |
| |
| <p>The nested directive can create loop variables for the |
| nested content. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro do_thrice> |
| <#nested <strong>1</strong>> |
| <#nested <strong>2</strong>> |
| <#nested <strong>3</strong>> |
| </#macro> |
| <@do_thrice <strong>; x</strong>> |
| ${<strong>x</strong>} Anything. |
| </@do_thrice></pre></div> |
| |
| <p>This will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1 Anything. |
| 2 Anything. |
| 3 Anything. |
| </pre></div> |
| |
| <p>A more complex example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro repeat count> |
| <#list 1..count as x> |
| <#nested <strong>x, x/2, x==count</strong>> |
| </#list> |
| </#macro> |
| <@repeat count=4 ; <strong>c, halfc, last</strong>> |
| ${<strong>c</strong>}. ${<strong>halfc</strong>}<#if <strong>last</strong>> Last!</#if> |
| </@repeat></pre></div> |
| |
| <p>The output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> 1. 0.5 |
| 2. 1 |
| 3. 1.5 |
| 4. 2 Last! |
| </pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_107">return</h6> |
| |
| |
| <a name="ref.directive.macro.return"></a> |
| |
| <p>With the <code class="inline-code">return</code> directive, you can leave |
| a macro or function definition body anywhere. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test> |
| Test text |
| <#return> |
| Will not be printed. |
| </#macro> |
| <@test/></pre></div> |
| |
| <p>Output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Test text |
| </pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_function">function, return</h4> |
| |
| |
| <a name="ref.directive.function"></a> |
| |
| <a name="ref.directive.function.return"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_108">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#function <em class="code-color">name</em> <em class="code-color">param1</em> <em class="code-color">param2</em> <em class="code-color">... paramN</em>> |
| <em class="code-color">...</em> |
| <#return <em class="code-color">returnValue</em>> |
| <em class="code-color">...</em> |
| </#function></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of method variable (not expression) |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">param1</em></code>, |
| <code class="inline-code"><em class="code-color">param2</em></code>, ...etc.: |
| the name of the <a href="#dgui_misc_var">local |
| variables</a> store the parameter values (not expression), |
| optionally followed by <code class="inline-code">=</code> and the default |
| value (that's an expression). |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">paramN</em></code>, the |
| last parameter, may optionally include a trailing ellipsis |
| (<code class="inline-code">...</code>), which indicates the macro takes a |
| variable number of parameters. Local variable |
| <code class="inline-code"><em class="code-color">paramN</em></code> will be a |
| sequence of the extra parameters. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">returnValue</em></code>: |
| the expression that calculates the value of the method |
| call. |
| </li> |
| </ul> |
| |
| <p>The <code class="inline-code">return</code> directive can be used anywhere |
| and for any times between the <code class="inline-code"><#function |
| <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#function></code>.</p> |
| |
| <p>Parameters without default value must precede parameters with |
| default value |
| (<code class="inline-code"><em class="code-color">paramName</em>=<em class="code-color">defaultValue</em></code>).</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_109">Description</h5> |
| |
| |
| <p>Creates a method variable (in the current namespace, if you |
| know namespace feature). This directive works in the same way as the |
| <a href="#ref.directive.macro"><code>macro</code> |
| directive</a>, except that <code class="inline-code">return</code> directive |
| <em>must</em> have a parameter that specifies the return |
| value of the method, and that attempts to write to the output will |
| be ignored. If the <code class="inline-code"></#function></code> is reached |
| (i.e. there was no <code class="inline-code">return |
| <em class="code-color">returnValue</em></code>), then the return |
| value of the method is an undefined variable.</p> |
| |
| <p>Example 1: Creating a method that calculates the average of |
| two numbers:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#function avg x y> |
| <#return (x + y) / 2> |
| </#function> |
| ${avg(10, 20)}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">15</pre></div> |
| |
| <p>Example 2: Creating a method that calculates the average of |
| multiple numbers:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#function avg nums...> |
| <#local sum = 0> |
| <#list nums as num> |
| <#local sum = sum + num> |
| </#list> |
| <#if nums?size != 0> |
| <#return sum / nums?size> |
| </#if> |
| </#function> |
| ${avg(10, 20)} |
| ${avg(10, 20, 30, 40)} |
| ${avg()!"N/A"}</pre></div> |
| |
| <p>will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">15 |
| 25 |
| N/A</pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_flush">flush</h4> |
| |
| |
| <a name="ref.directive.flush"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_110">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#flush></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_111">Description</h5> |
| |
| |
| <p>When FreeMarker generates the output it typically stockpiles |
| the generated output and send it to the client in one or in a few |
| big pieces. This act of sending is called flushing (as flushing the |
| toilet). Although flushing happens automatically, sometimes you want |
| to force it on certain points of the template processing, and this |
| is what <code class="inline-code">flush</code> directive does. If it is needed, |
| then the programmer could tell it to you; typically you should not |
| use this directive. The mechanism of automatic flushing and the |
| precise effect of <code class="inline-code">flush</code> directive are under the |
| control of the programmer.</p> |
| |
| <p><span class="marked-for-programmers">Flush simply calls the flush |
| method of the currently used java.io.Writer instance. The whole |
| buffering and flushing mechanism is implemented in the writer (what |
| you have passed as the parameter of the |
| <code class="inline-code">Template.process</code> method); FreeMarker does not |
| deal with it.</span></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_stop">stop</h4> |
| |
| |
| <a name="ref.directive.stop"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_112">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#stop></code> |
| or |
| <code class="inline-code"><#stop <em class="code-color">reason</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">reason</em></code>: |
| Informative message about the reason of termination. Expression |
| evaluates to string. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_113">Description</h5> |
| |
| |
| <p>Aborts the processing of template. This is something like an |
| emergency brake: don't use it in normal situations. <span class="marked-for-programmers">Aborting happens by throwing a |
| <code class="inline-code">StopException</code>, and the |
| <code class="inline-code">StopException</code> will hold the value of reason |
| parameter.</span></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_ftl">ftl</h4> |
| |
| |
| <a name="ref.directive.ftl"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_114">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#ftl <em class="code-color">param1</em>=<em class="code-color">value1</em> <em class="code-color">param2</em>=<em class="code-color">value2</em> <em class="code-color">...</em> <em class="code-color">paramN</em>=<em class="code-color">valueN</em>></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">param1</em></code>, |
| <code class="inline-code"><em class="code-color">param2</em></code>, ...etc.: |
| Name of the parameter. Not an expression. Allowed parameters |
| are: <code class="inline-code">encoding</code>, |
| <code class="inline-code">strip_whitespace</code>, |
| <code class="inline-code">strip_text</code>, ...etc. See below. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value1</em></code>, |
| <code class="inline-code"><em class="code-color">value2</em></code>, ...etc.: |
| The value of parameter. This must be a constant expression (as |
| <code class="inline-code">true</code>, or <code class="inline-code">"ISO-8859-5"</code>, or |
| <code class="inline-code">{x:1, y:2}</code>). It can't use variables. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_115">Description</h5> |
| |
| |
| <p>Tells information about the template for FreeMarker and for |
| other tools, also helps programs to automatically detect if a text |
| file is an FTL file. This directive, if present, must be the very |
| first thing in the template. Any <a href="#gloss.whiteSpace">white-space</a> before this directive |
| will be ignored. The old-syntax (<code class="inline-code">#</code>-less) format |
| of this directive is not supported.</p> |
| |
| <p>The settings (encoding, white-space stripping, etc.) given |
| here has the highest precedence, that is, they will be used for the |
| template regardless of any FreeMarker configuration settings.</p> |
| |
| <p>Parameters:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">encoding</code>: With this you can specify the |
| encoding (charset) of the template in the template file itself. |
| <span class="marked-for-programmers">(That is, this will be the |
| <code class="inline-code">encoding</code> setting of the newly created |
| <code class="inline-code">Template</code>, and not even the |
| <code class="inline-code">encoding</code> parameter to |
| <code class="inline-code">Configuration.getTemplate</code> can override |
| it)</span>. Note however, that FreeMarker will try to find and |
| interpret the <code class="inline-code">ftl</code> directive first with the |
| automatically guessed encoding (which depends on the FreeMarker |
| configuration set by the programmers), and only then realizes if |
| the <code class="inline-code">ftl</code> directive dictates something |
| different, and re-read the template with the new encoding. Thus, |
| the template must be valid FTL until the end of |
| <code class="inline-code">ftl</code> tag with the encoding tried first. The |
| valid values of this parameter are MIME-preferred charset names |
| from the IANA Charset Registry, like ISO-8859-5, UTF-8 or |
| Shift_JIS.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">strip_whitespace</code>: This enables/disables |
| <a href="#dgui_misc_whitespace_stripping">white-space |
| stripping</a>. Valid values are the boolean constants |
| <code class="inline-code">true</code> and <code class="inline-code">false</code>. (And for |
| backward compatibility, strings <code class="inline-code">"yes"</code>, |
| <code class="inline-code">"no"</code>, <code class="inline-code">"true"</code>, |
| <code class="inline-code">"false"</code>). The default value (i.e. when you |
| don't use this parameter) depends on the FreeMarker |
| configuration set by the programmers, but it should be |
| <code class="inline-code">true</code> for new projects.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">strip_text</code>: When enabled, all top-level |
| text in a template is removed when the template is parsed. This |
| does not affect text within macros, directives, or |
| interpolations. Valid values are the boolean constants |
| <code class="inline-code">true</code> and <code class="inline-code">false</code>. (And for |
| backward compatibility, strings <code class="inline-code">"yes"</code>, |
| <code class="inline-code">"no"</code>, <code class="inline-code">"true"</code>, |
| <code class="inline-code">"false"</code>). The default value (i.e. when you |
| don't use this parameter) is <code class="inline-code">false</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">strict_syntax</code>: This turns on/off |
| ``strict syntax''. Valid values are the boolean constants |
| <code class="inline-code">true</code> and <code class="inline-code">false</code>. (And for |
| backward compatibility, strings <code class="inline-code">"yes"</code>, |
| <code class="inline-code">"no"</code>, <code class="inline-code">"true"</code>, |
| <code class="inline-code">"false"</code>). The default value (i.e. when you |
| don't use this parameter) depends on the FreeMarker |
| configuration set by the programmers, but it should be |
| <code class="inline-code">true</code> for new projects. <span class="marked-for-programmers">(Programmers: you must set explicitly this |
| setting to <code class="inline-code">true</code> for this: |
| <code class="inline-code">config.setStrictSyntaxMode(true);</code>)</span> |
| For more information read: <a href="#ref_depr_oldsyntax">Deprecated FTL constructs/Old FTL syntax</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ns_prefixes</code>: This is a hash that |
| associates prefixes with node namespaces. For example: |
| <code class="inline-code">{"e":"http://example.com/ebook", |
| "vg":"http://example.com/vektorGraphics"}</code>. This is |
| mostly used with XML processing where the prefixes can be used |
| in XML queries, but it also influences the working of <a href="#ref_directive_visit">directives |
| <code>visit</code> and <code>recurse</code></a>. |
| Only one prefix can be registered for the same node namespace |
| (otherwise an error will occur), so there is one-to-one relation |
| between prefixes and node namespaces. Prefixes |
| <code class="inline-code">D</code> and <code class="inline-code">N</code> are reserved. If |
| you register prefix <code class="inline-code">D</code>, then other than you |
| associate the node namespace with prefix <code class="inline-code">D</code>, |
| you also set the default node namespace. Prefix |
| <code class="inline-code">N</code> can't be registered; it is used to denote |
| nodes with no node namespace in certain places, when (and only |
| when) prefix <code class="inline-code">D</code> is registered. (To see the |
| usage of default node namespace, <code class="inline-code">N</code>, and |
| prefixes in general, see the part about <a href="#xgui">XML |
| processing</a> and <a href="#ref_directive_visit"><code>visit</code> and |
| <code>recurse</code></a> in the reference.) The effect |
| of <code class="inline-code">ns_prefixes</code> is limited to a single <a href="#dgui_misc_namespace">FTL namespace</a>, namely, to |
| the FTL namespace that was created for the template. This also |
| means that <code class="inline-code">ns_prefixes</code> has effect only when |
| an FTL namespace is created for the template that contains it, |
| otherwise the <code class="inline-code">ns_prefixes</code> parameter has no |
| effect. An FTL namespace is made for a template when: (a) the |
| template is the ``main'' template, that is, it is not invoked as |
| a result of an <code class="inline-code"><#include ...></code>, but it |
| is directly invoked (<span class="marked-for-programmers">with the |
| <code class="inline-code">process</code> Java method of class |
| <code class="inline-code">Template</code> or |
| <code class="inline-code">Environment</code></span>); (b) the template is |
| invoked directly with <code class="inline-code"><#import |
| ...></code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">attributes</code>: This is a hash that |
| associates arbitrary attributes (name-value pairs) to the |
| template. The values of the attributes can be of any type |
| (string, number, sequence... etc.). FreeMarker doesn't try to |
| understand the meaning of the attributes. It's up to the |
| application that encapsulates FreeMarker (as a Web application |
| framework). Thus, the set of allowed attributes and their |
| semantic is application (Web application framework) dependent. |
| <span class="marked-for-programmers">Programmers: you can get the |
| attributes associated with a <code class="inline-code">Template</code> object |
| with its <code class="inline-code">getCustomAttributeNames</code> and |
| <code class="inline-code">getCustomAttribute</code> methods (inherited from |
| <code class="inline-code">freemarker.core.Configurable</code>). As the |
| template attributes are associated with the |
| <code class="inline-code">Template</code> object when the template is parsed, |
| the attributes can be read anytime, the template need not be |
| executed. The methods mentioned return the attribute values |
| unwrapped, that is, with FreeMarker independent type as |
| <code class="inline-code">java.util.List</code>.</span></p> |
| </li> |
| </ul> |
| |
| <p>This directive also determines if the template uses angle |
| bracket syntax (e.g. <code class="inline-code"><#include 'foo.ftl'></code>) |
| or <a href="#dgui_misc_alternativesyntax">square bracket |
| syntax</a> (e.g. <code class="inline-code">[#include 'foo.ftl']</code>). |
| Simply, the syntax used for this directive will be the syntax used |
| for the whole template, regardless of the FreeMarker configuration |
| settings.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_t">t, lt, rt</h4> |
| |
| |
| <a name="ref.directive.t"></a> |
| |
| <a name="ref.directive.lt"></a> |
| |
| <a name="ref.directive.rt"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_116">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#t></code> |
| |
| <code class="inline-code"><#lt></code> |
| |
| <code class="inline-code"><#rt></code> |
| |
| <code class="inline-code"><#nt></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_117">Description</h5> |
| |
| |
| <p>These directives, instruct FreeMarker to ignore certain |
| white-space in the line of the tag:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">t</code> (for trim): Ignore all leading and |
| trailing white-space in this line.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">lt</code> (for left trim): Ignore all leading |
| white-space in this line.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">rt</code> (for right trim): Ignore all |
| trailing white-space in this line.</p> |
| </li> |
| </ul> |
| |
| <p>where:</p> |
| |
| <ul> |
| <li> |
| <p>``leading white-space'' means all space and tab (and other |
| character that are white-space according to <a href="#gloss.unicode">UNICODE</a>, except <a href="#gloss.lineBreak">line breaks</a>) before the first |
| non-white-space character of the line.</p> |
| </li> |
| |
| <li> |
| <p>``trailing white-space'' means all space and tab (and |
| other character that are white-space according to <a href="#gloss.unicode">UNICODE</a>, except line breaks) |
| after the last non-white-space character of the line, |
| <em>and</em> the line break at the end of the |
| line.</p> |
| </li> |
| </ul> |
| |
| <p>It is important to understand that these directives examine |
| the template itself, and <em>not</em> the output what |
| the template generates when you merge it with the data-model. |
| <span class="marked-for-programmers">(That is, the white-space removal |
| happens on parse time.)</span></p> |
| |
| <p>For example this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">-- |
| 1 <#t> |
| 2<#t> |
| 3<#lt> |
| 4 |
| 5<#rt> |
| 6 |
| --</pre></div> |
| |
| <p>will output this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">-- |
| 1 23 |
| 4 |
| 5 6 |
| --</pre></div> |
| |
| <p>The placement of these directives inside the line has no |
| importance. That is, the effect will be the same regardless if you |
| put the directive at the beginning of the line, or at the end of the |
| line, or in the middle of the line.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_nt">nt</h4> |
| |
| |
| <a name="ref.directive.nt"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_118">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#nt></code> |
| </pre> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_119">Description</h5> |
| |
| |
| <p>``No Trim''. This directive disables <a href="#dgui_misc_whitespace_stripping">white-space |
| stripping</a> in the line where it occurs. It also disables the |
| effect of other trim directives occuring in the same line (the |
| effect of <code class="inline-code">t</code>, <code class="inline-code">rt</code>, |
| <code class="inline-code">lt</code>).</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_attempt">attempt, recover</h4> |
| |
| |
| <a name="ref.directive.attempt"></a> |
| |
| |
| |
| |
| |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The above format is supported starting from 2.3.3, earlier it |
| was |
| <code class="inline-code"><#attempt><em class="code-color">...</em><#recover><em class="code-color">...</em></#recover></code>, |
| which is still supported for backward compatibility. Furthermore, |
| these directives were introduced with FreeMarker 2.3.1, so they |
| aren't exist in 2.3.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_120">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#attempt> |
| <em class="code-color">attempt block</em> |
| <#recover> |
| <em class="code-color">recover block</em> |
| </#attempt> |
| </code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">attempt |
| block</em></code>: Template block with any content. |
| This will be always executed, but if an error occurs during |
| that, all output from this block is rolled back, and the |
| <code class="inline-code"><em class="code-color">recover block</em></code> will |
| be executed. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">recover |
| block</em></code>: Template block with any content. |
| This will be executed only if there was an error during the |
| execution of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code>. You may print an error messages |
| here and such. |
| </li> |
| </ul> |
| |
| <p>The <code class="inline-code"><em class="code-color">recover</em></code> is |
| mandatory. <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> can |
| be nested freely into other <code class="inline-code"><em class="code-color">attempt |
| block</em></code>s or <code class="inline-code"><em class="code-color">recover |
| block</em></code>s.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_121">Description</h5> |
| |
| |
| <p>These directives are used if you want the page successfully |
| outputted even if the outputting of a certain part of the page |
| fails. If an error occurs during the execution of the |
| <code class="inline-code"><em class="code-color">attempt block</em></code>, then |
| the template execution is not aborted, but the |
| <code class="inline-code"><em class="code-color">recover block</em></code> is |
| executed instead of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code>. If no error occurs during the |
| execution of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code>, then the |
| <code class="inline-code"><em class="code-color">recover block</em></code> is |
| ignored. A simple example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">Primary content |
| <#attempt> |
| Optional content: ${thisMayFails} |
| <#recover> |
| Ops! The optional content is not available. |
| </#attempt> |
| Primary content continued</pre></div> |
| |
| <p>If the <code class="inline-code">thisMayFails</code> variable doesn't exist, |
| then the output is:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Primary content |
| Ops! The optional content is not available. |
| Primary content continued</pre></div> |
| |
| <p>If the <code class="inline-code">thisMayFails</code> variable exists and |
| it's value is <code class="inline-code">123</code>, then the output is:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Primary content |
| Optional content: 123 |
| Primary content continued</pre></div> |
| |
| <p>The <code class="inline-code"><em class="code-color">attempt |
| block</em></code> has an all-or-none semantic: either |
| the entire content of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code> is output (when there was no error), |
| or no output at all results from the execution of the |
| <code class="inline-code"><em class="code-color">attempt block</em></code> (when |
| there was an error). For example, above, the failure happens after |
| ``Optional content: '' was printed, still it is not there in the |
| output before the ``Ops!''. (<span class="marked-for-programmers">This is |
| implemented with the aggressive buffering of the output inside the |
| <code class="inline-code"><em class="code-color">attempt block</em></code>. Not |
| even the <code class="inline-code">flush</code> directive will send the output to |
| the client.</span>)</p> |
| |
| <p>To prevent misunderstandings coming from the above example: |
| <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> is not (only) |
| for handling undefined variables (for that use <a href="#dgui_template_exp_missing">missing value handler |
| operators</a>). It can handle all kind of errors that occurs when |
| the block is executed (i.e. not syntactical errors, which are |
| detected earlier). And it's meant to enclose bigger template |
| fragments, where error can occur at various points. For example, you |
| have a part in your template that deals with printing |
| advertisements, but that's not the primary content of the page, so |
| you don't want your whole page be down just because some error |
| occurs with the printing of the advertisements (say, because of a |
| temporal database server faliure). So you put the whole |
| advertisement printing into an <code class="inline-code"><em class="code-color">attempt |
| block</em></code>.</p> |
| |
| <p>In some environments programmers configure FreeMarker so that |
| it doesn't abort template execution for certain errors, but |
| continues execution, possibly after printing some error indicator to |
| the output (<span class="marked-for-programmers">see more <a href="#pgui_config_errorhandling">here...</a></span>). The |
| <code class="inline-code">attempt</code> directive doesn't consider such |
| suppressed errors as errors.</p> |
| |
| <p>Inside a <code class="inline-code"><em class="code-color">recover |
| block</em></code> the error message of the error is |
| available with the <code class="inline-code">error</code> <a href="#ref_specvar">special variable</a>. Don't forget that |
| references to special variable are started with dot (for example: |
| <code class="inline-code">${.error}</code>).</p> |
| |
| <p><span class="marked-for-programmers">Errors occurring during template |
| execution are always <a href="#pgui_misc_logging">logged</a>, even if they occur inside |
| an <code class="inline-code"><em class="code-color">attempt |
| block</em></code>.</span></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_directive_visit">visit, recurse, fallback</h4> |
| |
| |
| <a name="ref.directive.visit"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_122">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#visit <em class="code-color">node</em> using <em class="code-color">namespace</em>></code> |
| or |
| <code class="inline-code"><#visit <em class="code-color">node</em>></code></pre> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#recurse <em class="code-color">node</em> using <em class="code-color">namespace</em>></code> |
| or |
| <code class="inline-code"><#recurse <em class="code-color">node</em>></code> |
| or |
| <code class="inline-code"><#recurse using <em class="code-color">namespace</em>></code> |
| or |
| <code class="inline-code"><#recurse></code></pre> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#fallback></code></pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">node</em></code>: |
| Expression evaluates to a <a href="#xgui_expose_dom">node |
| variable</a>. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">namespace</em></code>: A |
| <a href="#dgui_misc_namespace">namespace</a>, or a |
| sequence of namespaces. A namespace can be given with the |
| namespace hash (a.k.a. gate hash), or with a string literal that |
| store the path of template that could be imported. Instead of |
| namespace hashes, you can use plain hashes as well. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_123">Description</h5> |
| |
| |
| <p>The <code class="inline-code">visit</code> and <code class="inline-code">recurse</code> |
| directives are used for the recursive processing of trees. In |
| practice, this will mostly be used for <a href="#xgui">processing XML.</a></p> |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_124">Visit</h6> |
| |
| |
| <p>When you call <code class="inline-code"><#visit |
| <em class="code-color">node</em>></code>, it looks for a |
| user-defined directive (like a macro) to invoke that has the name |
| deducted from the node's name |
| (<code class="inline-code"><em class="code-color">node</em>?node_name</code>) and |
| namespace |
| (<code class="inline-code"><em class="code-color">node</em>?node_namesoace</code>). |
| The rules of name deduction:</p> |
| |
| <ul> |
| <li> |
| <p>If the node doesn't support node namespaces (as text |
| nodes in XML), then the directive name is simply the name of |
| the node |
| (<code class="inline-code"><em class="code-color">node</em>?node_name</code>). |
| <span class="marked-for-programmers">A node does not support node |
| namespaces if the <code class="inline-code">getNodeNamespace</code> method |
| returns <code class="inline-code">null</code>.</span></p> |
| </li> |
| |
| <li> |
| <p>If the node does support node namespaces (as element |
| nodes in XML), then a prefix deduced from the node namespace |
| maybe appended before the node name with a colon used as |
| separator (e.g. <code class="inline-code">e:book</code>). The prefix, and if |
| there is a prefix used at all, depends on what prefixes has |
| been registered with the <code class="inline-code">ns_prefixes</code> |
| parameter of the <code class="inline-code">ftl</code> directive in the <a href="#dgui_misc_namespace">FTL namespace</a> where |
| <code class="inline-code">visit</code> looks for the handler directive |
| (which is not necessary the same as the FTL namespace where |
| <code class="inline-code">visit</code> was called from, as you will see |
| later). Concretely, if there was no default namespace |
| registered with <code class="inline-code">ns_prefixes</code> then for nodes |
| that does not belong to any namespace (<span class="marked-for-programmers">when <code class="inline-code">getNodeNamespace</code> |
| returns <code class="inline-code">""</code></span>) no prefix is used. If |
| there was a default namespace registered with |
| <code class="inline-code">ns_prefixes</code> then for nodes that does not |
| belong to any namespace prefix <code class="inline-code">N</code> is used, |
| and for nodes that belong to the default node namespace no |
| prefix is used. Otherwise, in both case, the prefix associated |
| to the node namespace with the <code class="inline-code">ns_prefixes</code> |
| is used. If there is not prefix associated to the node |
| namespace of the node, then <code class="inline-code">visit</code> simply |
| behave as if there was no directive found with the proper |
| name.</p> |
| </li> |
| </ul> |
| |
| <p>The node for which the user-defined directive was invoked is |
| available for it as special variable <code class="inline-code">.node</code>. |
| Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- Assume that nodeWithNameX?node_name is "x" --> |
| <#visit nodeWithNameX> |
| Done. |
| <#macro x> |
| Now I'm handling a node that has the name "x". |
| Just to show how to access this node: this node has ${.node?children?size} children. |
| </#macro></pre></div> |
| |
| <p>The output will be something like:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> Now I'm handling a node that has the name "x". |
| Just to show how to access this node: this node has 3 children. |
| Done.</pre></div> |
| |
| <p>If one or more namespaces is specified using the optional |
| <code class="inline-code">using</code> clause, then <code class="inline-code">visit</code> |
| will look for the directives in those namespaces only, with the |
| earlier specified namespaces in the list getting priority. If no |
| <code class="inline-code">using</code> clause is specified, the namespace or |
| sequence of namespaces specified with the <code class="inline-code">using</code> |
| clause of the last uncompleted <code class="inline-code">visit</code> call is |
| reused. If there is no such pending <code class="inline-code">visit</code> call, |
| then the current namespace is used. For example, if you execute |
| this template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "n1.ftl" as n1> |
| <#import "n2.ftl" as n2> |
| |
| <#-- This will call n2.x (because there is no n1.x): --> |
| <#visit nodeWithNameX using [n1, n2]> |
| |
| <#-- This will call the x of the current namespace: --> |
| <#visit nodeWithNameX> |
| |
| <#macro x> |
| Simply x |
| </#macro></pre></div> |
| |
| <p>and this is <code class="inline-code">n1.ftl</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro y> |
| n1.y |
| </#macro></pre></div> |
| |
| <p>and this is <code class="inline-code">n2.ftl</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro x> |
| n2.x |
| <#-- This will call n1.y, becuase it inherits the "using [n1, n2]" from the pending visit call: --> |
| <#visit nodeWithNameY> |
| <#-- This will call n2.y: --> |
| <#visit nodeWithNameY using .namespace> |
| </#macro> |
| |
| <#macro y> |
| n2.y |
| </#macro></pre></div> |
| |
| <p>then this will print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> |
| n2.x |
| n1.y |
| n2.y |
| |
| Simply x |
| </pre></div> |
| |
| <p>If <code class="inline-code">visit</code> doesn't find a user-defined |
| directive in either FTL namespaces with the name identical to the |
| name deduced with the rules described earlier, then it tries to |
| find an user-defined directive with name |
| <code class="inline-code">@<em class="code-color">node_type</em></code>, or if |
| the node does not support node type property (i.e. |
| <code class="inline-code"><em class="code-color">node</em>?node_type</code> |
| returns undefined variable), then with name |
| <code class="inline-code">@default</code>. For the lookup, it uses the same |
| mechanism as was explained earlier. If it still doesn't find an |
| user-defined directive to handle the node, then |
| <code class="inline-code">visit</code> stops template processing with error. |
| Some XML specific node types have special handling in this regard; |
| see: <a href="#xgui_declarative_details">XML Processing Guide/Declarative XML Processing/Details</a>. Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- Assume that nodeWithNameX?node_name is "x" --> |
| <#visit nodeWithNameX> |
| |
| <#-- Assume that nodeWithNameY?node_type is "foo" --> |
| <#visit nodeWithNameY> |
| |
| <#macro x> |
| Handling node x |
| </#macro> |
| |
| <#macro @foo> |
| There was no specific handler for node ${node?node_name} |
| </#macro></pre></div> |
| |
| <p>This would print:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output">Handling node x |
| |
| There was no specific handler for node y |
| |
| </pre></div> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_125">Recurse</h6> |
| |
| |
| <a name="ref.directive.recurse"></a> |
| |
| <p>The <code class="inline-code"><#recurse></code> directive is really |
| syntactic sugar. It visits all children nodes of the node (and not |
| the node itself). So, to write:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#recurse <em>someNode</em> using <em>someLib</em>></pre></div> |
| |
| <p>is equivalent to writing:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list <em>someNode</em>?children as <em>child</em>><#visit <em>child</em> using <em>someLib</em>></#list></pre></div> |
| |
| <p>However, target node is optional in the |
| <code class="inline-code">recurse</code> directive. If the target node is |
| unspecified, it simply uses the <code class="inline-code">.node</code>. Thus, |
| the terse instruction <code class="inline-code"><#recurse></code> is |
| equivalent to:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list .node?children as child><#visit child></#list></pre></div> |
| |
| <p>As a side comment for those who are familiar with XSLT, |
| <code class="inline-code"><#recurse></code> is pretty much exactly |
| analogous to the <code class="inline-code"><xsl:apply-templates/></code> |
| instruction in XSLT.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_126">Fallback</h6> |
| |
| |
| <a name="ref.directive.fallback"></a> |
| |
| <p>As you could learn earlier, in the documentation of the |
| <code class="inline-code">visit</code> directive, the user-defined directive |
| that handles the node is maybe searched in multiple FTL |
| name-spaces. The <code class="inline-code">fallback</code> directive can be used |
| in a user-defined directive that was invoked to handle a node. It |
| directs FreeMarker to continue the searching for the user-defined |
| directive in the further name-spaces (that is, in the name-spaces |
| that are after the name-space of the currently invoked |
| user-defined directive in the list of name-spaces). If a handler |
| for the node is found then it is invoked, otherwise |
| <code class="inline-code">fallback</code> does nothing.</p> |
| |
| <p>A typical usage of this to write customization layer over a |
| handler library, that sometimes passes the handling to the |
| customized library:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#import "/lib/docbook.ftl" as docbook> |
| |
| <#-- |
| We use the docbook library, but we override some handlers |
| in this namespace. |
| --> |
| <#visit document using [.namespace, docbook]> |
| |
| <#-- |
| Override the "programlisting" handler, but only in the case if |
| its "role" attribute is "java" |
| --> |
| <#macro programlisting> |
| <#if .node.@role[0]!"" == "java"> |
| <#-- Do something special here... --> |
| ... |
| <#else> |
| <#-- Just use the original (overidden) handler --> |
| <#fallback> |
| </#if> |
| </#macro></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="ref_specvar">Special Variable Reference</h3> |
| |
| |
| |
| |
| <p>Special variables are variables defined by the FreeMarker engine |
| itself. To access them, you use the |
| <code class="inline-code">.<em class="code-color">variable_name</em></code> syntax. For |
| example, you can't write simply <code class="inline-code">version</code>; you have to |
| write <code class="inline-code">.version</code>.</p> |
| |
| <p>The supported special variables are:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">data_model</code>: A hash that you can use to |
| access the data-model directly. That is, variables you did with |
| <code class="inline-code">global</code> directive are not visible here. |
| </li> |
| |
| <li> |
| <code class="inline-code">error</code> (available since FreeMarker |
| 2.3.1): This variable accessible in the body of the <a href="#ref.directive.attempt"><code>recover</code> |
| directive</a>, where it stores the error message of the error we |
| recover from. |
| </li> |
| |
| <li> |
| <code class="inline-code">globals</code>: A hash that you can use to access |
| the globally accessible variables: the data-model and the variables |
| created with <code class="inline-code">global</code> directive. Note that |
| variables created with <code class="inline-code">assign</code> or |
| <code class="inline-code">macro</code> are not globals, thus they never hide the |
| variables when you use <code class="inline-code">globals</code>. |
| </li> |
| |
| <li> |
| <code class="inline-code">language</code>: Returns the language part |
| of the current value of the locale setting. For example if |
| <code class="inline-code">.locale</code> is <code class="inline-code">en_US</code>, then |
| <code class="inline-code">.lang</code> is <code class="inline-code">en</code>. |
| </li> |
| |
| <li> |
| <code class="inline-code">locale</code>: Returns the current value |
| of the locale setting. This is a string, for example |
| <code class="inline-code">en_US</code>. For more information about locale strings |
| <a href="#ref.directive.setting">see the |
| <code>setting</code> directive</a>. |
| </li> |
| |
| <li> |
| <code class="inline-code">locals</code>: A hash that you can use to access |
| the local variables (the variables created with the |
| <code class="inline-code">local</code> directive, and the parameters of |
| macro). |
| </li> |
| |
| <li> |
| <code class="inline-code">main</code>: A hash that you can use to access the |
| main <a href="#dgui_misc_namespace">namespace</a>. Note that |
| global variables like the variables of data-model are |
| <em>not</em> visible through this hash. |
| </li> |
| |
| <li> |
| <code class="inline-code">namespace</code>: A hash that you can use to |
| access the current <a href="#dgui_misc_namespace">namespace</a>. Note that global |
| variables like the variables of data-model are |
| <em>not</em> visible through this hash. |
| </li> |
| |
| <li> |
| <code class="inline-code">node</code> (alias <code class="inline-code">current_node</code> |
| for historical reasons): The node you are currently processing with |
| the visitor pattern (i.e. with the <a href="#ref_directive_visit"><code>visit</code>, |
| <code>recurse</code>, ...etc. directives</a>). Also, it |
| initially stores the root node when you use the <a href="#pgui_misc_ant">FreeMarker XML Ant task</a>. |
| </li> |
| |
| <li> |
| <code class="inline-code">output_encoding</code> (available since |
| FreeMarker 2.3.1): Returns the name of the current output charset. |
| This special variable is not existent if the framework that |
| encapsulates FreeMarker doesn't specify the output charset for |
| FreeMarker. <span class="marked-for-programmers">(Programmers can read more |
| about charset issues <a href="#pgui_misc_charset">here...</a>)</span> |
| </li> |
| |
| <li> |
| <code class="inline-code">template_name</code>: The name of the current |
| template (available since FreeMarker 2.3.14). |
| </li> |
| |
| <li> |
| <code class="inline-code">url_escaping_charset</code> (available |
| since FreeMarker 2.3.1): If exists, it stores the name of the |
| charset that should be used for URL escaping. If this variable |
| doesn't exist that means that nobody has specified what charset |
| should be used for URL encoding yet. In this case the <a href="#ref_builtin_url"><code>url</code> built-in</a> |
| uses the charset specified by the <code class="inline-code">output_encoding</code> |
| special variable for URL encoding; custom mechanism may follow the |
| same logic. <span class="marked-for-programmers">(Programmers can read more |
| about charset issues <a href="#pgui_misc_charset">here...</a>)</span> |
| </li> |
| |
| <li> |
| <code class="inline-code">vars</code>: Expression |
| <code class="inline-code">.vars.foo</code> returns the same variable as expression |
| <code class="inline-code">foo</code>. It's useful if for some reasons you have to |
| use square bracket syntax, since that works only for hash |
| subvariables, so you need an artificial parent hash. For example, to |
| read a top-level variable that has a strange name that would confuse |
| FreeMarker, you can write |
| <code class="inline-code">.vars["A strange name!"]</code>. Or, to access a |
| top-level variable with dynamic name given with variable |
| <code class="inline-code">varName</code> you can write |
| <code class="inline-code">.vars[varName]</code>. Note that the hash returned by |
| <code class="inline-code">.vars</code> does not support <code class="inline-code">?keys</code> |
| and <code class="inline-code">?values</code>. |
| </li> |
| |
| <li> |
| <code class="inline-code">version</code>: Returns the FreeMarker |
| version number as string, for example <code class="inline-code">2.2.8</code>. This |
| can be used to check which FreeMarker version does your application |
| use, but note that this special variable does not exist prior to the |
| 2.3-final or 2.2.8 versions. The version number of non-final |
| releases contain abbreviation ``pre'' for ``preview'' (e.g. |
| <code class="inline-code">2.3pre6</code>), or abbrevation ``rc'' for ``release |
| candidate''. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="ref_reservednames">Reserved names in FTL</h3> |
| |
| |
| |
| |
| <p>The following names cannot be used for top-level variables without |
| square-bracket syntax (as <code class="inline-code">.vars["in"]</code>), since they |
| are keywords in FTL:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code">true</code>: boolean value ``true'' |
| </li> |
| |
| <li> |
| <code class="inline-code">false</code>: boolean value ``false'' |
| </li> |
| |
| <li> |
| <code class="inline-code">gt</code>: comparison operator ``greater |
| than'' |
| </li> |
| |
| <li> |
| <code class="inline-code">gte</code>: comparison operator ``greater than or |
| equivalent'' |
| </li> |
| |
| <li> |
| <code class="inline-code">lt</code>: comparison operator ``less |
| than'' |
| </li> |
| |
| <li> |
| <code class="inline-code">lte</code>: comparison operator ``less than or |
| equivalent'' |
| </li> |
| |
| <li> |
| <code class="inline-code">as</code>: used by a few directives |
| </li> |
| |
| <li> |
| <code class="inline-code">in</code>: used by a few directives |
| </li> |
| |
| <li> |
| <code class="inline-code">using</code>: used by a few directives |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="ref_deprecated">Deprecated FTL constructs</h3> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_directive">List of deprecated directives</h4> |
| |
| |
| <p>The following directives are deprecated, but still |
| working:</p> |
| |
| <ul> |
| <li> |
| <p><a href="#ref.directive.call"><code>call</code></a>: use |
| <a href="#ref.directive.userDefined">user-defined directive |
| call</a> instead</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">comment</code>: This is the old format of |
| <code class="inline-code"><#--<em class="code-color">...</em>--></code>. |
| Anything between the <code class="inline-code"><#comment></code> and |
| <code class="inline-code"></#comment></code> will be ignored.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">foreach</code>: it is a synonym of the |
| <code class="inline-code">list</code> directive with slightly different |
| parameter syntax. The syntax is <code class="inline-code"><#foreach |
| <em class="code-color">item</em> in |
| <em class="code-color">sequence</em>></code> that is |
| equivalent with <code class="inline-code"><#list |
| <em class="code-color">sequence</em> as |
| <em class="code-color">item</em>></code>.</p> |
| </li> |
| |
| <li> |
| <p><a href="#ref.directive.transform"><code>transform</code></a>: |
| use <a href="#ref.directive.userDefined">user-defined |
| directive call</a> instead</p> |
| </li> |
| </ul> |
| |
| <p>The following directives are not working anymore:</p> |
| |
| <ul> |
| <li> |
| <p>Legacy <code class="inline-code">function</code>: Originally |
| <code class="inline-code">function</code> was used to define macros, and was |
| deprecated in favor of the <code class="inline-code">macro</code> directive. As |
| of FreeMarker 2.3, this directive is reintroduced with different |
| meaning: it is used to define methods.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_builtin">List of deprecated built-ins</h4> |
| |
| |
| <p>The following built-ins are deprecated, but still |
| working:</p> |
| |
| <ul> |
| <li> |
| <p> <code class="inline-code">default</code>: This was deprecated |
| with the introduction of the <a href="#dgui_template_exp_missing_default">default value |
| operator</a>. |
| <code class="inline-code"><em class="code-color">exp1</em>?default(<em class="code-color">exp2</em>)</code> |
| is near equivalent with |
| <code class="inline-code"><em class="code-color">exp1</em>!<em class="code-color">exp2</em></code>, |
| and |
| <code class="inline-code">(<em class="code-color">exp1</em>)?default(<em class="code-color">exp2</em>)</code> |
| is near equivalent with with |
| <code class="inline-code">(<em class="code-color">exp1</em>)!<em class="code-color">exp2</em></code>. |
| The only difference is that prior to FreeMarker 2.4, the |
| <code class="inline-code">default</code> built-in has always evaluated |
| <code class="inline-code"><em class="code-color">exp2</em></code>, while the |
| default value operator only evaluates it when the default value is |
| really needed. Starting from FreeMarker 2.4, however, the |
| <code class="inline-code">default</code> built-in was improved, and behaves |
| exactly like the default value operator.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">exists</code>: This was deprecated with |
| the introduction of the <a href="#dgui_template_exp_missing_test">missing value test |
| operator</a>. |
| <code class="inline-code"><em class="code-color">exp1</em>?exists</code> is |
| equivalent with |
| <code class="inline-code"><em class="code-color">exp1</em>??</code>, also |
| <code class="inline-code">(<em class="code-color">exp1</em>)?exists</code> is |
| equivalent with with |
| <code class="inline-code">(<em class="code-color">exp1</em>)??</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">if_exists</code>: This was deprecated |
| with the introduction of the <a href="#dgui_template_exp_missing_default">default value |
| operator</a>. |
| <code class="inline-code"><em class="code-color">exp1</em>?if_exists</code> is |
| similar to <code class="inline-code"><em class="code-color">exp1</em>!</code>, |
| and <code class="inline-code">(<em class="code-color">exp1</em>)?if_exists</code> |
| is similar to |
| <code class="inline-code">(<em class="code-color">exp1</em>)!</code>. The |
| difference is that the default value with |
| <code class="inline-code">if_exists</code> is not only empty string, empty |
| sequence and empty hashs at the same time, but also boolean |
| <code class="inline-code">false</code> and a transform that does nothing and |
| ignores all parameters.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">web_safe</code>: the same as <a href="#ref_builtin_html"><code>html</code></a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_oldmacro">Old-style macro and call directives</h4> |
| |
| |
| <a name="ref.directive.oldmacro"></a> |
| |
| <a name="ref.directive.call"></a> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_127">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code"><#macro <em class="code-color">name</em>(<em class="code-color">argName1</em>, <em class="code-color">argName2</em>, <em class="code-color">... argNameN</em>)> |
| ... |
| </#macro></code> |
| |
| <code class="inline-code"><#call <em class="code-color">name</em>(<em class="code-color">argValue1</em>, <em class="code-color">argValue2</em>, <em class="code-color">... argValueN</em>)></code></pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">name</em></code>: name |
| of the macro (not expression) |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">argName1</em></code>, |
| <code class="inline-code"><em class="code-color">argName2</em></code>, ...etc.: |
| the name of the <a href="#dgui_misc_var">local |
| variables</a> store the parameter values (not |
| expression) |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">argValue1</em></code>, |
| <code class="inline-code"><em class="code-color">argValue2</em></code>, |
| ...etc.: expressions, the value of the parameters |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_128">Description</h5> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This is the documentation of FreeMarker 2.1 macro and macro |
| related directives. These are still working, but deprecated. You |
| may want to read the FreeMarker 2.2+ references: <a href="#ref.directive.macro">macro, return</a>, <a href="#ref.directive.userDefined">user-defined directive |
| call</a></p> |
| </div> |
| |
| |
| <p>A macro is a template fragment with an associated name. You |
| can use that named fragment on multiple places in your template, so |
| it helps in repetitive tasks. A macro can have parameters that |
| influence the output generated when you use the macro.</p> |
| |
| <p>You define a macro with the <code class="inline-code">macro</code> |
| directive, and then you can use the defined macro in the whole |
| template. The <code class="inline-code">macro</code> directive itself does not |
| write anything to the output, it just defines the macro. For example |
| this will define a macro called <code class="inline-code">warning</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><strong><#macro warning(message)></strong> |
| <div align=center> |
| <table border=1 bgcolor=yellow width="80%"><tr><td align=center> |
| <b>Warning!</b> |
| <p>${message} |
| </td></tr></table> |
| </div> |
| <strong></#macro></strong></pre></div> |
| |
| <p>The macro definition body (the section between the macro |
| start-tag and end-tag) will be processed whenever you use the |
| <code class="inline-code">call</code> directive with the name of the macro. For |
| example this calls the macro called |
| <code class="inline-code">warning</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#call warning("Unplug the machine before opening the cover!")></pre></div> |
| |
| <p>and will write this to the output:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"> <div align=center> |
| <table border=1 bgcolor=yellow width="80%"><tr><td align=center> |
| <b>Warning!</b> |
| <p>Unplug the machine before opening the cover! |
| </td></tr></table> |
| </div> |
| </pre></div> |
| |
| <p>The parameters passed in as parameters to the |
| <code class="inline-code">call</code> directive will be accessible in the macro |
| definition body as <a href="#dgui_misc_var">local |
| variables</a>.</p> |
| |
| <p>When you call a macro, you must specify the same number of |
| parameters as were specified in the macro definition. For example if |
| this is the macro definition:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test(a, b, c)>Nothing...</#macro></pre></div> |
| |
| <p>then these are valid macro calls:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#call test(1, 2, 3)> |
| <#call test("one", 2 + x, [1234, 2341, 3412, 4123])></pre></div> |
| |
| <p>If a macro has no parameters, then you can omit the |
| parentheses:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#macro test>mooo</#macro> |
| <#call test></pre></div> |
| |
| <p>When you define a macro it will be available in the template, |
| where you have defined it only. But probably you want to use the |
| same macros in more templates. In this case you can store your macro |
| definitions in a common file, and then include that file in all |
| templates where you need those macros.</p> |
| |
| <p>It's fine to call a macro that's defined further down in the |
| template <span class="marked-for-programmers">(since macros are defined at |
| parse time, not in process time)</span>. However, if the macro |
| definitions are inserted with <code class="inline-code">include</code> directive, |
| they will not be available until FreeMarker has executed the |
| <code class="inline-code">include</code> directive.</p> |
| |
| <p>You can leave a macro definition body before the |
| <code class="inline-code"></#macro></code> tag with the |
| <code class="inline-code">return</code> directive.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_transform">Transform directive</h4> |
| |
| |
| <a name="ref.directive.transform"></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_129">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><transform <em class="code-color">transVar</em>> |
| <em class="code-color">...</em> |
| </transform></code> |
| or |
| <code class="inline-code"><transform <em class="code-color">transVar</em> <em class="code-color">name1</em>=<em class="code-color">value1</em> <em class="code-color">name2</em>=<em class="code-color">value2</em> <em class="code-color">...</em> <em class="code-color">nameN</em>=<em class="code-color">valueN</em>> |
| <em class="code-color">...</em> |
| </transform></code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">transVar</em></code>: |
| Expression evaluates to a transform |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">name1</em></code>, |
| <code class="inline-code"><em class="code-color">name2</em></code>, ... |
| <code class="inline-code"><em class="code-color">nameN</em></code>: Name of |
| parameters. Literal value, not expression. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">value1</em></code>, |
| <code class="inline-code"><em class="code-color">value2</em></code>, ... |
| <code class="inline-code"><em class="code-color">valueN</em></code>: |
| Expressions evaluate to the values of parameters |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_130">Description</h5> |
| |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>This directive is still working, but deprecated. You may |
| want to read about <a href="#ref.directive.userDefined">user-defined directive |
| calls</a> to see the replacement.</p> |
| </div> |
| |
| |
| <p>Captures the output generated inside its body (i.e. between |
| its start-tag and end-tag), and let the given transform modify it |
| before it is written to the final output.</p> |
| |
| <p>Example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><p>A very simple HTML file: |
| <pre> |
| <strong><transform html_escape></strong> |
| <html> |
| <body> |
| <p>Hello word! |
| </body> |
| </html> |
| <strong></transform></strong> |
| </pre></pre></div> |
| |
| <p>the output will be:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-output"><p>A very simple HTML file: |
| <pre> |
| &lt;html&gt; |
| &lt;body&gt; |
| &lt;p&gt;Hello word! |
| &lt;/body&gt; |
| &lt;/html&gt; |
| </pre></pre></div> |
| |
| <p>Some transforms may take parameters. The name and meaning of |
| parameters depends on the transform in question. For example here we |
| give a parameter called ``var'':</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#-- This transform stores the output in the variable x, |
| rather than sending it to the output --> |
| <transform capture_output<strong> var="x"</strong>> |
| some test |
| </transform></pre></div> |
| |
| <p>It is the task of the programmers to put the necessary |
| transforms into the data-model. For the name and usage of accessible |
| transforms ask the programmers. <span class="marked-for-programmers">Initially there is a <a href="#pgui_config_sharedvariables">shared variable</a> for |
| most transforms in the |
| <code class="inline-code">freemarker.template.utility</code> package. For more |
| information see: <a href="#pgui_config_sharedvariables">Programmer's Guide/The Configuration/Shared variables</a></span></p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_oldsyntax">Old FTL syntax</h4> |
| |
| |
| |
| |
| |
| |
| |
| |
| <p>With the old FTL syntax the <code class="inline-code">#</code> was not |
| required (prior 2.1 not even allowed) in the FTL tags. For example, |
| you could write this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><html> |
| <head> |
| <title>Welcome!</title> |
| </head> |
| <body> |
| <h1>Welcome ${user}!</h1> |
| <p>We have there animals: |
| <ul> |
| <strong><list animals as being></strong> |
| <li>${being.name} for ${being.price} Euros |
| <strong></list></strong> |
| </ul> |
| <strong><include "common_footer.html"></strong> |
| </body> |
| </html></pre></div> |
| |
| <p>While the <code class="inline-code">#</code>-less syntax was more natural for |
| HTML authors, it had too many drawbacks, so finally we have decided to |
| deprecate it. With the newer syntax (a.k.a ``strict syntax''), the |
| <code class="inline-code">#</code> is strictly required. That is, things like |
| <code class="inline-code"><include "common_footer.html"></code> will go to the |
| output as is, since they are not considered as FTL tags. Note that |
| user-defined directives use <code class="inline-code">@</code> <em>instead |
| of</em> <code class="inline-code">#</code>.</p> |
| |
| <p>However, to give users time to prepare for this change, in |
| FreeMarker 2.1 and 2.2 the usage of <code class="inline-code">#</code> is optional, |
| unless the programmer enables strict syntax mode in the FreeMarker |
| configuration by calling <code class="inline-code">setStrictSyntaxMode(true)</code> |
| on <code class="inline-code">Configuration</code>. In fact, we strongly recommend |
| this to programmers. Starting from some later release this setting |
| will be initially set to <code class="inline-code">true</code>. Also, you can |
| specify if you want to use strict syntax or old syntax in the template |
| files with the <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a>.</p> |
| |
| <p>The advantages of ``strict syntax'' over the legacy FTL syntax |
| are:</p> |
| |
| <ul> |
| <li> |
| <p>Since all |
| <code class="inline-code"><#<em class="code-color">...</em>></code> and |
| <code class="inline-code"></#<em class="code-color">...</em>></code> are |
| reserved for FTL:</p> |
| |
| <ul> |
| <li> |
| <p>We can introduce new directives without breaking |
| backward compatibility.</p> |
| </li> |
| |
| <li> |
| <p>We can detect if you made a typo, i.e. |
| <code class="inline-code"><#inculde |
| <em class="code-color">...</em>></code> is treated as |
| parse-time error, rather than silently treated as simple |
| text.</p> |
| </li> |
| |
| <li> |
| <p>It is easier for third-party tools to handle templates |
| (e.g. do syntax highlighting), especially since they don't |
| have to know about the new directives introduced with new |
| releases.</p> |
| </li> |
| |
| <li> |
| <p>Templates are more readable, since it is easier to spot |
| <code class="inline-code"><#...></code> tags embedded into HTML or |
| other markup.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"><#</code> and <code class="inline-code"></#</code> is |
| illegal XML (except in CDATA sections), and illegal in almost all |
| other SGML applications, so they can't interfere with the tags |
| used in the static text parts (e.g. if you have |
| <code class="inline-code">include</code> element in the generated XML).</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="ref_depr_numerical_interpolation">#{...}: Numerical interpolation</h4> |
| |
| |
| |
| |
| <p>Deprecated: Use the <a href="#ref.setting.number_format"><code>number_format</code> |
| setting</a> and <a href="#ref_builtin_string_for_number">the |
| <code>string</code> built-in</a> instead. For formatting for |
| computer audience (i.e., no localized formatting) use the <a href="#ref_builtin_c"><code>c</code> built-in</a> (like |
| <code class="inline-code"><em class="code-color">number</em>?c</code>).</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_131">Synopsis</h5> |
| |
| |
| |
| <pre class="metaTemplate"><code class="inline-code">#{<em class="code-color">expression</em>}</code> |
| or |
| <code class="inline-code">#{<em class="code-color">expression</em>; <em class="code-color">format</em>}</code></pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">expression</em></code>: |
| expression that can be evaluated as a number. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">format</em></code>: |
| optional format specifier. |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_132">Description</h5> |
| |
| |
| <p>The numerical interpolation is used to output a number value. |
| If the expression doesn't evaluate to a number, the evaluation ends |
| with an error.</p> |
| |
| <p>The optional format specifier specifies the minimum and the |
| maximum number of displayed fractional digits using syntax |
| <code class="inline-code">m<em class="code-color">min</em>M<em class="code-color">max</em></code>. |
| For example, <code class="inline-code">m2M5</code> means "at least two, at most |
| five fractional digits". The minimum or the maximum specifier part |
| can be omitted. If only the minimum is specified, the maximum is |
| equal to the minimum. If only maximum is specified, the minimum is |
| 0.</p> |
| |
| <p>The decimal separator character of the output is |
| internationalized (according the current locale setting), which |
| means that it is not necessarily a dot.</p> |
| |
| <p>Unlike <code class="inline-code">${...}</code>, <code class="inline-code">#{...}</code> |
| ignores the <a href="#ref.setting.number_format"><code>number_format</code> |
| setting</a>. This is actually a backward compatibility quirk, but |
| it can be useful when you print numbers in situations like |
| <code class="inline-code"><a href="quertyDatabase?id=#{id}"></code>, where |
| you surely don't want grouping separators or something fancy like |
| that. However, starting from FreeMarker 2.3.3 rather use the <a href="#ref_builtin_c"><code>?c</code> built-in</a> for |
| this purpose, like <code class="inline-code"><a |
| href="quertyDatabase?id=${id?c}"></code>.</p> |
| |
| <p>Examples. Assume that <code class="inline-code">x</code> is |
| <code class="inline-code">2.582</code> and <code class="inline-code">y</code> is |
| <code class="inline-code">4</code>:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> <#-- If the language is US English the output is: --> |
| #{x} <#-- 2.582 --> |
| #{y} <#-- 4 --> |
| #{x; M2} <#-- 2.58 --> |
| #{y; M2} <#-- 4 --> |
| #{x; m1} <#-- 2.6 --> |
| #{y; m1} <#-- 4.0 --> |
| #{x; m1M2} <#-- 2.58 --> |
| #{y; m1M2} <#-- 4.0 --></pre></div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-part" id="app">Appendixes</h2> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="app_faq">FAQ</h3> |
| |
| |
| |
| |
| <div class="qandaset"> |
| |
| <ol> |
| <li> |
| <a href="#faq_jsp_vs_freemarker"> |
| |
| JSP versus FreeMarker? |
| |
| |
| </a> |
| </li> |
| <li> |
| <a href="#faq_jsp_vs_velocity"> |
| |
| Velocity versus FreeMarker? |
| |
| |
| </a> |
| </li> |
| <li> |
| <a href="#faq_picky_about_missing_vars"> |
| |
| Why is FreeMarker so picky about <code class="inline-code">null</code>-s |
| and missing variables, and what to do with it? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_4"> |
| |
| The documentation writes about feature |
| <em>X</em>, but it seems that FreeMarker doesn't |
| know that, or it behaves in a different way as documented, or a |
| bug that was supposedly fixed is still present. |
| </a> |
| </li> |
| <li> |
| <a href="#faq_number_grouping"> |
| |
| Why does FreeMarker print the numbers with strange |
| formatting (as 1,000,000 or 1 000 000 instead of 1000000)? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_number_decimal_point"> |
| |
| Why does FreeMarker print bad decimal and/or grouping |
| separator symbol (as 3.14 instead of 3,14)? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_number_boolean_formatting"> |
| |
| Why does FreeMarker give an error when I try to print a |
| boolean like <code class="inline-code">${aBoolean}</code>, and how to fix |
| it? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_alternative_syntax"> |
| |
| The <code class="inline-code"><</code> and <code class="inline-code">></code> of |
| FreeMarker tags confuses my editor or the XML parser. What to |
| do? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_legal_variable_names"> |
| |
| What are the legal variable names? |
| |
| |
| </a> |
| </li> |
| <li> |
| <a href="#faq_strange_variable_name"> |
| |
| How can I use variable (macro) names that contain space, |
| dash or other special characters? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_11"> |
| |
| Why do I get "java.lang.IllegalArgumentException: argument |
| type mismatch" when I try to use <em>X</em> JSP |
| custom tag? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_servlet_include"> |
| |
| How to include other resources in a way as |
| <code class="inline-code">jsp:include</code> does it? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_13"> |
| |
| How can I get the parameters to my |
| plain-Java-method/<code class="inline-code">TemplateMethodModelEx</code>/<code class="inline-code">TemplateTransformModel</code>/<code class="inline-code">TemplateDirectiveModel</code> |
| implementation as plain |
| <code class="inline-code">java.lang.*</code>/<code class="inline-code">java.util.*</code> |
| objects? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_14"> |
| |
| Why I can't use non-string key in the |
| <code class="inline-code">myMap[myKey]</code> expression? And what to do |
| now? |
| |
| |
| </a> |
| </li> |
| <li> |
| <a href="#faq_simple_map"> |
| |
| When I list the contents of a map (a hash) with |
| <code class="inline-code">?keys</code>/<code class="inline-code">?values</code>, I get the |
| <code class="inline-code">java.util.Map</code> methods mixed with the real map |
| entries. Of course, I only want to get the map entries. |
| </a> |
| </li> |
| <li> |
| <a href="#faq_modify_seq_and_map"> |
| |
| How can I modify sequences (lists) and hashes (maps) in |
| FreeMarker templates? |
| |
| |
| |
| |
| |
| |
| |
| |
| </a> |
| </li> |
| <li> |
| <a href="#faq_null"> |
| |
| What about <code class="inline-code">null</code> and the FreeMarker |
| template language? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_18"> |
| |
| How can I use the output of a directive (macro) in |
| expressions (as a parameter to another directive)? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_19"> |
| |
| Why do I have ``?''-s in the output instead of character |
| <em>X</em>? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_20"> |
| |
| How to retrieve values calculated in templates after |
| template execution done? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_implement_function_or_macro_in_java"> |
| |
| How to implement a function or macro in Java Language |
| instead of in the template language? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_22"> |
| |
| Why is FreeMarker logging suppressed for my |
| application? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_23"> |
| |
| In my Servlet |
| based application, how do I show a nice error page instead of a |
| stack trace when error occurs during template processing? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_24"> |
| |
| I'm using a visual HTML editor that mangles template tags. |
| Will you change the template language syntax to accommodate my |
| editor? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_25"> |
| |
| How fast is FreeMarker? Is it true that 2.x is slower than |
| 1.x (FreeMarker classic)? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_26"> |
| |
| How can my Java classes ask a template for information about |
| its structure (e.g. a list of all the variables)? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_27"> |
| |
| Will you ever provide backward compatibility? |
| </a> |
| </li> |
| <li> |
| <a href="#faq_question_28"> |
| |
| If we distribute FreeMarker with our product, do we have to |
| release the source code for our product? |
| </a> |
| </li> |
| </ol> |
| <dl> |
| |
| |
| |
| <dt class="question" id="faq_jsp_vs_freemarker"> |
| 1. |
| JSP versus FreeMarker? |
| |
| |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Note: JSP 1.x was really bad as an MVC template engine |
| because it was not made for that, so I don't deal with that here. |
| We compare FreeMarker with the JSP 2.0 + JSTL combo.</p> |
| |
| <p>FreeMarker Pros:</p> |
| |
| <ul> |
| <li> |
| <p>FreeMarker is not tied to Servlets, networking or the |
| Web; it is just a class library to generate text output by |
| merging a template with Java objects (the data-model). You can |
| execute templates anywhere and anytime; no HTTP request |
| forwarding or similar tricks needed, no Servlet environment |
| needed at all. Because of this you can easily integrate it |
| into any system.</p> |
| </li> |
| |
| <li> |
| <p>No servlet specific scopes and other highly technical |
| things in templates. It was made for MVC from the beginning, |
| it focuses only on the presentation.</p> |
| </li> |
| |
| <li> |
| <p>You can load the templates from anywhere; from the class |
| path, from a data-base, etc.</p> |
| </li> |
| |
| <li> |
| <p>Locale sensitive number and date formatting by default. |
| Since we mostly output for a human audience all you need to do |
| is just write <code class="inline-code">${x}</code> rather than |
| <code class="inline-code"><fmt:formatNumber value="${x}" /></code>. |
| You can easily switch this behavior and output non-localized |
| numbers by default.</p> |
| </li> |
| |
| <li> |
| <p>Easier to define ad-hoc macros and functions.</p> |
| </li> |
| |
| <li> |
| <p>No sweeping errors under the carpet. Missing variables |
| will cause an error by default, and not silently default to |
| arbitrary values. Also, <code class="inline-code">null</code>-s are not |
| treated silently as 0/false/empty string. <a href="#faq_picky_about_missing_vars">See more about this |
| here...</a></p> |
| </li> |
| |
| <li> |
| <p>``Object wrapping''. This lets you show the objects to |
| templates in a customized, presentation oriented way (e.g. |
| <a href="#xgui_imperative_learn">see here</a> how a |
| W3C DOM nodes can be seen by templates using this |
| technology.)</p> |
| </li> |
| |
| <li> |
| <p>Macros and functions are just variables (compare it to |
| how JSP custom tags work), so they can be easily passed around |
| as parameter values, put into the data-model, ...etc, just |
| like any other value.</p> |
| </li> |
| |
| <li> |
| <p>Easier to read, more terse syntax. For example: |
| <code class="inline-code"><#if x>...</#if></code> instead of |
| <code class="inline-code"><c:if |
| test="${x}">...</c:if></code></p> |
| </li> |
| |
| <li> |
| <p>Virtually unnoticeable delay when visiting a page for |
| the first time (or after it was changed), because no expensive |
| compilation happens.</p> |
| </li> |
| </ul> |
| |
| <p>FreeMarker Cons:</p> |
| |
| <ul> |
| <li> |
| <p>Not a ``standard''. There are fewer tools and IDE |
| integrations, fewer developers knows it and there's much less |
| industry support in general. (However, JSP tag libraries work |
| without modification in FreeMarker templates, if they are not |
| using <code class="inline-code">.tag</code> files.)</p> |
| </li> |
| |
| <li> |
| <p>Since macros and function are just variables, incorrect |
| directive and parameter names and missing required parameters |
| can be detected only on runtime.</p> |
| </li> |
| |
| <li> |
| <p>Its syntax doesn't follow the HTML/XML rules appart from |
| some visual similarity, which is confusing for new users. |
| (It's the price of the terseness...)</p> |
| </li> |
| |
| <li> |
| <p>Doesn't work with JSF. (It could work technically, but |
| nobody has implemented that yet.)</p> |
| </li> |
| </ul> |
| |
| <p>You may read this if you are considering replacing JSP with |
| FreeMarker: <a href="#pgui_misc_servlet_model2">Programmer's Guide/Miscellaneous/Using FreeMarker with servlets/Using FreeMarker for ``Model 2''</a></p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_jsp_vs_velocity"> |
| 2. |
| Velocity versus FreeMarker? |
| |
| |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p><a href="http://jakarta.apache.org/velocity/index.html">Velocity</a> |
| is a simpler, more lightweight tool. Thus, it does not address |
| many tasks that FreeMarker does, and its template language is less |
| powerful in general, but it is simpler; visit <a href="http://freemarker.org/fmVsVel.html">http://freemarker.org/fmVsVel.html</a> |
| for details. Currently (2005) Velocity has wider third party |
| support and larger user community.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_picky_about_missing_vars"> |
| 3. |
| Why is FreeMarker so picky about <code class="inline-code">null</code>-s |
| and missing variables, and what to do with it? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>To recapitulate what's this entry is about: FreeMarker by |
| default treats an attempt to access a non-existent variable or a |
| <code class="inline-code">null</code> value (<a href="#faq_null">this two |
| is the same for FreeMarker</a>) as error, which aborts the |
| template execution.</p> |
| |
| <p>First of all, you should understand the reason of being |
| picky. Most scripting languages and template languages are rather |
| forgiving with missing variables (and with |
| <code class="inline-code">null</code>-s), and they usually treat them as empty |
| string and/or 0 and/or logical false. This behavior has several |
| problems:</p> |
| |
| <ul> |
| <li> |
| <p>It potentially hiders accidental mistakes, like a typo |
| in a variable name, or when the template author refers to a |
| variable that the programmer doesn't put into the data-model, |
| or for which the programmer uses a different name. Human is |
| prone to do such accidental mistakes, computers are not, so |
| missing this opportunity that the template engine can show |
| these errors is a bad business. Even if you very carefully |
| check the output of the templates during development, it is |
| easy to look over mistakes like <code class="inline-code"><#if |
| hasDetp><em class="code-color">print dept |
| here...</em></#if></code>, which would then |
| silently never print the dept of the visitor, since you have |
| mistyped the variable name (it should be |
| <code class="inline-code">hasDept</code>). Also think about maintenance, |
| when you later modify your application... most probably you |
| will not re-check templates that carefully each time.</p> |
| </li> |
| |
| <li> |
| <p>Makes dangerous assumptions. The script language or |
| template engine knows nothing about the application domain, so |
| when it decides the value of something it don't know to be |
| 0/false, it is a quite irresponsible and arbitrary thing. Just |
| because it is not know what's your current bank account |
| balance, can we just say it is $0 (and how easy it is to |
| accidentally write <code class="inline-code">Balance: ${balanace}</code>)? |
| Just because it is not known if a patient has penicillin |
| allergy, we can just say he/she doesn't have (and how easy it |
| is to accidentally write <code class="inline-code"><#if |
| hasPenicilinAllergy><em class="code-color">Warning...</em><#else><em class="code-color">Allow...</em></#if></code>; |
| there is a typo in this, if you didn't see)? Just consider the |
| implications of such mistakes for a moment. They can be quite |
| severe and troubling. Showing an error page is often better |
| than showing incorrect information that formally looks |
| good.</p> |
| </li> |
| </ul> |
| |
| <p>Being not picky is mostly sweeping under the carpet in this |
| case (not facing with the problems), which of course most people |
| feels more convenient, but still... we believe that in most cases |
| being strict will save your time and increase your software |
| quality in the long run.</p> |
| |
| <p>On the other hand, we recognize that there are cases where |
| you don't want FreeMarker to be that picky with good reason, and |
| there is solution for them:</p> |
| |
| <ul> |
| <li> |
| <p>It's often normal that your data-model contains |
| <code class="inline-code">null</code>-s or have optional variables. In such |
| cases use <a href="#dgui_template_exp_missing">these |
| operators</a>. If you use them too often, try to rethink |
| your data-model, because depending on them too much is not |
| just results in awkward verbose templates, but increases the |
| probability of hiding errors and printing arbitrary incorrect |
| output (for the reasons described earlier).</p> |
| </li> |
| |
| <li> |
| <p>On a production server you may rather want to show an |
| incomplete/damaged page than an error page. In this case you |
| can <a href="#pgui_config_errorhandling">use other error |
| handler</a> than the default. Error handlers can be made |
| that rather skip the problematic part than abort the whole |
| page rendering. Note, however, that although the error |
| handlers don't give arbitrary default values to variables, for |
| pages that show critical information it's maybe still better |
| to show an error page. (Another feature you may interested in: |
| <a href="#ref_directive_attempt">the |
| <code>attempt</code>/<code>recover</code> |
| directives</a>)</p> |
| </li> |
| </ul> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 4. |
| The documentation writes about feature |
| <em>X</em>, but it seems that FreeMarker doesn't |
| know that, or it behaves in a different way as documented, or a |
| bug that was supposedly fixed is still present. |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Are you sure that you are using the documentation written |
| for the same version of FreeMarker that you actually use? |
| Especially, note that our online documentation is for the latest |
| usable FreeMarker release. You may use an older release.</p> |
| |
| <p>Are you sure that the Java class loader finds the same |
| <code class="inline-code">freemarker.jar</code> that you expect to use? Maybe |
| there is an older version of <code class="inline-code">freemarker.jar</code> |
| around (such as in the Ant <code class="inline-code">lib</code> directory), |
| which has higher priority. To check this, try to print the version |
| number in a template with <code class="inline-code">${.version}</code>. If it |
| dies with ``Unknown built-in variable: version'' error message, |
| then you use a release before 2.3-final or 2.2.8, but you can |
| still try to get the version number in the Java code of your |
| application with |
| <code class="inline-code">Configuration.getVersionNumber()</code>. If this |
| method is not present either, then you are using an early |
| 2.3-preview, or a version before 2.2.6.</p> |
| |
| <p>If you think that the documentation or FreeMarker is wrong, |
| please report it using the bug tracker, or the mailing list, or |
| the forums on <a href="http://sourceforge.net/projects/freemarker/">http://sourceforge.net/projects/freemarker/</a>. |
| Thank you!</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_number_grouping"> |
| 5. |
| Why does FreeMarker print the numbers with strange |
| formatting (as 1,000,000 or 1 000 000 instead of 1000000)? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>FreeMarker uses the locale-sensitive number formatting |
| capability of the Java platform. The default number format for |
| your locale may uses grouping or other unwanted formatting. To |
| prevent this, you have to override the number format suggested by |
| the Java platform with the <code class="inline-code">number_format</code> <a href="#pgui_config_settings">FreeMarker setting</a>. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setNumberFormat("0.######"); // now it will print 1000000 |
| // where cfg is a freemarker.template.Configuration object</pre></div> |
| |
| <p>Note however than humans often find it hard to read big |
| numbers without grouping separator. So in general it is |
| recommended to keep them, and in cases where the numbers are for |
| ''computer audience'' that is confused on the grouping separators, |
| use the <a href="#ref_builtin_c"><code>c</code> |
| built-in</a>. For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><a href="/shop/productdetails?id=${<strong>product.id?c</strong>}">Details...</a></pre></div> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_number_decimal_point"> |
| 6. |
| Why does FreeMarker print bad decimal and/or grouping |
| separator symbol (as 3.14 instead of 3,14)? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Different countries use different decimal/grouping separator |
| symbols. If you see incorrect symbols, then probably your locale |
| is not set properly. Set the default locale of the JVM or override |
| the default locale with the <code class="inline-code">locale</code> <a href="#pgui_config_settings">FreeMarker setting</a>. For |
| example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">cfg.setLocale(java.util.Locale.ITALY); |
| // where cfg is a freemarker.template.Configuration object</pre></div> |
| |
| <p>However, sometimes you want to output a number not for human |
| audience, but for ``computer audience'' (like you want to print a |
| size in CSS), in which case you must use dot as decimal separator, |
| regardless of the locale (language) of the page. For that use the |
| <a href="#ref_builtin_c"><code>c</code> |
| built-in</a>, for example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">font-size: ${<strong>fontSize?c</strong>}pt;</pre></div> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_number_boolean_formatting"> |
| 7. |
| Why does FreeMarker give an error when I try to print a |
| boolean like <code class="inline-code">${aBoolean}</code>, and how to fix |
| it? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Unlike numbers, booleans has no commonly accepted format, |
| not even a common format within the same page. Like when you show |
| on a HTML page if a product is washable, you will hardly want to |
| show for the visitor "Washable: true", but rather "Washable: yes". |
| So we force the template author (by <code class="inline-code">${washable}</code> |
| causing error) to find out with his human knowledge how the |
| boolean value should be shown at the given place. The common way |
| of formatting a boolean is like <code class="inline-code">${washable?string("yes", |
| "no")}</code>, <code class="inline-code">${caching?string("Enabled", |
| "Disabled")}</code>, <code class="inline-code">${heating?string("on", |
| "off")}</code>, etc. However, for generating source code |
| <code class="inline-code">${washable?string("true", "false")}</code> would be |
| very often used, so <code class="inline-code">${washable?string}</code> (i.e., |
| omitting the parameter list) is equivalent with that.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_alternative_syntax"> |
| 8. |
| The <code class="inline-code"><</code> and <code class="inline-code">></code> of |
| FreeMarker tags confuses my editor or the XML parser. What to |
| do? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Starting from FreeMarker 2.3.4 you can use |
| <code class="inline-code">[</code> and <code class="inline-code">]</code> instead of |
| <code class="inline-code"><</code> and <code class="inline-code">></code>. For more |
| details <a href="#dgui_misc_alternativesyntax">read |
| this...</a></p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_legal_variable_names"> |
| 9. |
| What are the legal variable names? |
| |
| |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>FreeMarker has no limitations regarding the characters used |
| in variable names, nor regarding the length of the variable names, |
| but for your convenience try to chose variable names that can be |
| used with the simple variable reference expressions (see it <a href="#dgui_template_exp_var_toplevel">here</a>). If you have |
| to choose a more extreme variable name, that's not a bid problem |
| either: <a href="#faq_strange_variable_name">see |
| here</a>.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_strange_variable_name"> |
| 10. |
| How can I use variable (macro) names that contain space, |
| dash or other special characters? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>If you have a variable with strange name, such as |
| <code class="inline-code">foo-bar</code>, FreeMarker will misinterpret what do |
| you want when you write thing as <code class="inline-code">${foo-bar}</code>. In |
| this concrete case, it will believe that you want subtract the |
| value of <code class="inline-code">bar</code> from <code class="inline-code">foo</code>. This |
| FAQ entry explains how to handle situations like this.</p> |
| |
| <p>First of all it should be clean that these are just |
| syntactical problems. FreeMarker has no limitations regarding the |
| characters used in variable names, nor regarding the length of the |
| variable names, but sometimes you need to use syntactical |
| tricks.</p> |
| |
| <p>If you want to read the variable: Use the square bracket |
| syntax. An example of square bracket syntax is |
| <code class="inline-code">baaz["foo"]</code>, which is equivalent with |
| <code class="inline-code">baaz.foo</code>. As the subvariable name with the |
| square bracket syntax is a string literal (in fact, arbitrary |
| expression), it let you write <code class="inline-code">baaz["foo-bar"]</code>. |
| Now you may say that it can be used for hash subvariables only. |
| Yes, but top-level variables are accessible through special hash |
| variable <code class="inline-code">.vars</code>. For example, |
| <code class="inline-code">foo</code> is equivalent with |
| <code class="inline-code">.vars["foo"]</code>. So you can also write |
| <code class="inline-code">.vars["foo-bar"]</code>. Naturally, this trick works |
| with macro invocations too: |
| <code class="inline-code"><@.vars["foo-bar"]/></code></p> |
| |
| <p>If you want to create or modify the variable: All directives |
| that let you create or modify a variable (such as |
| <code class="inline-code">assign</code>, <code class="inline-code">local</code>, |
| <code class="inline-code">global</code>, <code class="inline-code">macro</code>, |
| <code class="inline-code">function</code>, etc.) allows the quotation of the |
| destination variable name. For example, <code class="inline-code"><#assign foo = |
| 1></code> is the same as <code class="inline-code"><#assign "foo" = |
| 1></code>. So you can write things like <code class="inline-code"><#assign |
| "foo-bar" = 1></code> and <code class="inline-code"><#macro |
| "foo-bar"></code>.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 11. |
| Why do I get "java.lang.IllegalArgumentException: argument |
| type mismatch" when I try to use <em>X</em> JSP |
| custom tag? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>On JSP pages you quote all parameter (attribute) values, it |
| does not mater if the type of the parameter is string or boolean |
| or number. But since custom tags are accessible in FTL templates |
| as plain user-defined FTL directives, you have to use the FTL |
| syntax rules inside the custom tags, not the JSP rules. Thus, |
| according to FTL rules, you must not quote boolean and numerical |
| parameter values, or they are interpreted as string values, and |
| this will cause a type mismatch error when FreeMarker tries to |
| pass the value to the custom tag that expects non-string |
| value.</p> |
| |
| <p>For example, the <code class="inline-code">flush</code> parameter to |
| Struts Tiles <code class="inline-code">insert</code> tag is boolean. In JSP the |
| correct syntax was:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><tiles:insert page="/layout.jsp" <strong>flush="true"</strong>/> |
| <em>...</em></pre></div> |
| |
| <p>but in FTL you should write:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@tiles.insert page="/layout.ftl" <strong>flush=true</strong>/> |
| <em>...</em></pre></div> |
| |
| <p>Also, for similar reasons, this is wrong:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><tiles:insert page="/layout.jsp" <strong>flush="${needFlushing}"</strong>/> |
| <em>...</em></pre></div> |
| |
| <p>and you should write:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><tiles:insert page="/layout.jsp" <strong>flush=needFlushing</strong>/> |
| <em>...</em></pre></div> |
| |
| <p>(Not <code class="inline-code">flush=${needFlushing}</code>!)</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_servlet_include"> |
| 12. |
| How to include other resources in a way as |
| <code class="inline-code">jsp:include</code> does it? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Not with <code class="inline-code"><#include ...></code>, as that |
| just includes another FreeMarker template without involving the |
| Servlet container.</p> |
| |
| <p>Since the inclusion method you look for is Servlet-related, |
| and pure FreeMarker is unaware of Servlets or even HTTP, it's the |
| Web Application Framework that decides if you can do this and if |
| so how. For example, in Struts 2 you can do this like this:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@s.include value="/WEB-INF/just-an-example.jspf" /></pre></div> |
| |
| <p>If the FreeMarker support of the Web Application Framework |
| is based on |
| <code class="inline-code">freemarker.ext.servlet.FreemarkerServlet</code>, then |
| you can also do this (since FreeMarker 2.3.15):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><@include_page path="/WEB-INF/just-an-example.jspf" /></pre></div> |
| |
| <p>but if the Web Application Framework provides its own |
| solution, then you may prefer that, after all it may does |
| something special.</p> |
| |
| <p>For more information about <code class="inline-code">include_page</code> |
| <a href="#pgui_misc_servlet_include">read |
| this...</a></p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 13. |
| How can I get the parameters to my |
| plain-Java-method/<code class="inline-code">TemplateMethodModelEx</code>/<code class="inline-code">TemplateTransformModel</code>/<code class="inline-code">TemplateDirectiveModel</code> |
| implementation as plain |
| <code class="inline-code">java.lang.*</code>/<code class="inline-code">java.util.*</code> |
| objects? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Unfortunately, there is no simple general-purpose solution |
| for this problem. The problem is that FreeMarker object wrapping |
| is very flexible, which is good when you access variables from |
| templates, but makes unwrapping on the Java side a tricky |
| question. For example, it is possible to wrap a |
| non-<code class="inline-code">java.util.Map</code> object as |
| <code class="inline-code">TemplateHashModel</code> (FTL hash variable). But |
| then, it can't be unwrapped to <code class="inline-code">java.util.Map</code>, |
| since there is no wrapped <code class="inline-code">java.util.Map</code> around |
| at all.</p> |
| |
| <p>So what to do then? Basically there are two cases:</p> |
| |
| <ul> |
| <li> |
| <p>Directives and methods that are written for presentation |
| purposes (like kind of ``tools'' for helping FreeMarker |
| templates) should declare their arguments as |
| <code class="inline-code">TemplateModel</code>-s and the more specific sub |
| interfaces of that. After all, the object wrapping is about |
| apparently transforming the data-model to something that |
| serves the purpose of the presentation layer, and these |
| methods are part of the presentation layer.</p> |
| </li> |
| |
| <li> |
| <p>Methods that are not for presentation related tasks (but |
| for business logic and like) should be implemented as plain |
| Java methods, and should not use any FreeMarker specific |
| classes at all, since according the MVC paradigm they must be |
| independent of the presentation technology (FreeMarker). If |
| such a method is called from a template, then it is the |
| responsibility of the <a href="#pgui_datamodel_objectWrapper">object wrapper</a> |
| to ensure the conversion of the arguments to the proper type. |
| If you use the <code class="inline-code">DefaultObjectWrapper</code> or the |
| <a href="#pgui_misc_beanwrapper"><code>BeansWrapper</code></a> |
| then this will happen automatically (but be sure you are using |
| at least FreeMarker 2.3.3). Furthermore if you use |
| <code class="inline-code">BeansWrapper</code>, then the method will surely |
| get exactly the same instance that was earlier wrapped (as far |
| as it was wrapped by the |
| <code class="inline-code">BeansWrapper</code>).</p> |
| </li> |
| </ul> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 14. |
| Why I can't use non-string key in the |
| <code class="inline-code">myMap[myKey]</code> expression? And what to do |
| now? |
| |
| |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>The ``hash'' type of the FreeMarker Template Language (FTL) |
| is not the same as Java's <code class="inline-code">Map</code>. FTL's hash is an |
| associative array too, but it uses string keys exclusively. This |
| is because it was introduced for subvariables (as |
| <code class="inline-code">password</code> in <code class="inline-code">user.password</code>, |
| which is the same as <code class="inline-code">user["password"]</code>), and |
| variable names are strings.</p> |
| |
| <p>So FTL's hashes are not general purpose associate arrays |
| that could be used for looking up values with keys of arbitrary |
| type. FTL is presentation oriented language, and it has no feature |
| dedicated for that purpose. It has, however, methods. Methods are |
| part of the data-model, and they can do all kind of fancy |
| data-model related calculations, so of course you can add some |
| methods to the data-model for <code class="inline-code">Map</code> lookup. The |
| bad news is that the building of the data-model, as it's an |
| application specific issue, is the task of the programmers who use |
| FreeMarker, so it's their task to ensure that such methods are |
| present there to serve the template authors. (However, when |
| template authors need to call methods that are not about |
| presentation, then consider if the data-model is simple enough. |
| Maybe you should push some calculations back to the data-model |
| building phase. Ideally the data-model contains what should be |
| displayed, and not something that serves as the base of further |
| calculations.)</p> |
| |
| <p>If you read the programmer's guide, then you know that |
| technically, the data-model is a tree of |
| <code class="inline-code">freemarker.template.TemplateModel</code> objects. The |
| building of the data-model usually (but not necessary) happens by |
| automatically wrapping (enclosing) plain Java objects into |
| <code class="inline-code">TemplateModel</code> objects. The object that does |
| this wrapping is the object wrapper, and it's specified when you |
| configure FreeMarker. FreeMarker comes with a few object wrapper |
| implementations out-of-the-box, and probably the most widely used |
| of them is <a href="#pgui_misc_beanwrapper"><code>freemarker.ext.beans.BeansWrapper</code></a>. |
| If you use an instance of this as the object wrapper, then |
| <code class="inline-code">java.util.Map</code>-s you put into the data-model |
| will also act as a method, so you can write |
| <code class="inline-code">myMap(myKey)</code> in the template, that will |
| internally call <code class="inline-code">Map.get(myKey)</code>. There will be |
| no restriction regarding the type of <code class="inline-code">myKey</code>, as |
| <code class="inline-code">Map.get(Object key)</code> has no such restriction. If |
| the value of <code class="inline-code">myKey</code> was wrapped with |
| <code class="inline-code">BeansWrapper</code> or other object wrapper whose |
| wrapped objects support unwrapping, or it is given as literal in |
| the template, then the value will be automatically unwrapped to |
| plain Java object before the actual invocation of the |
| <code class="inline-code">Map.get(Object key)</code> method, so it will not be |
| invoked with <code class="inline-code">TemplateModel</code>-s.</p> |
| |
| <p>But there still will be a problem. Java's |
| <code class="inline-code">Map</code> is particular about the exact class of the |
| key, so for numerical keys calculated inside the templates you |
| will have to cast them to the proper Java type, otherwise the item |
| will not be found. For example if you use |
| <code class="inline-code">Integer</code> keys in a Map, then you have to write |
| <code class="inline-code">${myMap.get(123?int)}</code>. This is an ugly effect |
| caused by that FTL's deliberately simplified type system just has |
| a single numerical type, while Java distinguishes a lot of |
| numerical types. (Ideally, in the above case, the programmers |
| ensure that the <code class="inline-code">get</code> method automatically |
| converts the key to <code class="inline-code">Integer</code>, so it's not the |
| problem of the template author. This can be done with wrapper |
| customization, but the wrapper has to know that the particular |
| <code class="inline-code">Map</code> object uses <code class="inline-code">Integer</code> |
| keys, which assumes application specific knowledge.) Note that the |
| casting is not needed when the key value comes directly from the |
| data-model (i.e. you didn't modified its value with arithmetical |
| caluclations in the template), including the case when it's the |
| return value of a method, and it was of the proper class before |
| wrapping, because then the result of the unwrapping will be of the |
| original type.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_simple_map"> |
| 15. |
| When I list the contents of a map (a hash) with |
| <code class="inline-code">?keys</code>/<code class="inline-code">?values</code>, I get the |
| <code class="inline-code">java.util.Map</code> methods mixed with the real map |
| entries. Of course, I only want to get the map entries. |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Certainly you are using <code class="inline-code">BeansWrapper</code> as |
| your object wrapper, or a custom subclass of it, and the |
| <code class="inline-code">simpleMapWrapper</code> property of that is left to |
| <code class="inline-code">false</code>. Unfortunatelly, it's the default (for |
| backward compatibility), so you have to explicitly set it to |
| <code class="inline-code">true</code> where you create the object |
| wrapper.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_modify_seq_and_map"> |
| 16. |
| How can I modify sequences (lists) and hashes (maps) in |
| FreeMarker templates? |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>First of all, you may don't want to modify the |
| sequence/hash, just concatenate (add) two or more of them, which |
| results in a new sequence/hash, rather than modifying an existing |
| one. In this case use the <a href="#dgui_template_exp_sequenceop_cat">sequence |
| concatenation</a> and <a href="#dgui_template_exp_hashop_cat">hash concatenation |
| operators</a>. Also, you may use the <a href="#dgui_template_exp_seqenceop_slice">subsequence |
| operator</a> instead of removing sequence items. However, be |
| aware of the performance implications: these operations are fast, |
| but the hashes/sequences that are the result of many subseqent |
| applications of these operations (i.e. when you use the result of |
| the operation as the input of yet another operation, and so on) |
| will be slow to read.</p> |
| |
| <p>Now if you still want to modify sequences/hashes, then read |
| on...</p> |
| |
| <p>The FreeMarkes Template Language doesn't support the |
| modification of sequences/hashes. It's for displaying already |
| calculated things, not for calculating data. Keep templates |
| simple. But don't give it up, you will see some advices and tricks |
| bellow.</p> |
| |
| <p>The best is if you can divide the work between the |
| data-model builder program and the template so that the template |
| doesn't need to modify sequences/hashes. Maybe if you rethink your |
| data-model, you will realize this is possible. But, seldom there |
| are cases where you need to modify sequences/hashes for some |
| complex but purely presentation related algorithms. It seldom |
| happens, so think twice whether that calculation (or parts of it) |
| rather belongs to the data-model domain than to the presentation |
| domain. Let's assume you are sure it belongs to the presentation |
| domain. For example, you want to display a keyword index on some |
| very smart way, whose algorithm need you to create and write some |
| sequence variables. Then you should do something like this (ugly |
| situations has ugly solutions...):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign caculatedResults = |
| 'com.example.foo.SmartKeywordIndexHelper'?new().calculate(keywords)> |
| <#-- some simple algorithms comes here, like: --> |
| <ul> |
| <#list caculatedResults as kw> |
| <li><a href="${kw.link}">${kw.word}</a> |
| </#list> |
| </ul></pre></div> |
| |
| <p>That is, you move out the complex part of the presentation |
| task from the template into Java code. Note that it doesn't affect |
| the data-model, so the presentation is still kept separated from |
| other the other application logic. Of course the drawback is that |
| for this the template author will need the help of a Java |
| programmer, but for complex algorithms that's probably needed |
| anyway.</p> |
| |
| <p>Now, if you still say you need to modify sequences/hashes |
| directly with the FreeMarker template, here are two solutions, but |
| please read the warning after them:</p> |
| |
| <ul> |
| <li> |
| <p>You can write a <code class="inline-code">TemplateMethodModelEx</code> |
| and <code class="inline-code">TemplateDirectiveModel</code> implementation |
| that can modify certain types of sequences/hashes. Just |
| certain types, because |
| <code class="inline-code">TemplateSequenceModel</code> and |
| <code class="inline-code">TemplateHashModel</code> doesn't have methods for |
| modification, so you will need the sequence or hash to |
| implement some additional methods. An example of this solution |
| can be seen in FMPP. It allows you to do things like this |
| (<code class="inline-code">pp</code> stores the services provided by FMPP |
| for templates):</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign a = pp.newWritableSequence()> |
| <@pp.add seq=a value="red" /></pre></div> |
| |
| <p>The <code class="inline-code">pp.add</code> directive works only with |
| sequences that were created with |
| <code class="inline-code">pp.newWritableSequence()</code>. So for example |
| the template author can't modify a sequence that comes from |
| the data-model with this.</p> |
| </li> |
| |
| <li> |
| <p>A sequence can have some methods/directives if you use a |
| customized wrapper (so you can <code class="inline-code"><@myList.append foo |
| /></code>). (Also, if you use |
| <code class="inline-code">BeansWrapper</code> and configure it so it exposes |
| the public methods, you can use the Java API for variables |
| that are for <code class="inline-code">java.util.Map</code>-s and |
| <code class="inline-code">java.util.List-s</code>. Just like with Apache |
| Velocity.)</p> |
| </li> |
| </ul> |
| |
| <p>But beware, these solutions have a problem: The <a href="#dgui_template_exp_sequenceop_cat">sequence |
| concatenation</a>, <a href="#dgui_template_exp_seqenceop_slice">sequence slice</a> |
| operator (like <code class="inline-code">seq[5..10]</code>) and |
| <code class="inline-code">?reverse</code> do not copy the original sequence, |
| just wraps it (for efficiency), so the resulting sequence will |
| change if the original sequence is changed later (an abnormal |
| aliasing effect). The same problem exists with the result of <a href="#dgui_template_exp_hashop_cat">hash concatenation</a>; |
| it just wraps the two hashes, so the resulting hash will magically |
| change if you modify the hashes you have added earlier. As a |
| work-around, after you did the above problematic operations, |
| either be sure you will not modify the objects that were used as |
| input, or create a copy of the result with a method provided by |
| the solution described in above two points (e.g. in FMPP you could |
| do <code class="inline-code"><#assign b = |
| pp.newWritableSequence(a[5..10])></code> and |
| <code class="inline-code"><#assign c = pp.newWritableHash(hashA + |
| hashB)></code>). Of course this is easy to miss... so again, |
| rather try to build the data-model so you will not need to modify |
| collections, or use a presentation task helper class as was shown |
| earlier.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_null"> |
| 17. |
| What about <code class="inline-code">null</code> and the FreeMarker |
| template language? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>The FreeMarker template language doesn't know the Java |
| language <code class="inline-code">null</code> at all. It doesn't have |
| <code class="inline-code">null</code> keyword, and it can't test if something is |
| <code class="inline-code">null</code> or not. When it technically faces with a |
| <code class="inline-code">null</code>, it treats it exactly as a missing |
| variable. For example, both if <code class="inline-code">x</code> is |
| <code class="inline-code">null</code> in the data-model and if it's not present |
| at all, <code class="inline-code">${x!'missing'}</code> will print ``missing'', |
| you can't tell the difference. Also, if for example you want to |
| test if a Java method has returned <code class="inline-code">null</code>, just |
| write something like <code class="inline-code"><#if |
| foo.bar()??></code>.</p> |
| |
| <p>You may interested in the rationale behind this. From the |
| viewpoint of the presentation layer a <code class="inline-code">null</code> and |
| non-existent thing is almost always the same. The difference |
| between this two is usually just a technical detail, which is |
| rather the result of implementation details than of the |
| application logic. That you can't compare something to |
| <code class="inline-code">null</code> (unlike in Java); it doesn't make sense to |
| compare something with <code class="inline-code">null</code> in a template, |
| since the template language doesn't do identity comparison (like |
| the Java <code class="inline-code">==</code> operator when you compare two |
| objects) but the more common sense value comparison (like Java's |
| <code class="inline-code">Object.equals(Object)</code>; that doesn't work with |
| <code class="inline-code">null</code> either). And how could FreeMarker tell if |
| something concrete equals with something that is missing and thus |
| unknown? Or if two missing (unknown) things are equal? Of course |
| these questions can't be answered.</p> |
| |
| <p>There is at least one problem with this |
| <code class="inline-code">null</code>-unaware approach. When you call a Java |
| method from a template, you may want to pass a |
| <code class="inline-code">null</code> value as argument (since the method was |
| designed to be used in Java language, where the concept of |
| <code class="inline-code">null</code> is known). In this case you can exploit a |
| bug of FreeMarker (that we will not fix until we provide a correct |
| solution for passing <code class="inline-code">null</code> values to a method): |
| if you specify a missing variable as the argument, then it will |
| not cause an error, but a <code class="inline-code">null</code> will be passed |
| to the method instead. Like <code class="inline-code">foo.bar(nullArg)</code> |
| will call the <code class="inline-code">bar</code> method with |
| <code class="inline-code">null</code> as argument, assuming that there is no |
| varaible exists with ``nullArg'' name.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 18. |
| How can I use the output of a directive (macro) in |
| expressions (as a parameter to another directive)? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>Capture the output into a variable with the |
| <code class="inline-code">assign</code> or <code class="inline-code">local</code> directive. |
| For example:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#assign capturedOutput><@outputSomething /></#assign> |
| <@otherDirective someParam=capturedOutput /></pre></div> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 19. |
| Why do I have ``?''-s in the output instead of character |
| <em>X</em>? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>This is because the character that you want to print can't |
| be represented with the <a href="#gloss.charset">charset</a> (encoding) used for the |
| output stream, so the Java platform (not FreeMarker) substitutes |
| the problematic character with question mark. In general you |
| should use the same charset for the output as for the template |
| (use the <code class="inline-code">getEncoding()</code> method of the template |
| object), or which is even safer, you should always use UTF-8 |
| charset for the output. The charset used for the output stream is |
| not decided by FreeMarker, but by you, when you create the |
| <code class="inline-code">Writer</code> that you pass to the |
| <code class="inline-code">process</code> method of the template.</p> |
| |
| <p>Example: Here I use UTF-8 charset in a servlet:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">... |
| resp.setContentType("text/html; charset=utf-8"); |
| Writer out = resp.getWriter(); |
| ... |
| t.process(root, out); |
| ...</pre></div> |
| |
| <p>Note that the question marks (or other substitution |
| characters) may be produced outside FreeMarker, in which case the |
| above obviously will not help. For example a bad/missconfigured |
| database connection or JDBC driver may bring the text already with |
| substitution characters in it. HTML forms are another potential |
| source of encoding problems. It's a good idea to print the |
| numerical code of the characters of the string on various places, |
| to see where the problem occurs first.</p> |
| |
| <p>You can read more about charsets and FreeMarker <a href="#pgui_misc_charset">here...</a></p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 20. |
| How to retrieve values calculated in templates after |
| template execution done? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>First of all, be sure your application is designed well: |
| templates should display data, and almost never calculate data. If |
| you are still sure you want to do it, read on...</p> |
| |
| <p>When you use <code class="inline-code"><#assign x = "foo"></code>, |
| then you do not actually modify the data-model (since that is |
| read-only, see: <a href="#pgui_misc_multithreading">Programmer's Guide/Miscellaneous/Multithreading</a>), but |
| create the <code class="inline-code">x</code> variable in the runtime <a href="#gloss.environment">environment</a> of the processing |
| (see <a href="#pgui_misc_var">Programmer's Guide/Miscellaneous/Variables</a>). The problem is that this |
| runtime environment will be discarded when |
| <code class="inline-code">Template.process</code> returns, as it was created for |
| a single <code class="inline-code">Template.process</code> call:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">// internally an Environment will be created, and then discarded |
| myTemplate.process(root, out);</pre></div> |
| |
| <p>To prevent this, you can do the below, which is equivalent |
| with the above, except that you have chance to return the |
| variables created in the template:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out); |
| env.process(); // process the template |
| TemplateModel x = env.getVariable("x"); // get variable x</pre></div> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id="faq_implement_function_or_macro_in_java"> |
| 21. |
| How to implement a function or macro in Java Language |
| instead of in the template language? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>It's not possible (yet), but something very similar is |
| possible if you write a class that implements |
| <code class="inline-code">freemarker.template.TemplateMethodModelEx</code> or |
| <code class="inline-code">freemarker.template.TemplateDirectiveModel</code> |
| respectively, and then where you were write <code class="inline-code"><#function |
| my |
| <em class="code-color">...</em>><em class="code-color">...</em></#function></code> |
| or <code class="inline-code"><#macro my |
| <em class="code-color">...</em>><em class="code-color">...</em></#macro></code> |
| you write <code class="inline-code"><#assign my = "your.package.YourClass |
| "?</code><a href="#ref_builtin_new"><code>new</code></a><code class="inline-code">()></code> |
| instead. Note that using the <code class="inline-code">assign</code> directive |
| for this works because functions (and methods) and macros are just |
| plain variables in FreeMarker. (For the same reason you could also |
| put <code class="inline-code">TemplateMethodModelEx</code> or |
| <code class="inline-code">TemplateDirectiveModel</code> instances into the |
| data-model before calling the template, or into the shared |
| variable map (see: |
| <code class="inline-code">freemarker.template.Configuration.setSharedVariable(String, |
| TemplateModel)</code>) when you initialize the |
| application.)</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 22. |
| Why is FreeMarker logging suppressed for my |
| application? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>It is because FreeMarker does not find any logging system. |
| To fix this, you must make available one of the following logging |
| systems for your application: Avalon |
| (<code class="inline-code">org.apache.log</code>), Log4J |
| (<code class="inline-code">org.apache.log4j</code>), or use J2SE 1.4 or later |
| (that contains <code class="inline-code">java.util.logging</code>). That is, the |
| class-loader used with your application must find one of the |
| mentioned classes.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 23. |
| <a name="misc.faq.niceErrorPage"></a> In my Servlet |
| based application, how do I show a nice error page instead of a |
| stack trace when error occurs during template processing? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>First of all, use <code class="inline-code">RETHROW_HANDLER</code> instead |
| of the default <code class="inline-code">DEBUG_HANDLER</code> (for more |
| information about template exception handlers <a href="#pgui_config_errorhandling">read this...</a>). Now |
| FreeMarker will not print anything to the output when an error |
| occurs, so the control is in your hands. After you have caught the |
| exception of |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| basically you can follow two strategies:</p> |
| |
| <ul> |
| <li> |
| <p>Call <code class="inline-code">httpResp.isCommitted()</code>, and if |
| that returns <code class="inline-code">false</code>, then you call |
| <code class="inline-code">httpResp.reset()</code> and print a ``nice error |
| page'' for the visitor. If the return value was |
| <code class="inline-code">true</code>, then try to finish the page be |
| printing something that makes clear for the visitor that the |
| page generation was abruptly interrupted because of an error |
| on the Web server. You may have to print a lot of redundant |
| HTML end-tags and set colors and font size to ensure that the |
| error message will be actually readable in the browser window |
| (check the source code of the |
| <code class="inline-code">HTML_DEBUG_HANDLER</code> in |
| <code class="inline-code">src\freemarker\template\TemplateException.java</code> |
| to see an example).</p> |
| </li> |
| |
| <li> |
| <p>Use full page buffering. This means that the |
| <code class="inline-code">Writer</code> doesn't send the output to the |
| client progressively, but buffers the whole page in the |
| memory. Since you provide the <code class="inline-code">Writer</code> |
| instance for the |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| method, this is your responsibility, FreeMarker has nothing to |
| do with it. For example, you may use a |
| <code class="inline-code">StringWriter</code>, and if |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| returns by throwing an exception, then ignore the content |
| accumulated by the <code class="inline-code">StringWriter</code>, and send |
| an error page instead, otherwise you print the content of |
| <code class="inline-code">StringWriter</code> to the output. With this |
| method you surely don't have to deal with partially sent |
| pages, but it can have negative performance implications |
| depending on the characteristic of the pages (for example, the |
| user will experience more response delay for a long page that |
| is generated slowly, also the server will consume more RAM). |
| Note that using a <code class="inline-code">StringWriter</code> is surely |
| not the most efficient solution, as it often reallocates its |
| buffer as the accumulated content grows.</p> |
| </li> |
| </ul> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 24. |
| I'm using a visual HTML editor that mangles template tags. |
| Will you change the template language syntax to accommodate my |
| editor? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>We won't change the standard version, because a lot of |
| templates depend on it.</p> |
| |
| <p>Our view is that the editors that break template code are |
| themselves broken. A good editor should ignore, not mangle, what |
| it doesn't understand.</p> |
| |
| <p>You maybe interested in that starting from FreeMarker 2.3.4 |
| you can use <code class="inline-code">[</code> and <code class="inline-code">]</code> instead |
| of <code class="inline-code"><</code> and <code class="inline-code">></code>. For more |
| details <a href="#dgui_misc_alternativesyntax">read |
| this...</a></p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 25. |
| How fast is FreeMarker? Is it true that 2.x is slower than |
| 1.x (FreeMarker classic)? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>First of all, don't forget that FreeMarker is only the view |
| rendering component in an <a href="#gloss.MVC">MVC</a> |
| system. Furthermore MVC templates tend to be simple: many static |
| text with a few interpolations and loops and conditional block. So |
| it is not like PHP or Model 1 JSP; your application performance is |
| not affected that much by the execution time of templates.</p> |
| |
| <p>FreeMarker is certainly fast enough that it will only very |
| rarely be a bottleneck in your application. Rather, other factors |
| such as the speed of the data-base operations or network bandwidth |
| will likely dominate. The impact of FreeMarker performance could |
| be noticeable only for really busy sites (say, over 30 hits per |
| second per server), where almost all database data is cached. If |
| you are finding FreeMarker slow, do make sure that the cache of |
| parsed templates works well |
| (<code class="inline-code">Configuration.getTemplate</code> be default uses |
| caching). Parsing a template file is a relatively costly step; in |
| most long-running server-side applications, you will want to parse |
| a template once and have it be used many times. (Note that |
| FreeMarker 2.1.4 and earlier versions have bugs that sometimes can |
| ruin caching.)</p> |
| |
| <p>FreeMarker 2.1 is slower than 1.7.1. This surely depends on |
| your templates, but it could be slower by a factor of 2 or 3. But |
| again, it does not means that response time will be 2 or 3 times |
| slower; most FreeMarker user simply should not be able to perceive |
| the change in the final response time.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 26. |
| How can my Java classes ask a template for information about |
| its structure (e.g. a list of all the variables)? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>In FreeMarker 2.2, <code class="inline-code">Template</code> has an |
| undocumented method for examining the parsed template: |
| <code class="inline-code">getRootTreeNode</code>.</p> |
| |
| <p>But listing all accessed variables is not possible, because |
| variable names can be dynamically generated from data. However, |
| there's a more important reason why FreeMarker doesn't support |
| this. The design of FreeMarker is based on the idea of a |
| separation between business objects and presentation objects. This |
| separation takes two forms:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>The templates know what data to expect, but they don't |
| know how it's generated.</p> |
| </li> |
| |
| <li> |
| <p>The business objects know what data to produce, but they |
| don't know how it's going to be displayed. Therefore, they |
| don't know anything about templates.</p> |
| </li> |
| </ol></div> |
| |
| <p>Since the business objects don't rely on the templates, if |
| you need to use them with some other presentation system, you |
| won't have to rewrite your application.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 27. |
| Will you ever provide backward compatibility? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>FreeMarker 2.0 was a complete rewrite of FreeMarker 1.x, by |
| a new author. The 1.x series continues as separated project: |
| FreeMarker Classic. Since 2.x follows different philosophy than |
| 1.x, 2.0x releases were immature despite the high major version |
| number. This caused further radical changes between 2.01 and 2.1. |
| As of 2.1 things were much more matured, and 2.2 is almost |
| backward compatible with 2.1. We hope that this tendency |
| continues.</p> |
| |
| <p>Currently, the rule is that releases with different second |
| version number (as 2.1.x and 2.2.x) are not (fully) compatible. |
| Releases where only the third version number differs (as 2.2.1 and |
| 2.2.6) are compatible.</p> |
| |
| <p>We always provide backward compatible bugfix releases for |
| the released versions. So basically, you don't |
| <em>have</em> to switch to a new, non-backward |
| compatible release in an already written product. It's a something |
| for something situation... FreeMarker recovers faster from design |
| mistakes than many other projects, but the price of this is that |
| major releases are not backward compatible. This is admittedly not |
| optimal, it would be better if there are fewer design mistakes... |
| but, well, it is the reality.</p> |
| </dd> |
| |
| |
| |
| |
| |
| <dt class="question" id=""> |
| 28. |
| If we distribute FreeMarker with our product, do we have to |
| release the source code for our product? |
| |
| </dt> |
| |
| |
| <dd class="answer"> |
| |
| <p>No. As of 2.0, FreeMarker is released under a BSD-style |
| license. This means that source or binary distributions may be |
| made freely, and can be included in other products, whether |
| commercial or open source.</p> |
| |
| <p>The only restrictions apply to the copyright of FreeMarker |
| itself, and the use of FreeMarker or its contributors as |
| endorsements of your own product. See the <a href="#app_license">LICENSE</a> for further details.</p> |
| |
| <p>If you use FreeMarker, we hope you'll send us a link to some |
| information about your product, but that's optional as |
| well.</p> |
| </dd> |
| |
| |
| </dl> |
| |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="app_install">Installing FreeMarker</h3> |
| |
| |
| |
| |
| <p>No real installation needed. Simply copy |
| <code class="inline-code">lib/freemarker.jar</code> to a location where your Java |
| application's class-loader will find it. For example, if you use |
| FreeMarker in a web application, you probably want to put |
| <code class="inline-code">freemarker.jar</code> into the |
| <code class="inline-code">WEB-INF/lib</code> directory of your web application.</p> |
| |
| <p>No real installation needed. Simply copy |
| <code class="inline-code">lib/freemarker.jar</code> to a location where your Java |
| application's ClassLoader will find it. For example, if you use |
| FreeMarker in a web application, you probably want to put |
| <code class="inline-code">freemarker.jar</code> into the |
| <code class="inline-code">WEB-INF/lib</code> directory of your web application. (If |
| you want to use FreeMarker with JSP Model-2 style (which also means that |
| you can use custom JSP taglibs in the templates), some extra steps |
| needed. For more information please see <a href="#pgui_misc_servlet">the chapter about servlets</a>.)</p> |
| |
| <p>However, some third party libraries have also be available for the |
| class-loader, if you want to enable certain |
| <em>optional</em> FreeMarker features:</p> |
| |
| <ul> |
| <li> |
| <p>At least J2SE 1.4 is required for regular expression |
| built-ins.</p> |
| </li> |
| |
| <li> |
| <p>At least J2SE 1.4 or a JAXP + DOM implementation + SAX |
| implementation is needed for the XML wrapping.</p> |
| </li> |
| |
| <li> |
| <p>Jaxen (recommended, <a href="http://jaxen.org/">download here</a>) or Apache Xalan |
| is needed for XML XPath support. Please use at least Jaxen |
| 1.1-beta-8, not older versions! Apache Xalan classes are included in |
| Sun J2SE 1.4, 1.5 and 1.6 (and maybe later too), so no separate |
| Xalan jar is needed with those versions.</p> |
| </li> |
| |
| <li> |
| <p>Obviously, <code class="inline-code">javax.servlet</code> classes are needed |
| for <code class="inline-code">FreemarkerServlet</code>. Servlet version 2.2 or |
| later is needed.</p> |
| </li> |
| |
| <li> |
| <p>For the custom JSP taglib support, you will need JSP 1.2 API |
| classes. No JSP implementation needed, just the API. For more |
| information please see <a href="#pgui_misc_servlet">the chapter |
| about servlets</a>.</p> |
| </li> |
| |
| <li> |
| <p>Obviously, Jython classes are needed for the Jython |
| wrapper.</p> |
| </li> |
| |
| <li> |
| <p>JDOM is needed for the deprecated freemarker.ext.jdom |
| package.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="app_build">Building FreeMarker</h3> |
| |
| |
| |
| |
| <p>If you want to modify the source code and rebuild |
| <code class="inline-code">freemarker.jar</code>, you need <a href="http://ant.apache.org/">Ant</a> 1.6.1 (or newer) and JDK |
| 5 (or newer). If these are satisfied, just run Ant from the root |
| directory of the distribution, and it will create the new |
| <code class="inline-code">freemarker.jar</code>. Note that for the very first build |
| you must be on-line, because the build task will download a lot of |
| required dependencies (about 20 MB) into the <code class="inline-code">lib</code> |
| subdirectory of distribution root directory.</p> |
| |
| <p>Maybe you should check the new jar file against our test suite. |
| This is done by running Ant with <code class="inline-code">test</code> target (go to |
| the root directory of the distribution, and issue "ant test"). If the |
| test fails, read the resulting <code class="inline-code">.txt</code> file in the |
| <code class="inline-code">build/testcase</code> directory for more details.</p> |
| |
| <p>Note that building a full distribution, which includes the |
| FreeMarker Manual and the off-line Web site, is not possible purely from |
| the source code that is included with the distribution. You will have to |
| check out the "docgen" and "site" sub-projects from the SVN repository |
| of FreeMarker for that.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="app_versions">Versions</h3> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_16">2.3.16</h4> |
| |
| |
| <p>Date of release: FIXME</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_15">2.3.15</h4> |
| |
| |
| <p>Date of release: 2008-12-16</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_133">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: Hash concatenation (like <code class="inline-code">hash1 + |
| hash2</code>) shuffled the order of keys/values even if both |
| hashes were ordered.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_134">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>In web pages that are based on the |
| <code class="inline-code">FreemarkerServlet</code>, you can now use |
| <code class="inline-code"><@include_page path="..."/></code> to use |
| servlet includes. See more <a href="#pgui_misc_servlet_include">here...</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_135">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> can automatically |
| detect that classes were reloaded by JavaRebel.</p> |
| </li> |
| |
| <li> |
| <p>Fixed a bug that caused <code class="inline-code">null</code> to be |
| returned from |
| <code class="inline-code">Environment.getCurrentEnvironment()</code> while |
| processing autoincludes and autoimports. (<a href="https://sourceforge.net/forum/message.php?msg_id=5531621">See |
| bug report</a>)</p> |
| </li> |
| |
| <li> |
| <p>Fixed a bug that caused |
| <code class="inline-code">getObject(Object)</code> method on POJOs to not be |
| recognized as a general get method.</p> |
| </li> |
| |
| <li> |
| <p>Substantially improved performance of the |
| <code class="inline-code"><#break></code> directive.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">DeepUnwrap</code> now unwraps custom null |
| model of the current object wrapper into a Java |
| <code class="inline-code">null</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_14">2.3.14</h4> |
| |
| |
| <p>Date of release: 2008-09-01</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_136">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New built-in: <code class="inline-code">xhtml</code>. See more <a href="#ref_builtin_xhtml">here...</a></p> |
| </li> |
| |
| <li> |
| <p>New special variable: <code class="inline-code">template_name</code>. |
| See more <a href="#ref_specvar">here...</a></p> |
| </li> |
| |
| <li> |
| <p>Now you can use the values of parameters as the defaults |
| of other parameters, for example <code class="inline-code"><#macro section |
| title label=title></code>. In earlier versions it worked |
| unreliably. There are no restriction regarding the order of |
| parameters, like <code class="inline-code"><#macro section label=title |
| title></code> works too.</p> |
| </li> |
| |
| <li> |
| <p>Added a new <a href="#ref_builtin_string_for_number">number format |
| specifier</a>, <code class="inline-code">computer</code>. This uses the |
| same formatting as |
| <code class="inline-code"><em class="code-color">exp</em>?c</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_137">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The constructor to |
| <code class="inline-code">freemarker.ext.servlet.AllHttpScopesHashModel</code> |
| is now public, allowing it to be reused in 3rd party web |
| frameworks.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.ext.beans.SimpleMapModel</code> (unlike |
| either <code class="inline-code">freemarker.ext.beans.MapModel</code> or |
| <code class="inline-code">freemarker.template.SimpleHash</code>) didn't allow |
| lookup by <code class="inline-code">java.lang.Character</code> key when passed |
| a single-character string as a key.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: permissive unwrapping in |
| <code class="inline-code">freemarker.template.utility.DeepUnwrap</code> class |
| was not recursively permissive with elements of sequences and |
| hashes.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">freemarker.ext.beans.MapModel</code> |
| returns <code class="inline-code">BeansWrapper.wrap(null)</code> instead of |
| <code class="inline-code">null</code> for <code class="inline-code">null</code> values |
| explicitly bound into the map.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Fixed a subtle bug with property getters of |
| classes implementing a type-parametrized interface.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: A further corner case of <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1939742&group_id=794&atid=100794">[1939742]</a>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_13">2.3.13</h4> |
| |
| |
| <p>Date of release: 2008-05-05</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_138">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New built-ins for rounding numbers: |
| <code class="inline-code">round</code>, <code class="inline-code">floor</code>, |
| <code class="inline-code">ceiling</code>. See more <a href="#ref_builtin_rounding">here...</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_139">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p><a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1898300&group_id=794&atid=350794">[1898300]</a>, |
| <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1818742&group_id=794&atid=350794">[1818742]</a>, |
| <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1780882&group_id=794&atid=350794">[1780882]</a>: |
| Reworked template caching mechanism for radically improved |
| concurrent performance, with help from Azul Systems engineers. |
| (Achieved 20x speedup with Struts2 webapps on a 128-CPU Azul |
| device compared to 2.3.12.) Also, template loading (including |
| parsing) errors are now cached, improving performance in |
| applications that often try to get missing templates.</p> |
| </li> |
| |
| <li> |
| <p><a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1892546&group_id=794&atid=100794">[1892546]</a> |
| Allow for custom <code class="inline-code">TemplateLoader</code> in |
| <code class="inline-code">FreemarkerServlet</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1725107&group_id=794&atid=100794">[1725107]</a> |
| Using the FreeMarker JSP taglib support with Servlet 2.4 may |
| generates XML validation warnings.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1939742&group_id=794&atid=100794">[1939742]</a> |
| <code class="inline-code">ConcurrentModificationException</code> on accessing |
| nonexistent <code class="inline-code">SimpleHash</code> entries in a |
| loop</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1902012&group_id=794&atid=100794">[1902012]</a> |
| <code class="inline-code">IteratorModel</code> eats exception causes</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <code class="inline-code"><#assign |
| x></#assign></code> (empty nested content) has |
| caused <code class="inline-code">NullPointerException</code></p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1926150&group_id=794&atid=100794">[1926150]</a> |
| <code class="inline-code">CachedTemplate</code> should be serializable</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_12">2.3.12</h4> |
| |
| |
| <p>Date of release: 2008-02-03</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_140">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1857161&group_id=794&atid=100794">[1857161]</a> |
| JSP <code class="inline-code">SimpleTag</code> support was broken in |
| 2.3.11.</p> |
| </li> |
| |
| <li> |
| <p>In the templates, now you can conveniently call Java |
| methods that use the Java 5 varargs feature (variable-length |
| argument lists). Also the overloaded-method chooser logic now |
| considers vararg methods more intelligently.</p> |
| </li> |
| |
| <li> |
| <p>Enum constants are now identified by their |
| <code class="inline-code">name()</code> instead of by their |
| <code class="inline-code">toString()</code> (because the latter can be |
| overridden in subclasses). This doesn't affect the way enum |
| constants are printed; of course that still uses |
| <code class="inline-code">toString()</code>.</p> |
| </li> |
| |
| <li> |
| <p>Messages in parser exceptions now display the name of the |
| template.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_11">2.3.11</h4> |
| |
| |
| <p>Date of release: 2007-12-04</p> |
| |
| <p>This release contains several performance and usability |
| improvements.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_141">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1687248&group_id=794&atid=100794">[1687248]</a> |
| <strong>Warning! This bugfix may breaks some |
| templates!</strong> Fixed the bugs of the <a href="#ref_builtin_c"><code>c</code> built-in</a> |
| (<code class="inline-code">?c</code>) that sometimes caused whole numbers to |
| be formatted with ``.0'' at the end (like: 1.0), and caused |
| numbers sometimes formatted to exponential form (like 4E-20). |
| From now whole numbers will never use decimal dot (not even if |
| the wrapped number is a <code class="inline-code">double</code>; remember, the |
| template language knows only a single numerical type), and |
| exponential form will never be used either. Also, the maximum |
| number of digits after the decimal dot was limited to 16, so |
| numbers smaller than 1E-16 will be shown as 0.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_142">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>FreeMarker now has much better JSP 2.0 and JSP 2.1 |
| compliance. Most notably, the JSP 2.0 |
| <code class="inline-code">SimpleTag</code> interface is now supported. |
| Additionally, even when run in an environment that doesn't have |
| its own JSP implementation, the FreeMarker JSP runtime will make |
| available its own implementation of |
| <code class="inline-code">JspFactory</code> and |
| <code class="inline-code">JspEngineInfo</code> to tags when JSP 2.0 API JAR is |
| available in classpath, as well as an implementation of |
| <code class="inline-code">JspApplicationContext</code> when JSP 2.1 API JAR is |
| available in classpath.</p> |
| </li> |
| |
| <li> |
| <p>A new model interface, |
| <code class="inline-code">TemplateDirectiveModel</code> provides an easier |
| paradigm for implementing user-defined directives than |
| <code class="inline-code">TemplateTransformModel</code> did previously. |
| <code class="inline-code">TemplateTransformModel</code> will be |
| deprecated.</p> |
| </li> |
| |
| <li> |
| <p>FreeMarker now finds the Xalan-based XPath support |
| included in Sun JRE/JDK 5 and 6, so no separate Xalan jar is |
| required for the XPath support to work. (However, we recommend |
| Jaxen over Xalan, as the FreeMarker XPath support is more |
| complete with that. Of course for that the Jaxen jar is still |
| needed.)</p> |
| </li> |
| |
| <li> |
| <p>Wrapping performance of <code class="inline-code">BeansWrapper</code> |
| has been significantly improved by eliminating repetitive |
| execution of various class tests.</p> |
| |
| <p><strong>Note for |
| <code class="inline-code">BeansWrapper</code> customizers:</strong> |
| subclasses of <code class="inline-code">BeansWrapper</code> that previously |
| overrode <code class="inline-code">getInstance(Object, ModelFactory)</code> |
| method should now instead override |
| <code class="inline-code">getModelFactory(Class)</code> to take advantage of |
| this improvement. Overriding the old method still works, but it |
| will not take advantage of the performance improvement.</p> |
| </li> |
| |
| <li> |
| <p>Memory footprint of a wrapper created by |
| <code class="inline-code">BeansWrapper</code> has been reduced (by a size of |
| one default-sized <code class="inline-code">HashMap</code>) until methods or |
| indexed properties are accessed on it (simple properties can be |
| accessed without increasing memory footprint).</p> |
| </li> |
| |
| <li> |
| <p>Rhino objects can be used in templates as scalars, |
| numbers, and booleans, following the JavaScript conversion |
| semantics for these types.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">.data_model</code> is now a |
| <code class="inline-code">TemplatHashModelEx</code> when possible. This means |
| that the list of the data-model variable names usually can be |
| get with <code class="inline-code">.data_model?keys</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FileTemplateLoader</code> can now optionally |
| allow following symlinks that point out of the base directory. |
| It is disabled by default for backward compatibility.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1670887&group_id=794&atid=100794">[1670887]</a> |
| <code class="inline-code">TaglibFactory</code> taglib matching did not follow |
| JSP 1.2 FCS.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1754320&group_id=794&atid=100794">[1754320]</a> |
| Bug in <code class="inline-code">setXPathSupportClass</code> prevented |
| plugging in a user-supplied <code class="inline-code">XPathSupport</code> |
| implementation.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1803298&group_id=794&atid=100794">[1803298]</a> |
| Parser error while parsing macro with loop variables</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1824122&group_id=794&atid=100794">[1824122]</a> |
| Loading templates from JAR files could lead to leaking of file |
| handles (due to a bug in the Java API implementation of |
| Sun).</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: Cached template is now removed from the cache |
| if the re-loading of the modified template file fails, so no |
| staled template is served.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_143">Documentation changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Substantial reworkings in the Template Authors's Guide |
| (which was previously called Designer's Guide), especially in |
| the Getting Started section.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">#{...}</code> is documented as deprected |
| construct from now.</p> |
| </li> |
| |
| <li> |
| <p>The "transform" term is now removed from the |
| documentation. Instead the more general "user-defined directive" |
| term is used, which encompasses macros, |
| <code class="inline-code">TemplateTransformModel</code>-s and the new |
| <code class="inline-code">TemplateDirectiveModel</code>-s, which are just |
| different ways of implementing user-defined directives.</p> |
| </li> |
| |
| <li> |
| <p>Some more minor improvements in the Manual.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_10">2.3.10</h4> |
| |
| |
| <p>Date of release: 2007-04-20</p> |
| |
| <p>This release contains several important bugfixes.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_144">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>[1589245] <code class="inline-code">MultiTemplateLoader</code> clears |
| its internal cached data (used for optimizing subsequent lookups |
| of the same template) when |
| <code class="inline-code">Configuration.clearTemplateCache()</code> is |
| invoked.</p> |
| </li> |
| |
| <li> |
| <p>[1619257] A bug that caused an exception when |
| <code class="inline-code">strict_bean_model</code> was used in a FreeMarker |
| configuration <code class="inline-code">Properties</code> object or in the |
| <code class="inline-code"><#setting .../></code> directive has been |
| fixed.</p> |
| </li> |
| |
| <li> |
| <p>[1685176] A bug that caused |
| <code class="inline-code">StackOverflowError</code> in certain interactions of |
| garbage collector with MRU cache under Sun's Java 6 JVM has been |
| fixed.</p> |
| </li> |
| |
| <li> |
| <p>[1686955] When <code class="inline-code">ResourceBundleModel</code> |
| constructs <code class="inline-code">MessageFormat</code> objects, it passes |
| them its own locale. <a href="#beanswrapper_method">More |
| info...</a></p> |
| </li> |
| |
| <li> |
| <p>[1691432] A bug that caused |
| <code class="inline-code">BeansWrapper.EXPOSE_SAFE</code> to be no safer than |
| <code class="inline-code">BeansWrapper.EXPOSE_ALL</code> has been |
| fixed.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_145">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>[1628550] You can now use |
| <code class="inline-code">dateExp?string.full</code> for formatting dates |
| using Java built-in format |
| <code class="inline-code">java.util.Date.FULL</code> <a href="#ref_builtin_string_for_date">More info...</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_9">2.3.9</h4> |
| |
| |
| <p>Date of release: 2007-01-23</p> |
| |
| <p>This release contains support for accessing JDK 1.5 enums and |
| public fields of classes from the templates through the |
| BeansWrapper.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_146">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> can now expose public |
| fields of objects to the template if you call the |
| <code class="inline-code">setExposeFields(true)</code> on it. <a href="#beanswrapper_hash">More info...</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> can now pass any sequence |
| model to Java methods expecting a |
| <code class="inline-code">java.util.Collection</code> or a native Java array |
| (including primitive arrays). <a href="#beanswrapper_hash">More info...</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> can now pass any sequence |
| and collection model to Java methods expecting a |
| <code class="inline-code">java.lang.Iterable</code>. <a href="#beanswrapper_hash">More info...</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> can now unwrap numeric |
| models into correct target types when passing to Java methods |
| expecting a primitive or boxed number. Use of various <a href="#ref_builtins_expert">expert built-ins</a> to |
| manually coerce the types becomes mostly unnecessary.</p> |
| </li> |
| |
| <li> |
| <p>Fixed a bug where <code class="inline-code">BeansWrapper</code> would |
| pass a <code class="inline-code">java.util.Collection</code> to a method |
| expecting a <code class="inline-code">java.util.Set</code> in certain rare |
| cases. <a href="#beanswrapper_hash">More |
| info...</a></p> |
| </li> |
| |
| <li> |
| <p>Support for JDK 1.5 enums in |
| <code class="inline-code">BeansWrapper</code> and |
| <code class="inline-code">DefaultObjectWrapper</code>. By calling the |
| <code class="inline-code">getEnumModels()</code> method, you can retrieve a |
| hash model that is keyed by class names and allows access to |
| enumerated values. I.e. if you bind this hash model under name |
| <code class="inline-code">enums</code> in the data-model, you can write |
| expressions like |
| <code class="inline-code">enums["java.math.RoundingMode"].UP</code> in the |
| template. The enum values can be used as scalars and support |
| equality and inequality comparisons. <a href="#jdk_15_enums">More info...</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.ext.rhino.RhinoWrapper</code> now |
| correctly translates Rhino <code class="inline-code">Undefined</code> |
| instance, <code class="inline-code">UniqueTag.NOT_FOUND</code>, and |
| <code class="inline-code">UniqueTag.NULL</code> to FreeMarker undefined |
| value.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_8">2.3.8</h4> |
| |
| |
| <p>Date of release: 2006-07-09</p> |
| |
| <p>This release substantially improves the JSP 2.0 compatibility. |
| (For those who have seen the same points in 2.3.7: Sorry, the version |
| history was incorrect... those JSP 2.0 related changes were not in the |
| release yet.)</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_147">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>JSP support improvement: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1326058&group_id=794">[1326058]</a> |
| Added support for <code class="inline-code">DynamicAttributes</code> (new in |
| JSP 2.0)</p> |
| </li> |
| |
| <li> |
| <p>JSP support improvement: Added support for |
| <code class="inline-code">pushBody()</code>/<code class="inline-code">popBody()</code> in |
| <code class="inline-code">FreemarkerPageContext</code></p> |
| </li> |
| |
| <li> |
| <p>JSP support improvement: Added support for |
| <code class="inline-code">getVariableResolver()</code> (new in JSP |
| 2.0).</p> |
| </li> |
| |
| <li> |
| <p>JSP support improvement: Added support for |
| <code class="inline-code">include(String, boolean)</code> (new in JSP |
| 2.0).</p> |
| </li> |
| |
| <li> |
| <p>JSP support improvement: Added support for |
| <code class="inline-code">getExpressionEvaluator()</code> (new in JSP 2.0). |
| However, it will need Apache commons-el in the class path, or |
| else this method will not work (it's optional). Note that EL |
| support is not needed in principle, since FreeMarker has it's |
| own expression language. But some custom JSP 2 tags may still |
| want to use this method, after all it's in the JSP 2 API.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_7">2.3.7</h4> |
| |
| |
| <p>Date of release: 2006-06-23</p> |
| |
| <p>This release, compared to 2.3.7 RC1, contains new operators for |
| handling null/missing variables, , the <code class="inline-code">substring</code> |
| built-in, and some more bugfixes. Note that 2.3.7 RC1 has a long |
| change log, so you may want to <a href="#versions_2_3_7rc1">read |
| that</a> too.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_148">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">seq_contains</code> built-in now handles |
| <code class="inline-code">TemplateCollectionModel</code>-s as well.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: In 2.3.7 RC1 |
| <code class="inline-code">FreemarkerServlet</code> has always died with |
| <code class="inline-code">NullPointerException</code> during |
| initialization.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_149">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>3 new operators were added for terser missing variable |
| handling. These operators make the <code class="inline-code">default</code>, |
| <code class="inline-code">exists</code> and <code class="inline-code">if_exists</code> |
| built-ins deprecated. (The parser doesn't issue any warning |
| messages when you use deprecated built-ins, and they are still |
| working.):</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code"><em class="code-color">exp1</em>!<em class="code-color">exp2</em></code> |
| is near equivalent with |
| <code class="inline-code"><em class="code-color">exp1</em>?default(<em class="code-color">exp2</em>)</code>, |
| also |
| <code class="inline-code">(<em class="code-color">exp1</em>)!<em class="code-color">exp2</em></code> |
| is near equivalent with |
| <code class="inline-code">(<em class="code-color">exp1</em>)?default(<em class="code-color">exp2</em>)</code>. |
| The only difference is that this new operator doesn't |
| evaluate the |
| <code class="inline-code"><em class="code-color">exp2</em></code> when the |
| default value is not needed.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"><em class="code-color">exp1</em>!</code> is |
| similar to |
| <code class="inline-code"><em class="code-color">exp1</em>?if_exists</code>, |
| also <code class="inline-code">(<em class="code-color">exp1</em>)!</code> |
| is similar to |
| <code class="inline-code">(<em class="code-color">exp1</em>)?if_exists</code>. |
| The difference is that with this new operator the default |
| value is an empty string and an empty list and empty hash at |
| the same time (multi-type variable), while with |
| <code class="inline-code">if_exists</code> the default value was an empty |
| string and an empty list and empty hash and boolean |
| <code class="inline-code">false</code> and a transform that does nothing |
| and ignores all parameters at the same time.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"><em class="code-color">exp1</em>??</code> |
| is equivalent with |
| <code class="inline-code"><em class="code-color">exp1</em>?exists</code>, |
| also <code class="inline-code">(<em class="code-color">exp1</em>)??</code> |
| is equivalent with with |
| <code class="inline-code">(<em class="code-color">exp1</em>)?exists</code>.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>New built-in: |
| <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>, |
| <em class="code-color">toExclusive</em>)</code>, also callable |
| as |
| <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>)</code>. |
| Getting substrings was possible for a long time like |
| <code class="inline-code">myString[<em class="code-color">from</em>..<em class="code-color">toInclusive</em>]</code> |
| and |
| <code class="inline-code">myString[<em class="code-color">from</em>..]</code>. |
| This syntax is now deprecated for getting substrings (but it's |
| still working), and instead you should use |
| <code class="inline-code">myString?substring(<em class="code-color">from</em>, |
| <em class="code-color">toExclusive</em>)</code> and |
| <code class="inline-code">myString?substring(<em class="code-color">from</em>)</code>. |
| Sequence (list) slices still has to be get with the old syntax, |
| since <code class="inline-code">substring</code> only applies to strings. |
| Please note that the ``to'' parameter is 1 greater with this new |
| builtin, as it is an exclusive index. Further difference is that |
| the <code class="inline-code">substring</code> built-in requires that the |
| ``from'' index is less than or equal to the ``to'' index. So 0 |
| length substrings are possible now, but not reversed |
| substrings.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1487694&group_id=794">[1487694]</a> |
| malfunction when the <code class="inline-code">recover</code> directive has no |
| nested content</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_7rc1">2.3.7 RC1</h4> |
| |
| |
| <p>Date of release: 2006-04-27</p> |
| |
| <p>This release contains many bugfixes and some |
| <code class="inline-code">FreemarkerServlet</code> related improvements. It's a |
| Release Candidate, which means that it shouldn't be used in production |
| environment yet. We recommend this release for development, however. |
| Please test it.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_150">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">FreemarkerServlet</code> improvement: |
| <code class="inline-code">AllHttpScopesHashModel</code> is now public, so you |
| can add unlisted variables to the data-model.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FreemarkerServlet</code> improvement: When it |
| throws a <code class="inline-code">ServletException</code>, the J2SE 1.4 cause |
| exception is now set under J2SE 1.4.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1469275&group_id=794">[1469275]</a> |
| <code class="inline-code">NullPointerException</code> when using |
| <code class="inline-code">BeansWrapper</code> with reloaded classes</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1449467&group_id=794">[1449467]</a> |
| <code class="inline-code">HttpSessionHashModel</code> is not |
| <code class="inline-code">Serializable</code></p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1435113&group_id=794">[1435113]</a> |
| Error in <code class="inline-code">BeanWrapper</code> with indexed |
| properties</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1411705&group_id=794">[1411705]</a> |
| Acquisition bug in <code class="inline-code">TemplateCache</code></p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1459699&group_id=794&atid=100794">[1459699]</a> |
| Tag syntax can't set with |
| <code class="inline-code">Configuration.setSetting(String, |
| String)</code></p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1473403&group_id=794">[1473403]</a> |
| <code class="inline-code">ReturnInstruction.Return</code> should be |
| public</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_151">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1463664&group_id=794">[1463664]</a>kup |
| <code class="inline-code">[/#noparse]</code> is printed out</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_6">2.3.6</h4> |
| |
| |
| <p>Date of release: 2006-03-15</p> |
| |
| <p>Quick release that fixes a serious bug of 2.3.5, days after its |
| release. So for the recently added new features please <a href="#versions_2_3_5">see the section of 2.3.5.</a></p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_152">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: In FreeMarker 2.3.5 only, when you read a bean |
| property for the second time, FreeMarker will say that it's |
| missing (null).</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_5">2.3.5</h4> |
| |
| |
| <p>Date of release: 2006-03-11</p> |
| |
| <p><em>This release was withdrawn because of a serious bug in |
| it. Please don't use it! Of course, all new features of it are |
| included in FreeMarker 2.3.6.</em></p> |
| |
| <p>A few new features and several bugfixes.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_153">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1435847&group_id=794">[1435847]</a> |
| Alternative syntax doesn't work for comments</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: With the new square bracket syntax, the tag |
| could be closed with <code class="inline-code">></code>. Now it can be |
| closed with <code class="inline-code">]</code> only.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1324020&group_id=794">[1324020]</a> |
| <code class="inline-code">ParseException</code> with the |
| <code class="inline-code">ftl</code> directive if it wasn't in its own |
| line</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1404033&group_id=794">[1404033]</a> |
| <code class="inline-code">eval</code> built-in fails with hash |
| concatenation</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_154">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>A new <code class="inline-code">Configuration</code> level setting, |
| <code class="inline-code">tagSyntax</code> was added. This determines the |
| syntax of the templates (angle bracket syntax VS <a href="#dgui_misc_alternativesyntax">square bracket |
| syntax</a>) that has no <code class="inline-code">ftl</code> directive in |
| it. So now you can choose to use the new square bracket syntax |
| by default. However, the recommended is to use auto-detection |
| (<code class="inline-code">yourConfig.setTagSyntax(Configuration.AUTO_DETECT_TAG_SYNTAX)</code>), |
| because that will be the default starting from 2.4. |
| Auto-detection chooses syntax based on the syntax of the first |
| FreeMarker tag of the template (could be any FreeMarker tag, not |
| just <code class="inline-code">ftl</code>). Note that as with the previous |
| version, if a the template uses <code class="inline-code">ftl</code> |
| directive, then the syntax of the <code class="inline-code">ftl</code> |
| directive determines the syntax of the template, and the |
| <code class="inline-code">tagSyntax</code> setting is ignored.</p> |
| </li> |
| |
| <li> |
| <p>Now <code class="inline-code">BeansWrapper</code>, |
| <code class="inline-code">DefaultObjectWrapper</code> and |
| <code class="inline-code">SimpleObjectWrapper</code> support lookup with 1 |
| character long strings in <code class="inline-code">Map</code>-s (like |
| <code class="inline-code">myHash["a"]</code>) that use |
| <code class="inline-code">Character</code> keys. Simply, as a special case, |
| when a hash lookup fails on a string that is 1 character long, |
| it checks for the <code class="inline-code">Character</code> key in the |
| underlying map. (Bug tracker entry <a href="http://sourceforge.net/tracker/?func=detail&atid=100794&aid=1299045&group_id=794">[1299045]</a> |
| FreeMarker doesn't support map lookup with Character |
| keys.)</p> |
| </li> |
| |
| <li> |
| <p>A new property, <code class="inline-code">strict</code> was added to |
| <code class="inline-code">BeansWrapper</code>, |
| <code class="inline-code">DefaultObjectWrapper</code> and |
| <code class="inline-code">SimpleObjectWrapper</code>. If this property is |
| <code class="inline-code">true</code> then an attempt to read a bean propertly |
| in the template (like <code class="inline-code">myBean.aProperty</code>) that |
| doesn't exist in the bean class (as opposed to just holding |
| <code class="inline-code">null</code> value) will cause |
| <code class="inline-code">InvalidPropertyException</code>, which can't be |
| suppressed in the template (not even with |
| <code class="inline-code">myBean.noSuchProperty?default('something')</code>). |
| This way <code class="inline-code">?default('something')</code> and |
| <code class="inline-code">?exists</code> and similar built-ins can be used to |
| handle existing properties whose value is |
| <code class="inline-code">null</code>, without the risk of hiding typos in the |
| property names. Typos will always cause error. But mind you, it |
| goes against the basic approach of FreeMarker, so use this |
| feature only if you really know what are you doing.</p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1426227&group_id=794&atid=100794">[1426227]</a> |
| <code class="inline-code">NullPointerException</code> in |
| <code class="inline-code">printStackTrace(...)</code></p> |
| </li> |
| |
| <li> |
| <p>Bug fixed: <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1386193&group_id=794&atid=100794">[1386193]</a> |
| Division by zero in <code class="inline-code">ArithmeticEngine</code></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_4">2.3.4</h4> |
| |
| |
| <p>Date of release: 2005-10-10</p> |
| |
| <p>Some new features and bugfixes.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_155">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Now you can use <code class="inline-code">[</code> and |
| <code class="inline-code">]</code> instead of <code class="inline-code"><</code> and |
| <code class="inline-code">></code> for the FreeMarker tags. For example you |
| can write <code class="inline-code">[#if |
| loggedIn]<em class="code-color">...</em>[/#if]</code> and |
| <code class="inline-code">[@myMacro /]</code>. <a href="#dgui_misc_alternativesyntax">More info...</a></p> |
| </li> |
| |
| <li> |
| <p>Bugfix: the <code class="inline-code">has_content</code> built-in |
| returned <code class="inline-code">false</code> for number, date and boolean |
| values (if the value was not a multi-type value that is also a |
| sequence or collection or hash or string). Now it always returns |
| <code class="inline-code">true</code> for a number, date or boolean values |
| (except if the value is also a sequence or collection or hash or |
| string, because then it will be examined only like that).</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_156">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: the parameterless constructor of the |
| <code class="inline-code">ClassTemplateLoader</code> didn't worked.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The Jython wrapper didn't wrapped |
| <code class="inline-code">java.util.Date</code> objects well. Now it wraps |
| them with <code class="inline-code">BeanWrapper</code> to |
| <code class="inline-code">TemplateDateModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: the <code class="inline-code">include</code> directive was |
| blamed when the included file had syntax error.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_157">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Minor Manual fixes.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_3">2.3.3</h4> |
| |
| |
| <p>Date of release: 2005-06-23</p> |
| |
| <p>Some new features and lot of bugfixes.</p> |
| |
| <p>Attention:</p> |
| |
| <ul> |
| <li> |
| <p>If you are using the Log4J logging, from now at least Log4J |
| 1.2 is required. This is because of incompatible changes in the |
| Log4J API.</p> |
| </li> |
| |
| <li> |
| <p>If you build FreeMarker yourself: from now at least JavaCC |
| 3.2 (instead of JavaCC 2.1) and at least Ant 1.6.1 (instead of Ant |
| 1.5.x) is required. This doesn't affect users who use the |
| <code class="inline-code">freemarker.jar</code> comes with the |
| distribution.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_158">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New built-in for formatting numbers for ``computer |
| audience'' as opposed to human audience: <a href="#ref_builtin_c"><code>c</code></a>. It should |
| be used for numbers that must use Java language formatting |
| regardless of the number format and locale settings, like for a |
| database record ID used as the part of an URL or as invisible |
| field value in a HTML form, or for printing CSS/JavaScript |
| numerical literals.</p> |
| </li> |
| |
| <li> |
| <p>New built-in for the columnar/tabular displaying of |
| sequences: <a href="#ref_builtin_chunk"><code>chunk</code></a>.</p> |
| </li> |
| |
| <li> |
| <p>The <a href="#dgui_template_exp_seqenceop_slice">sequence |
| slice</a> and substring operators now allow the omitting of |
| the last index, in which case it defaults to the index of the |
| last sequence item or character. Example: |
| <code class="inline-code">products[2..]</code>. (Also, <a href="#dgui_template_exp_direct_seuqence">numerical range |
| literals</a> now allow the omitting of the final number, in |
| which case it defaults to infinity. Example: |
| <code class="inline-code">5..</code>.)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">?replace</code> has worked forever if |
| the string to replace was <code class="inline-code">""</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_159">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New template loader: |
| <code class="inline-code">freemarker.cache.StringTemplateLoader</code>. It |
| uses a <code class="inline-code">Map</code> with <code class="inline-code">Strings</code> as |
| its source of templates. See more in the JavaDoc.</p> |
| </li> |
| |
| <li> |
| <p>Experimental Rhino support: FreeMarker now comes with an |
| experimental object wrapper for Rhino (Java ECMAScript |
| implementation): |
| <code class="inline-code">freemarker.ext.rhino.RhinoWrapper</code></p> |
| </li> |
| |
| <li> |
| <p>Some new utility methods for |
| <code class="inline-code">Simple<em class="code-color">Xxx</em></code> classes: |
| <code class="inline-code">SimpleHash.toMap()</code>, |
| <code class="inline-code">SimpleSequence.toList()</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: FTL literals and any other |
| <code class="inline-code">SimpleSequnce</code>-s, and |
| <code class="inline-code">SimpleHash</code>-es now can be used as parameters |
| to the FreeMarker-unaware Java methods that are exposed by |
| <code class="inline-code">DefaultWrapper</code> or |
| <code class="inline-code">BeansWrapper</code>. That is, the method parameters |
| are automatically converted from |
| <code class="inline-code">Template<em class="code-color">Type</em>Model</code>-s |
| to <code class="inline-code">java.util.Map</code> and |
| <code class="inline-code">java.util.List</code> respectively.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The JSP support now works in JSP 2 compliant |
| containers as well. No, it doesn't support the new features of |
| JSP 2 yet, it's just that the JSP 1.2 taglib support has not |
| worked in JSP 2 containers.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The |
| <code class="inline-code">Configuration.setOutputEncoding</code> and |
| <code class="inline-code">setURLEscapingCharset</code> methods died with |
| <code class="inline-code">NullPointerException</code> when you tried to set |
| the setting value to <code class="inline-code">null</code>, which is legal for |
| these settings.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.template.utility.StringUtil.replace(...)</code> |
| has worked forever if the string to replace was |
| <code class="inline-code">""</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The Log4J logging was updated to be compatible |
| with the upcoming Log4J 1.3. Note that now FreeMarker will need |
| at least Log4J 1.2.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: FreeMarker didn't built from the source code on |
| J2SE 1.5, because of the introduction of the |
| <code class="inline-code">enum</code> keyword.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The return value of |
| <code class="inline-code">SimpleSequence.synchronizedWrapper()</code> was not |
| properly synchronized. Same with |
| <code class="inline-code">SimpleHash.synchronizedWrapper()</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Problem with <code class="inline-code">BeansWrapper</code> and |
| overridden bean methods/properties. (Details: bug-tracker entry |
| <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1217661&group_id=794&atid=100794">#1217661</a> |
| and <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1166533&group_id=794&atid=100794">#1166533</a>)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Can't access JSP taglibs if |
| <code class="inline-code">Request</code> attribute is defined in the |
| data-model (Details: bug-tracker entry <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1202918&group_id=794&atid=100794">#1202918</a>).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Various minor parser glitches were fixed.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_160">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Manual improvements, especially in the FAQ.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_2">2.3.2</h4> |
| |
| |
| <p>Date of release: 2005-01-22</p> |
| |
| <p>Bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_161">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: If you use JSP taglibs in FreeMarker templates, |
| FreeMarker possibly tried to get DTD-s from the Sun Web site |
| because of a bug introduced with FreeMarker 2.3.1. This was a |
| serious problem since if your server is offline or the Sun Web |
| site becomes temporarily inaccessible the templates that are |
| using JSP taglibs will possibly die with error.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">DefaultObjectWrapper</code> has |
| ignored the value of the <code class="inline-code">nullModel</code> property. |
| (Note that it's discouraged to use a ``null model''.)</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3_1">2.3.1</h4> |
| |
| |
| <p>Date of release: 2005-01-04</p> |
| |
| <p>Maintenance (with some important new features) and bugfix |
| release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_162">Possible backward compatibility issue</h5> |
| |
| |
| <p>There is a bugfix that may affect the behavior of you Web |
| application if you use JSP tags in FreeMarker templates: |
| FreeMarker's implementation of |
| <code class="inline-code">javax.servlet.jsp.PageContext.getSession()</code> was |
| incorrect. The <code class="inline-code">getSession()</code> method is a |
| convenience method by which the custom tag can get the current |
| <code class="inline-code">HttpSession</code> object (possibly |
| <code class="inline-code">null</code> if there is no session). Till now, if the |
| session didn't existed then it has created it automatically, so it |
| never returned <code class="inline-code">null</code>. This was a bug, so starting |
| from 2.3.1 it never creates the session, just returns |
| <code class="inline-code">null</code> if it doesn't exist. The old incorrect |
| behavior could cause page rendering to fail if the method is called |
| after the page is partially flushed. But beware, the old behavior |
| has possibly hidden some bugs of the Web application, where it |
| forgot to create the session, so with the new correct behavior you |
| may face malfunction caused by previously cloaked bugs of the Web |
| application. (It's the task of the MVC Controller to create the |
| session, except if the JSP tag that needs a session is written so it |
| creates it automatically, but then it doesn't expects that |
| <code class="inline-code">getSession()</code> will do it.)</p> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_163">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New built-in: <a href="#ref_builtin_url"><code>url</code></a>. This |
| built-in can be used for URL escaping. Note, however, that to |
| use this built-in conveniently, the software that encapsulates |
| FreeMarker has to be 2.3.1 aware (programmers will find more |
| info bellow...).</p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_specvar">special variables</a>: |
| <code class="inline-code">output_encoding</code> and |
| <code class="inline-code">url_escaping_charset</code>. Note, however, that to |
| use these, the software that encapsulates FreeMarker has to be |
| 2.3.1 aware (programmers will find more info bellow...).</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for sequences: <a href="#ref_builtin_seq_contains"><code>seq_contains</code></a>, |
| <a href="#ref_builtin_seq_index_of"><code>seq_index_of</code></a>, |
| <a href="#ref_builtin_seq_last_index_of"><code>seq_last_index_of</code></a>.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for strings: <a href="#ref_builtin_left_pad"><code>left_pad</code></a>, |
| <a href="#ref_builtin_right_pad"><code>right_pad</code></a> |
| and <a href="#ref_builtin_contains"><code>contains</code></a>.</p> |
| </li> |
| |
| <li> |
| <p>New directive: <a href="#ref.directive.attempt"><code>attempt</code>/<code>recover</code></a></p> |
| </li> |
| |
| <li> |
| <p>The <a href="#ref_builtin_js_string"><code>js_string</code> |
| built-in</a> now escapes <code class="inline-code">></code> as |
| <code class="inline-code">\></code> (to avoid |
| <code class="inline-code"></script></code>).</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">sort</code> and <code class="inline-code">sort_by</code> |
| built-ins now can sort by date values. Also, |
| <code class="inline-code">sort_by</code> built-in now can sort by the |
| subvarible of a subvariable of a subvariable... etc. for any |
| level depth. (<a href="#ref_builtin_sort_by">Details...</a>)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</code> |
| now prints more HTML-context-proof messages.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_164">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New setting: <code class="inline-code">output_encoding</code>. This |
| setting is used for informing FreeMarker about the charset that |
| the enclosing software (as a Web application framework) uses for |
| the output of FreeMarker. It's undefined by default, and |
| although it is not strictly required to set it, the enclosing |
| software should do so. This setting must be set if templates |
| want to use the new <code class="inline-code">output_encoding</code> special |
| variable, and possibly if they want to use the new |
| <code class="inline-code">url</code> built-in. Note that the FreeMarker API |
| allows you to set settings for each template execution |
| individually (look at |
| <code class="inline-code">Template.createProcessingEnvironment(...)</code>).</p> |
| </li> |
| |
| <li> |
| <p>New setting: <code class="inline-code">url_escaping_charset</code>. This |
| is the charset used for calculating the escaped parts |
| (<code class="inline-code">%<em class="code-color">XX</em></code>) when you do |
| URL escaping with the new <code class="inline-code">url</code> built-in. If it |
| is not set, then the <code class="inline-code">url</code> built-in uses the |
| value of the <code class="inline-code">output_encoding</code> setting, and if |
| that's not set either, then the parameterless version of |
| <code class="inline-code">url</code> built-in (<code class="inline-code">${foo?url}</code>) |
| can't be used.</p> |
| </li> |
| |
| <li> |
| <p>Using the singleton (static) |
| <code class="inline-code">Configuration</code> instance is clearly a bad |
| practice, so related methods are now deprecated, and the Manual |
| was adjusted, and the <code class="inline-code">FreemarkerXmlTask</code> was |
| updated as well.</p> |
| </li> |
| |
| <li> |
| <p>The |
| <code class="inline-code">freemarker.template.utility.Constants</code> class |
| was added that contains various static final fields that store |
| frequently used constant <code class="inline-code">TemplateModel</code> |
| values, as <code class="inline-code">EMPTY_SEQUENCE</code>, |
| <code class="inline-code">ZERO</code>, ...etc.</p> |
| </li> |
| |
| <li> |
| <p>When using <code class="inline-code">SecurityManager</code> with |
| FreeMarker, accessing system properties may caused |
| AccessControlException. Now such exceptions are catched and |
| logged with warning level, and the default value of the property |
| is returned.</p> |
| </li> |
| |
| <li> |
| <p>The needles <code class="inline-code">InvocationTargetException</code> |
| is now removed from the exception cause trace in certain |
| cases.</p> |
| </li> |
| |
| <li> |
| <p>Added a dirty hack that prints |
| <code class="inline-code">ServletException</code> root cause in |
| <code class="inline-code">TemplateException</code>'s stack trace if that's the |
| direct cause exception of the |
| <code class="inline-code">TemplateException</code>, despite the poorly written |
| <code class="inline-code">ServletException</code> class.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: FreeMarker's implementation of |
| <code class="inline-code">javax.servlet.jsp.PageContext.getSession()</code> |
| was incorrect. The <code class="inline-code">getSession()</code> method is a |
| convenience method by which the custom tag can get the current |
| <code class="inline-code">HttpSession</code> object (possibly |
| <code class="inline-code">null</code> if there is no session). Till now, if |
| the session didn't existed then it has created it automatically, |
| so it never returned <code class="inline-code">null</code>. This was a bug, so |
| starting from 2.3.1 it never creates the session, just returns |
| <code class="inline-code">null</code> if it doesn't exist. The old incorrect |
| behavior could cause page rendering to fail if the method is |
| called after the page is partially flushed. But beware, the old |
| behavior has possibly hidden some bugs of the Web application, |
| where it forgot to create the session, so with the new correct |
| behavior you may face malfunction caused by previously cloaked |
| bugs of the Web application. (It's the task of the MVC |
| Controller to create the session, except if the JSP tag that |
| needs a session is written so it creates it automatically, but |
| then it doesn't expects that <code class="inline-code">getSession()</code> |
| will do it.)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">BeansWrapper</code> didn't always |
| handled properly the case of a Java class having both a public |
| static field and a public static method with the same |
| name.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">SimpleMethodModel</code> had |
| incorrectly propagate exceptions sometimes, causing null pointer |
| exception.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The template execution may used outdated cached |
| values when you have processed the same |
| <code class="inline-code">Environment</code> for multiple times, and changed |
| settings between the two processings. Note that this could |
| happen only in single-thread environment, where such setting |
| modifications are allowed.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Some of the string built-ins has died with |
| <code class="inline-code">IndexOutOfBounds</code> exception if the template |
| author has forgotten to specify required parameters. Now they |
| die with more helpful error messages.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.ext.dom.NodeModel.equals(...)</code> has |
| died with null pointer exception if its argument was |
| <code class="inline-code">null</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The cause exception of |
| <code class="inline-code">TemplateException</code>-s was sometimes printed |
| twice in stack traces with J2SE 1.4 or later.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The |
| <code class="inline-code">StringUtil.FTLStringLiteralEnc(String)</code> method |
| was finished.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_165">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Fixes and improvements in the Manual and in the API |
| JavaDoc.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_166">The history of the releases before the final version</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_167">Differences between the preview release and final |
| release</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Added a dirty hack that prints |
| <code class="inline-code">ServletException</code> root cause in |
| <code class="inline-code">TemplateException</code>'s stack trace if that's |
| the direct cause exception of the |
| <code class="inline-code">TemplateException</code>, despite the poorly |
| written <code class="inline-code">ServletException</code> class.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.ext.dom.NodeModel.equals(...)</code> |
| has died with null pointer exception if its argument was |
| <code class="inline-code">null</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The cause exception of |
| <code class="inline-code">TemplateException</code>-s was sometimes printed |
| twice in stack traces with J2SE 1.4 or later.</p> |
| </li> |
| |
| <li> |
| <p>More minor improvements in the Manual.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_3">2.3</h4> |
| |
| |
| <p>Date of release: 2004-June-15</p> |
| |
| <p>FreeMarker 2.3 introduces numerous little new features and |
| quality improvements compared to the 2.2.x series. The most notable |
| improvements are the ability to define functions (methods) in |
| templates, the ability to interpolate variables in string literals, |
| the support for a variable number of macro parameters, and the more |
| intelligent default object wrapper. Although none of the improvements |
| is a drastic change, the 2.3.x series is not backward compatible with |
| the 2.2.x series (see the list below), so you may choose to use it for |
| new projects only.</p> |
| |
| <p>Probably the most ``loudly promoted'' new feature is the totally |
| redesigned XML wrapper. With the new XML wrapper FreeMarker targets a |
| new application domain, which is similar to the application domain of |
| XSLT: transforming complex XML to whatever textual output. Although |
| this subproject is young, it is definitely usable in practice. See the |
| <a href="#xgui">XML Processing Guide</a> for more |
| details.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_168">Non backward-compatible changes!</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Since interpolations (<code class="inline-code">${...}</code> and |
| <code class="inline-code">#{...}</code>) now work inside string literals, the |
| character sequence <code class="inline-code">${</code> and |
| <code class="inline-code">#{</code> in string literals are reserved for that. |
| So if you have something like <code class="inline-code"><#set x = |
| "${foo}"></code>, then you have to replace it with |
| <code class="inline-code"><#set x = r"${foo}"></code> -- beware, escapes |
| such as <code class="inline-code">\n</code> will not work in raw |
| (<code class="inline-code">r</code>) strings.</p> |
| </li> |
| |
| <li> |
| <p>The default (initial) value of the |
| <code class="inline-code">strict_syntax</code> setting has been changed from |
| <code class="inline-code">false</code> to <code class="inline-code">true</code>. When |
| <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>, |
| tags with old syntax as <code class="inline-code"><include |
| "foo.ftl"></code> will be considered as static text (so |
| they go to the output as-is, like HTML tags do), and not as FTL |
| tags. Such tags have to be rewritten to <code class="inline-code"><#include |
| "foo.ftl"></code>, since only parts that starts with |
| <code class="inline-code"><#</code>, <code class="inline-code"></#</code>, |
| <code class="inline-code"><@</code>, or <code class="inline-code"></@</code> count as |
| FTL tags. Or, to recover the old transitional behavior, where |
| both legacy and new tag syntax was recognized, you have to |
| explicitly set <code class="inline-code">strict_syntax</code> to |
| <code class="inline-code">false</code>: |
| <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for |
| individual templates you can force the old behavior by starting |
| the template with <code class="inline-code"><#ftl |
| strict_syntax=false></code>. (For more information about |
| why strict syntax is better than old syntax <a href="#ref_depr_oldsyntax">read this...</a>)</p> |
| </li> |
| |
| <li> |
| <p>Several classes were moved from the |
| <code class="inline-code">freemarker.template</code> package, to the new |
| <code class="inline-code">freemarker.core</code> package:</p> |
| |
| <ul> |
| <li> |
| "Normal" classes: <code class="inline-code">ArithmeticEngine</code>, |
| <code class="inline-code">Configurable</code>, |
| <em><code class="inline-code">Environment</code></em> |
| </li> |
| |
| <li> |
| Exceptions: |
| <code class="inline-code">InvalidReferenceException</code>, |
| <code class="inline-code">NonBooleanException</code>, |
| <code class="inline-code">NonNumericalException</code>, |
| <code class="inline-code">NonStringException</code>, |
| <code class="inline-code">ParseException</code>, |
| <code class="inline-code">StopException</code> |
| </li> |
| |
| <li> |
| Errors: <code class="inline-code">TokenMgrError</code> |
| </li> |
| </ul> |
| |
| <p>The main reason of the splitting of |
| <code class="inline-code">freemarker.template</code> package was that the |
| amount of "expert" public classes and interfaces grows too much, |
| as we introduce API-s for third-party tools, such as debugging |
| API.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code> |
| now returns <code class="inline-code">Object</code> instead of |
| <code class="inline-code">TemplateModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>White-space stripping is now more aggressive as before: it |
| always removes leading and trailing white-space if the line only |
| contains FTL tags. (Earlier the white-space was not removed if |
| the tag was <code class="inline-code"><#include |
| <em class="code-color">...</em>></code> or user-defined |
| directive tag with empty directive syntax as |
| <code class="inline-code"><@myMacro/></code> (or its equivalents: |
| <code class="inline-code"><@myMacro></@myMacro></code> and |
| <code class="inline-code"><@myMacro></@></code>). Now white-space |
| is removed in these cases as well.) Also, white-space sandwiched |
| between two non-outputting elements, such as macro definitions, |
| assignments, imports, or property settings, is now ignored. More |
| information: <a href="#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">function</code> directive is now used for |
| defining methods. You should replace <code class="inline-code">function</code> |
| with <code class="inline-code">macro</code> in your old templates. Note, |
| however, that old <code class="inline-code">function</code>-s will still work |
| if you don't use the <code class="inline-code">return</code> directive in |
| them, and you invoke them with the deprecated the |
| <code class="inline-code">call</code> directive.</p> |
| </li> |
| |
| <li> |
| <p>The expressions <code class="inline-code">as</code>, |
| <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now |
| keywords in the template language and cannot be used as |
| top-level variable names without square-bracket syntax. If, by |
| some chance, you have top-level variables that use one of these |
| names, you will have to rename them, or use the square-bracket |
| syntax with the <code class="inline-code">.vars</code> special variable: |
| <code class="inline-code">.vars["in"]</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">?new</code> built-in, as it was |
| implemented, was a security hole. Now, it only allows you to |
| instantiate a java object that implements the |
| <code class="inline-code">freemarker.template.TemplateModel</code> interface. |
| If you want the functionality of the <code class="inline-code">?new</code> |
| built-in as it existed in prior versions, make available an |
| instance of the |
| <code class="inline-code">freemarker.template.utility.ObjectConstructor</code> |
| class to your template. (For example: |
| <code class="inline-code">myDataModel.put("objConstructor", new |
| ObjectConstructor());</code>, and then in the template you |
| can do this: <code class="inline-code"><#assign aList = |
| objConstructor("java.util.ArrayList", 100)></code>)</p> |
| </li> |
| |
| <li> |
| <p>Changes to the |
| <code class="inline-code">FreemarkerServlet</code>:</p> |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">FreemarkerServlet</code> uses |
| <code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code> by default |
| instead of <code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>. |
| What this means is that, by default, objects of type |
| <code class="inline-code">java.lang.String</code>, |
| <code class="inline-code">java.lang.Number</code>, |
| <code class="inline-code">java.util.List</code>, and |
| <code class="inline-code">java.util.Map</code> will be wrapped as |
| <code class="inline-code">TemplateModels</code> via the classes |
| <code class="inline-code">SimpleScalar</code>, |
| <code class="inline-code">SimpleNumber</code>, |
| <code class="inline-code">SimpleSequence</code>, and |
| <code class="inline-code">SimpleHash</code> respectively. Thus, the java |
| methods on those objects will not be available. The default |
| wrapper implementation in FreeMarker 2.3 automatically knows |
| how to wrap Jython objects, and also wraps |
| <code class="inline-code">org.w3c.dom.Node</code> objects into instances |
| of <code class="inline-code">freemarker.ext.dom.NodeModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">FreemarkerServlet</code> base |
| implementation no longer deduces the locale used for |
| templates with <code class="inline-code">HttpRequest.getLocale()</code>. |
| Rather, it simply delegates to the new protected method, |
| <code class="inline-code">deduceLocale</code>. The default implementation |
| of this method simply returns the value of configuration the |
| <code class="inline-code">locale</code> setting.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_169">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Interpolation in string literals. For convenience, |
| interpolations are now supported in string literals. For |
| example: <code class="inline-code"><@message "Hello ${user}!" /></code> |
| is the same as <code class="inline-code"><@message "Hello " + user + "!" |
| /></code></p> |
| </li> |
| |
| <li> |
| <p>Raw string literals: In string literals prefixed with |
| <code class="inline-code">r</code>, interpolations and escape sequences will |
| not be interpreted as special tokens. For example: |
| <code class="inline-code">r"\n${x}"</code> will be simply interpreted as the |
| character sequence <code class="inline-code">'\'</code>, |
| <code class="inline-code">'n'</code>, <code class="inline-code">'$'</code>, |
| <code class="inline-code">'{'</code>, <code class="inline-code">'x'</code>, |
| <code class="inline-code">'}'</code>, and not as line-feed and the value of |
| the <code class="inline-code">x</code> variable.</p> |
| </li> |
| |
| <li> |
| <p>Method variables can be defined in FTL, with the <a href="#ref.directive.function"><code>function</code></a> |
| directive.</p> |
| </li> |
| |
| <li> |
| <p>Support for a variable number of macro parameters. If the |
| last parameter in a macro declaration ends with |
| <code class="inline-code">...</code>, all extra parameters passed to the macro |
| will be available via that parameter. For macros called with |
| positional parameters, the parameter will be a sequence. For |
| named parameters, the parameter will be a hash. Note that it all |
| works with the new <code class="inline-code">function</code> directive as |
| well.</p> |
| </li> |
| |
| <li> |
| <p>A new header parameter, <code class="inline-code">strip_text</code>, |
| that removes all top-level text from a template. This is useful |
| for ``include files'' to suppress newlines that separate the |
| macro definitions. See <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_specvar">special variable</a>: |
| <code class="inline-code">.vars</code>. This is useful to read top-level |
| variables with square bracket syntax, for example |
| <code class="inline-code">.vars["name-with-hyphens"]</code> and |
| <code class="inline-code">.vars[dynamicName]</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">macro</code> and assignment directives now |
| accept arbitrary destination variable name with quoted syntax. |
| For example: <code class="inline-code"><#macro |
| "name-with-hyphens"><em class="code-color">...</em></code> |
| or <code class="inline-code"><#assign "foo bar" = 123></code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">?keys</code> and |
| <code class="inline-code">?values</code> hash built-ins now return sequences. |
| In practical terms this means you can access their sizes or |
| retrieve their subvariables by index, and use all of the <a href="#ref_builtins_sequence">sequence built-ins</a>. (Note |
| for the programmers: The <code class="inline-code">TemplateHashModelEx</code> |
| interface has not been changed. Your old code will work. See the |
| API documentation to see why.)</p> |
| </li> |
| |
| <li> |
| <p>Existence built-ins (<code class="inline-code">?default</code>, |
| <code class="inline-code">?exists</code>, etc.) are now working with sequence |
| subvariables as well. Read the documentation of the |
| <code class="inline-code">default</code> built-in for more information.</p> |
| </li> |
| |
| <li> |
| <p>White-space stripping is now more aggressive as before: it |
| always removes leading and trailing white-space if the line only |
| contains FTL tags. (Earlier the white-space was not removed if |
| the tag was <code class="inline-code"><#include |
| <em class="code-color">...</em>></code> or user-defined |
| directive tag with empty directive syntax as |
| <code class="inline-code"><@myMacro/></code> (or its equivalents: |
| <code class="inline-code"><@myMacro></@myMacro></code> and |
| <code class="inline-code"><@myMacro></@></code>). Now white-space |
| is removed in these cases as well.) Also, top-level white-space |
| that separates macro definitions and/or assignments is now |
| ignored. More information: <a href="#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p> |
| </li> |
| |
| <li> |
| <p>White-space stripping can be disabled for a single line |
| with the <a href="#ref.directive.nt"><code>nt</code></a> |
| directive (for No Trim).</p> |
| </li> |
| |
| <li> |
| <p>Hashes can be concatenated using the <code class="inline-code">+</code> |
| operator. The keys in the hash on the right-hand side take |
| precedence.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for Java and JavaScript string escaping: |
| <a href="#ref_builtin_j_string">j_string</a> and <a href="#ref_builtin_js_string">js_string</a></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">replace</code> and |
| <code class="inline-code">split</code> built-ins now support case-insensitive |
| comparsion and regular expressions (J2SE 1.4+ only), and some |
| other new options. More information can be found <a href="#ref_builtin_string_flags">here</a>.</p> |
| </li> |
| |
| <li> |
| <p>New built-in for regular expression matching (J2SE 1.4+ |
| only): <a href="#ref_builtin_matches"><code>matches</code></a></p> |
| </li> |
| |
| <li> |
| <p>New built-in, <code class="inline-code">eval</code>, to evaluate a |
| string as FTL expression. For example |
| <code class="inline-code">"1+2"?eval</code> returns the number 3.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for Java and JavaScript string escaping: |
| <a href="#ref_builtin_j_string">j_string</a> and <a href="#ref_builtin_js_string">js_string</a></p> |
| </li> |
| |
| <li> |
| <p>New special variables to read the value of the locale |
| setting: <code class="inline-code">locale</code>, <code class="inline-code">lang</code>. See |
| more <a href="#ref_specvar">in the |
| reference...</a></p> |
| </li> |
| |
| <li> |
| <p>New special variable to read the FreeMarker version |
| number: <code class="inline-code">version</code>. See more <a href="#ref_specvar">in the reference...</a></p> |
| </li> |
| |
| <li> |
| <p>Tree new directives, <code class="inline-code">recurse</code>, |
| <code class="inline-code">visit</code> and <code class="inline-code">fallback</code>, were |
| introduced to support declarative node-tree processing. These |
| are meant to be used typically (though not exclusively) for |
| processing XML input. Together with this, a new variable type |
| has been introduced, the node type. See the <a href="#xgui_declarative">chapter on declarative XML |
| processing</a> for more details.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">?new</code> built-in, as it was |
| implemented, was a security hole. Now, it only allows you to |
| instantiate a java object that implements the |
| <code class="inline-code">freemarker.template.TemplateModel</code> interface. |
| <span class="marked-for-programmers">If you want the functionality of |
| the <code class="inline-code">?new</code> built-in as it existed in prior |
| versions, make available an instance of the |
| <code class="inline-code">freemarker.template.utility.ObjectConstructor</code> |
| class to your template. (For example: |
| <code class="inline-code">myDataModel.put("objConstructor", new |
| ObjectConstructor());</code>, and then in the template you |
| can do this: <code class="inline-code"><#assign aList = |
| objConstructor("java.util.ArrayList", |
| 100)></code>)</span></p> |
| </li> |
| |
| <li> |
| <p>Variable names can contain <code class="inline-code">@</code> anywhere |
| (without using quote-bracket syntax). For example: |
| <code class="inline-code"><#assign x@@@ = 123></code> is valid.</p> |
| </li> |
| |
| <li> |
| <p>The expressions <code class="inline-code">as</code>, |
| <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now |
| keywords in the template language and cannot be used as |
| top-level variable names without square-bracket syntax (as |
| <code class="inline-code">.vars["in"]</code>).</p> |
| </li> |
| |
| <li> |
| <p>New parameter to the <a href="#ref_directive_ftl"><code>ftl</code> |
| directive</a>: <code class="inline-code">attributes</code>. The value of |
| this attribute is a hash that associates arbitrary attributes |
| (name-value pairs) to the template. The values of the attributes |
| can be of any type (string, number, sequence... etc.). |
| FreeMarker doesn't try to understand the meaning of the |
| attributes. It's up to the application that encapsulates |
| FreeMarker (as a Web application framework). Thus, the set of |
| allowed attributes and their semantic is application (Web |
| application framework) dependent.</p> |
| </li> |
| |
| <li> |
| <p>Other minor quality improvements...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_170">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Smarter default object wrapping: The default object |
| wrapper is now |
| <code class="inline-code">freemarker.template.DefaultObjectWrapper</code>, |
| which falls back on wrapping arbitrary objects as beans using |
| the <code class="inline-code">freemarker.ext.beans.BeansWrapper</code>. Also, |
| it will wrap <code class="inline-code">org.w3c.dom.Node</code> objects with |
| the new DOM wrapper. Also, it is aware of Jython objects, and |
| will use <code class="inline-code">freemarker.ext.jython.JythonWrapper</code> |
| if the object passed in is a Jython object. (We count it as a |
| backward compatible change, since this new object wrapper wraps |
| differently only those objects that the old wrapper was not able |
| to wrap, so it has thrown exception.)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code> |
| now returns <code class="inline-code">Object</code> instead of |
| <code class="inline-code">TemplateModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>The default (initial) value of the |
| <code class="inline-code">strict_syntax</code> setting has been changed from |
| <code class="inline-code">false</code> to <code class="inline-code">true</code>. When |
| <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>, |
| tags with old syntax as <code class="inline-code"><include |
| "foo.ftl"></code> will be considered as static text (so |
| they go to the output as-is, like HTML tags do), and not as FTL |
| tags. Such tags have to be rewritten to <code class="inline-code"><#include |
| "foo.ftl"></code>, since only parts that starts with |
| <code class="inline-code"><#</code>, <code class="inline-code"></#</code>, |
| <code class="inline-code"><@</code>, or <code class="inline-code"></@</code> count as |
| FTL tags. Or, to recover the old transitional behavior, where |
| both legacy and new tag syntax was recognized, you have to |
| explicitly set <code class="inline-code">strict_syntax</code> to |
| <code class="inline-code">false</code>: |
| <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for |
| individual templates you can force the old behavior by starting |
| the template with <code class="inline-code"><#ftl |
| strict_syntax=false></code>. (For more information about |
| why strict syntax is better than old syntax <a href="#ref_depr_oldsyntax">read this...</a>)</p> |
| </li> |
| |
| <li> |
| <p>New <code class="inline-code">CacheStorage</code> implementation: |
| <code class="inline-code">freemarker.cache.MruCacheStorage</code>. This cache |
| storage implements a two-level Most Recently Used cache. In the |
| first level, items are strongly referenced up to the specified |
| maximum. When the maximum is exceeded, the least recently used |
| item is moved into the second level cache, where they are softly |
| referenced, up to another specified maximum. |
| <code class="inline-code">freemarker.cache.SoftCachseStorage</code> and |
| <code class="inline-code">StrongCachseStorage</code> are deprected, |
| <code class="inline-code">MruCachseStorage</code> is used everywhere instead. |
| The default cache storage is now an |
| <code class="inline-code">MruCachseStorage</code> object with 0 strong size, |
| and infinite soft size. |
| <code class="inline-code">Configuration.setSetting</code> for |
| <code class="inline-code">cache_storage</code> now understands string values |
| as <code class="inline-code">"strong:200, soft:2000"</code>.</p> |
| </li> |
| |
| <li> |
| <p>For <code class="inline-code">BeansWrapper</code> generated models, you |
| can now use the <code class="inline-code">${obj.method(args)}</code> syntax to |
| invoke methods whose return type is <code class="inline-code">void</code>. |
| <code class="inline-code">void</code> methods now return |
| <code class="inline-code">TemplateModel.NOTHING</code> as their return |
| value.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.SimpleHash</code> now can |
| wrap read-only <code class="inline-code">Map</code>-s, such as the map of HTTP |
| request parameters in Servlet API.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">TemplateNodeModel</code> interface was |
| introduced to support recursive processing of trees of nodes. |
| Typically, this will be used in relation to XML.</p> |
| </li> |
| |
| <li> |
| <p>New package: <code class="inline-code">freemarker.ext.dom</code>. This |
| contains the new XML wrapper, that supports the processing of |
| XML documents using the visitor pattern (i.e. with |
| <code class="inline-code"><#visit <em class="code-color">...</em>></code> |
| and similar directives), and to provide more convenient XML |
| traversing as the legacy wrapper. See the <a href="#xgui">XML processing guide</a> for more |
| details.</p> |
| </li> |
| |
| <li> |
| <p>New package: <code class="inline-code">freemarker.core</code>. Classes |
| used by mostly power-users was moved here from the |
| <code class="inline-code">freemarker.template</code> package. The main reason |
| of the splitting of <code class="inline-code">freemarker.template</code> |
| package was that the amount of "expert" public classes and |
| interfaces grows too much, as we introduce API-s for third-party |
| tools, such as debugging API.</p> |
| </li> |
| |
| <li> |
| <p>New package: <code class="inline-code">freemarker.debug</code>. This |
| provides a debugging API, by which you can debug executing |
| templates through network (RMI). You have to write the front-end |
| (client), as the API is just the server side. For more |
| information please read the JavaDoc of the |
| <code class="inline-code">freemarker.debug</code> package.</p> |
| </li> |
| |
| <li> |
| <p>You can query the FreeMarker version number with static |
| method <code class="inline-code">Configuration.getVersionNumber()</code>. |
| Also, the <code class="inline-code">Manifest.mf</code> included in |
| <code class="inline-code">freemarker.jar</code> now contains the FreeMarker |
| version number, furthermore, executing it with <code class="inline-code">java |
| -jar freemarker.jar</code> will print the version number to |
| the stdout.</p> |
| </li> |
| |
| <li> |
| <p>Added a new protected <code class="inline-code">FreemarkerServlet</code> |
| method: <code class="inline-code">Configuration |
| getConfiguration()</code>.</p> |
| </li> |
| |
| <li> |
| <p>Date support is now labeled as final. (It was experimental |
| earlier.)</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> has been improved to |
| prevent some security exceptions when introspecting.</p> |
| </li> |
| |
| <li> |
| <p>Other minor quality improvements and extensions...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_171">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Fixes and improvements in the Manual and in the API |
| JavaDoc.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_172">The history of the releases before the final version</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_173">Differences between the final release and Release Candidate |
| 4</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Added a new special variable to print the FreeMarker |
| version number: <code class="inline-code">version</code>. See more <a href="#ref_specvar">in the reference...</a></p> |
| </li> |
| |
| <li> |
| <p>Minor documentation fixes and improvements.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_174">Differences between the Release Candidate 4 and Release |
| Candidate 3</h6> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> has been improved to |
| prevent some security exceptions when introspecting.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">FreemarkerXmlTask</code> has two new |
| sub-tasks that can be used to prepare template execution with |
| Jython scripts: <code class="inline-code">prepareModel</code> and |
| <code class="inline-code">prepareEnvironment</code>. The |
| <code class="inline-code">jython</code> sub-task is now deprecated, and does |
| the same as <code class="inline-code">prepareEnvironment</code>. See the |
| Java API documentation for more details.</p> |
| </li> |
| |
| <li> |
| <p>New special variable to read the FreeMarker version |
| number: <code class="inline-code">version</code>. See more <a href="#ref_specvar">in the reference...</a></p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Greater-than sign doesn't confuse the |
| <code class="inline-code">eval</code> built-in anymore.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">BeansWrapper</code> now wrapps |
| the <code class="inline-code">null</code> return values of methods |
| appropriately.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">FreemarkerXmlTask</code> doesn't |
| need Jython classes anymore, unless you really use Jython |
| scripts. Several other bugfixes in the Jython related |
| features.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: If the template exception handler has ignored |
| the exception, errors occurring in interpolations inside FTL |
| tags (e.g. <code class="inline-code"><#if "foo${badVar}" != |
| "foobar"></code>) were handled in the same way as errors |
| occuring in interpolations outside FTL tags. Thus, the |
| directive call was not skipped, and the problematic |
| interpolation was replaced with an empty string. (This was |
| inconsistent with the behavior of <code class="inline-code"><#if |
| "foo"+badVar != "foobar"></code>, which should be 100% |
| equivalent with the previous example.)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">FileTemplateLoader</code> is now |
| more robust when it receives paths that are malformed |
| according the native file system. In the earlier version such |
| paths sometimes caused unexpected |
| <code class="inline-code">IOException</code> that aborted the searching for |
| the template in further |
| <code class="inline-code">FileTemplateLoader</code>-s when you use the |
| <code class="inline-code">MultiTemplateLoader</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_175">Differences between the Release Candidate 3 and Release |
| Candidate 2</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: Fixing a fatal bug in the template cache that |
| was introduced with the latest cache ``bugfix''. The template |
| cache has always reloaded the unchanged template when the |
| update delay has been elapsed, until the template has been |
| actually changed, in which case it has never reloaded the |
| template anymore.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_176">Differences between the Release Candidate 2 and Release |
| Candidate 1</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: The template cache didn't reload the template |
| when it was replaced with an older version.</p> |
| </li> |
| |
| <li> |
| <p>API JavaDoc fix: date/time related classes/interfaces |
| were marked as experimental. They are not experimental.</p> |
| </li> |
| |
| <li> |
| <p>Minor site improvements.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_177">Differences between the Release Candidate 1 and Preview 16 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p><em>Warning! Non-backward-compatible |
| change!</em> The default (initial) value of the |
| <code class="inline-code">strict_syntax</code> setting has been changed from |
| <code class="inline-code">false</code> to <code class="inline-code">true</code>. When |
| <code class="inline-code">strict_syntax</code> is <code class="inline-code">true</code>, |
| tags with old syntax as <code class="inline-code"><include |
| "foo.ftl"></code> will be considered as static text (so |
| they go to the output as-is, like HTML tags do), and not as |
| FTL tags. Such tags have to be rewritten to |
| <code class="inline-code"><#include "foo.ftl"></code>, since only |
| parts that starts with <code class="inline-code"><#</code>, |
| <code class="inline-code"></#</code>, <code class="inline-code"><@</code>, or |
| <code class="inline-code"></@</code> count as FTL tags. Or, to recover |
| the old transitional behavior, where both legacy and new tag |
| syntax was recognized, you have to explicitly set |
| <code class="inline-code">strict_syntax</code> to <code class="inline-code">false</code>: |
| <code class="inline-code">cfg.setStrictSyntaxMode(false)</code>. Also, for |
| individual templates you can force the old behavior by |
| starting the template with <code class="inline-code"><#ftl |
| strict_syntax=false></code>. (For more information about |
| why strict syntax is better than old syntax <a href="#ref_depr_oldsyntax">read this...</a>)</p> |
| </li> |
| |
| <li> |
| <p>New parameter to the <a href="#ref_directive_ftl"><code>ftl</code> |
| directive</a>: <code class="inline-code">attributes</code>. The value of |
| this attribute is a hash that associates arbitrary attributes |
| (name-value pairs) to the template. The values of the |
| attributes can be of any type (string, number, sequence... |
| etc.). FreeMarker doesn't try to understand the meaning of the |
| attributes. It's up to the application that encapsulates |
| FreeMarker (as a Web application framework). Thus, the set of |
| allowed attributes and their semantic is application (Web |
| application framework) dependent.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.template.utility.DeepUnwrap</code> |
| unwrapped sequences to empty |
| <code class="inline-code">ArrayList</code>-s.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: If you included/imported a template with |
| <code class="inline-code">*/</code> in path (acquisition), and that template |
| in turn itself included/imported another template with |
| <code class="inline-code">*/</code> in path, it may failed.</p> |
| </li> |
| |
| <li> |
| <p>New methods to the |
| <code class="inline-code">freemarker.core.Environment</code>: |
| <code class="inline-code">importLib(Template loadedTemplate, java.lang.String |
| namespace)</code>, |
| <code class="inline-code">getTemplateForImporting(...)</code>, |
| <code class="inline-code">getTemplateForInclusion(...)</code>.</p> |
| </li> |
| |
| <li> |
| <p>Improvements in the |
| <code class="inline-code">java.io.IOException</code> related error messages |
| of the <code class="inline-code">include</code> and |
| <code class="inline-code">import</code> directives.</p> |
| </li> |
| |
| <li> |
| <p>Minor improvements in the documentation.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_178">Differences between the Preview 16 and Preview 15 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>New package: <code class="inline-code">freemarker.debug</code>. This |
| provides a debugging API, by which you can debug executing |
| templates through network (RMI). You have to write the |
| front-end (client), as the API is just the server side. For |
| more information please read the JavaDoc of the |
| <code class="inline-code">freemarker.debug</code> package. (The debugging |
| API is present for a while, just I forgot to announce it in |
| the version history. Sorry for that.)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: With the new XML wrapper, |
| <code class="inline-code">@@markup</code> and similar special keys:</p> |
| |
| <ul> |
| <li> |
| <p>have returned |
| <code class="inline-code"><foo></foo></code> for empty |
| elements instead of <code class="inline-code"><foo /></code>. |
| Other than it was needlessly verbose, it has confused |
| browsers if you generate HTML.</p> |
| </li> |
| |
| <li> |
| <p>have showed the attributes that have no explicitly |
| given value in the original document, just a default value |
| coming form the DTD.</p> |
| </li> |
| |
| <li> |
| <p>have forgot to put space before the system |
| identifier in the <code class="inline-code"><!DOCTYPE |
| <em class="code-color">...</em>></code>.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Bugfix: XPath with Jaxen has died with |
| <code class="inline-code">NullPointerException</code> if the context was an |
| empty node set.</p> |
| </li> |
| |
| <li> |
| <p>A bit more intelligent Xalan XPath error |
| messages.</p> |
| </li> |
| |
| <li> |
| <p>Revoked fallback-to-classloader logic from the template |
| cache.</p> |
| </li> |
| |
| <li> |
| <p>From now, if no XPath engine is available, and the hash |
| key in an ``XML query'' can't be interpreted without XPath, an |
| error will tell this clearly, rather than silently returning |
| undefined variable (null).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Some templates have caused the parser to |
| die.</p> |
| </li> |
| |
| <li> |
| <p>Some other minor improvements here and there...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_179">Differences between the Preview 15 and Preview 14 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: The new default template cache storage |
| (<code class="inline-code">MruCacheStorage</code>) has started to |
| continually fail with <code class="inline-code">NullPointerException</code> |
| from a random point of time, usually when the memory usage was |
| high in the JVM.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: In error messages, when the quoted FTL directive |
| had nested content, that was quoted as well, so the quotation |
| could be very long and expose nested lines needlessly.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_180">Differences between the Preview 14 and Preview 13 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateMethodModel.exec</code> |
| now returns <code class="inline-code">Object</code> instead of |
| <code class="inline-code">TemplateModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>Fixes and improvements for XPath with Jaxen (not Xalan). |
| Non-node-set XPath expressions are now working. FreeMarker |
| variables are accessible in XPath expressions with XPath |
| variable references (e.g. |
| <code class="inline-code">doc["book/chapter[title=$currentTitle]"]</code>).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.cache.SoftCachseStorage</code> |
| and <code class="inline-code">StrongCachseStorage</code> is deprected. The |
| more flexible <code class="inline-code">MruCachseStorage</code> is used |
| instead everywhere. The default cache storage is now an |
| <code class="inline-code">MruCachseStorage</code> object with 0 strong size, |
| and infinite soft size. |
| <code class="inline-code">Configuration.setSetting</code> for |
| <code class="inline-code">cache_storage</code> now understands string values |
| as <code class="inline-code">"strong:200, soft:2000"</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.cache.MruCachseStorage</code> has died |
| with <code class="inline-code">ClassCastException</code> sometimes.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for Java and JavaScript string escaping: |
| <a href="#ref_builtin_j_string">j_string</a> and <a href="#ref_builtin_js_string">js_string</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</code> |
| now prints more HTML-context-proof messages.</p> |
| </li> |
| |
| <li> |
| <p>You can query the FreeMarker version number with static |
| method <code class="inline-code">Configuration.getVersionNumber()</code>. |
| Also, the <code class="inline-code">Manifest.mf</code> included in |
| <code class="inline-code">freemarker.jar</code> now contains the FreeMarker |
| version number, furthermore, executing it with <code class="inline-code">java |
| -jar freemarker.jar</code> will print the version number to |
| the stdout.</p> |
| </li> |
| |
| <li> |
| <p>Added a new protected |
| <code class="inline-code">FreemarkerServlet</code> method: |
| <code class="inline-code">Configuration getConfiguration()</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: FreeMarker has frozen on empty conditional |
| blocks in certain contexts.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Methods called twice on an object using the |
| <code class="inline-code">list</code> directive, as |
| <code class="inline-code">parent.getChildren()</code> with |
| <code class="inline-code"><#list parent.children as child> |
| ...</#list></code></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_181">Differences between the Preview 13 and Preview 12 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>White-space stripping is now more aggressive as before: |
| it always removes leading and trailing white-space if the line |
| only contains FTL tags. (Earlier the white-space was not |
| removed if the tag was <code class="inline-code"><#include |
| <em class="code-color">...</em>></code> or user-defined |
| directive tag with empty directive syntax as |
| <code class="inline-code"><@myMacro/></code> (or its equivalents: |
| <code class="inline-code"><@myMacro></@myMacro></code> and |
| <code class="inline-code"><@myMacro></@></code>). Now |
| white-space is removed in these cases as well.) Also, |
| top-level white-space that separates macro definitions and/or |
| assignments is now ignored. More information: <a href="#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p> |
| </li> |
| |
| <li> |
| <p>White-space stripping can be disabled for a single line |
| with the <a href="#ref.directive.nt"><code>nt</code></a> |
| directive (for No Trim).</p> |
| </li> |
| |
| <li> |
| <p>A new directive for the declarative XML processing: |
| <a href="#ref.directive.fallback"><code>fallback</code></a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.SimpleHash</code> now |
| can wrap read-only <code class="inline-code">Map</code>-s, such as the map |
| of HTTP request parameters in Servlet API.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_182">Differences between the Preview 12 and Preview 11 |
| releases</h6> |
| |
| |
| <p>The only change between this and the previous preview |
| release is that Preview 11 had a bug where DOM trees would |
| <em>never</em> be garbage-collected.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_183">Differences between the Preview 11 and Preview 10 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Many XML related changes. Some of them are incompatible |
| with the previous preview releases! For a more detailed |
| explanation of how XML related features now work, see: <a href="#xgui">XML Processing Guide</a></p> |
| |
| <ul> |
| <li> |
| <p>Attention! Attribute queries such as |
| <code class="inline-code">foo.@bar</code> now return sequences |
| (similarly to child element queries and XPath queries), |
| not single nodes. Because of the rule with node sequences |
| of size 1, it is still good to write |
| <code class="inline-code">${foo.@bar}</code>, but built-ins such as |
| <code class="inline-code">?exists</code>, <code class="inline-code">?if_exists</code> |
| or <code class="inline-code">?default</code> don't work as before. For |
| example, instead of |
| <code class="inline-code">foo.@bar?default('black')</code>, you now have |
| to write <code class="inline-code">foo.@bar[0]?default('black')</code>. |
| So if you have used existence built-ins with attributes, |
| you have to find those occurrences in the templates and |
| add that <code class="inline-code">[0]</code>.</p> |
| </li> |
| |
| <li> |
| <p>Attention! XML name-space handling has been totally |
| reworked and is absolutely incompatible with pre 10. Don't |
| worry about this if none of your XML input documents use |
| you use <code class="inline-code">xmlns</code> attributes. Worry, |
| though, if you have utilized the ``loose mode'', where |
| only the local name of elements were compared, because |
| that's now gone. Sorry...</p> |
| </li> |
| |
| <li> |
| <p>Attention! Special-keys <code class="inline-code">@@</code> and |
| <code class="inline-code">@*</code> now return a sequence of attribute |
| nodes instead of the hash of them.</p> |
| </li> |
| |
| <li> |
| <p>Several hash keys are now working for node sequences |
| that store multiple nodes. For example, to get the list of |
| all <code class="inline-code">para</code> elements of all |
| <code class="inline-code">chapter</code>-s, just write |
| <code class="inline-code">doc.book.chapter.para</code>. Or, to get list |
| of title attributes of all <code class="inline-code">chapter</code>-s |
| write <code class="inline-code">doc.book.chapter.@title</code>.</p> |
| </li> |
| |
| <li> |
| <p>New special hash keys: <code class="inline-code">**</code>, |
| <code class="inline-code">@@start_tag</code>, |
| <code class="inline-code">@@end_tag</code>, |
| <code class="inline-code">@@attribute_markup</code>, |
| <code class="inline-code">@@text</code>, |
| <code class="inline-code">@@qname</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">?parent</code> for attribute nodes now |
| returns the element node the attribute node belongs |
| to.</p> |
| </li> |
| |
| <li> |
| <p>You can use Jaxen instead of Xalan for XPath |
| expressions, if you call the static |
| <code class="inline-code">freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</code> |
| method once. We plan to use Jaxen automatically instead of |
| Xalan if it is available, just the Jaxen support is not |
| fully functional yet.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>New special variable: <code class="inline-code">.vars</code>. This is |
| useful to read top-level variables with square bracket syntax, |
| for example <code class="inline-code">.vars["name-with-hyphens"]</code> and |
| <code class="inline-code">.vars[dynamicName]</code>.</p> |
| </li> |
| |
| <li> |
| <p>New built-in, <code class="inline-code">eval</code>, to evaluate a |
| string as FTL expression. For example |
| <code class="inline-code">"1+2"?eval</code> returns the number 3.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FreemarkerServlet</code> now uses the |
| configuration's <code class="inline-code">locale</code> setting, rather than |
| <code class="inline-code">Locale.getDefault()</code>, to set the locale of |
| the templates. Also, the signature of the |
| <code class="inline-code">deduceLocale</code> method has been |
| changed.</p> |
| </li> |
| |
| <li> |
| <p>We have a new (beta status) |
| <code class="inline-code">CacheStorage</code> implementation: |
| <code class="inline-code">freemarker.cache.MruCacheStorage</code>. This |
| cache storage implements a two-level Most Recently Used cache. |
| In the first level, items are strongly referenced up to the |
| specified maximum. When the maximum is exceeded, the least |
| recently used item is moved into the second level cache, where |
| they are softly referenced, up to another specified maximum. |
| You can plug to try it with <code class="inline-code">cfg.setCacheStorage(new |
| freemarker.cache.MruCacheStorage(maxStrongSize, |
| maxSoftSize))</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_184">Differences between the Preview 10 and Preview 9 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>The special key <code class="inline-code">@@xmlns</code> was removed |
| in favor of a new FTL directive for the same purpose, |
| <code class="inline-code"><#xmlns...></code>.</p> |
| </li> |
| |
| <li> |
| <p>By default, the system is stricter about the use of |
| namespace prefixes. In general, you must use a prefix to |
| qualify subelements that are associated with an XML |
| nampespace. You can do this with the new |
| <code class="inline-code"><#xmlns...></code> directive, but prefixes |
| declared in the input XML doc will actually work with no |
| declaration.</p> |
| </li> |
| |
| <li> |
| <p>Introduced a new special key called |
| <code class="inline-code">@@text</code> that returns all the text nodes |
| contained (recursively) in an element all concatenated |
| together.</p> |
| </li> |
| |
| <li> |
| <p>Either Jaxen or Xalan can be used to provide XPath |
| functionality. Prior versions only worked with Xalan.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">FreemarkerServlet</code> uses |
| <code class="inline-code">ObjectWrapper.DEFAULT_WRAPPER</code> by default |
| instead of <code class="inline-code">ObjectWrapper.BEANS_WRAPPER</code>. |
| What this means is that, by default, objects of type |
| <code class="inline-code">java.lang.String</code>, |
| <code class="inline-code">java.lang.Number</code>, |
| <code class="inline-code">java.util.List</code>, and |
| <code class="inline-code">java.util.Map</code> will be wrapped as |
| <code class="inline-code">TemplateModels</code> via the classes |
| <code class="inline-code">SimpleScalar</code>, |
| <code class="inline-code">SimpleNumber</code>, |
| <code class="inline-code">SimpleSequence</code>, and |
| <code class="inline-code">SimpleHash</code> respectively. Thus, the java |
| methods on those objects will not be available. The default |
| wrapper implementation in FreeMarker 2.3 automatically knows |
| how to wrap Jython objects, and also wraps |
| <code class="inline-code">org.w3c.dom.Node</code> objects into instances of |
| <code class="inline-code">freemarker.ext.dom.NodeModel</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">FreemarkerServlet</code> base |
| implementation no longer deduces the locale to use from the |
| HttpRequest.getLocale() hook. Rather, it simply delegates to a |
| <code class="inline-code">deduceLocale()</code> hook that is overridable in |
| subclasses. The base implementation simply uses |
| <code class="inline-code">Locale.getDefault()</code></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_185">Differences between the Preview 9 and Preview 8 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Fixed bugs introduced with Preview 8: XPath, |
| <code class="inline-code">@@markup</code> and |
| <code class="inline-code">@@nested_markup</code> now works with the document |
| node.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_186">Differences between the Preview 8 and Preview 7 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">macro</code> and assignment directives now |
| accept arbitrary destination variable name with quoted syntax. |
| For example: <code class="inline-code"><#macro |
| "foo-bar"><em class="code-color">...</em></code> or |
| <code class="inline-code"><#assign "this+that" = 123></code>. This is |
| important, because XML element names can contain hyphen, and |
| it was not possible to define a handler macro for those |
| elements, till now.</p> |
| </li> |
| |
| <li> |
| <p>Special key <code class="inline-code">@@content</code> was renamed to |
| <code class="inline-code">@@nested_markup</code>.</p> |
| </li> |
| |
| <li> |
| <p>Fixed outdated XML related Manual parts (that were |
| outdated even in Preview 7).</p> |
| </li> |
| |
| <li> |
| <p>Better parse-error messages.</p> |
| </li> |
| |
| <li> |
| <p>Minor bugfixes here and there...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_187">Differences between the Preview 7 and Preview 6 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Caching of XPath queries should lead to significant |
| performance improvements for XML processing, at least when |
| XPath is heavily used.</p> |
| </li> |
| |
| <li> |
| <p>Refinements in handling of XML namespaces in the XML |
| processing functionality. The new |
| <code class="inline-code">strict_namespace_handling</code> setting |
| introduced in 2.3pre6 was removed. A general-purpose solution |
| was arrived at that should make that configuration setting |
| unnecessary.</p> |
| </li> |
| |
| <li> |
| <p>Special key <code class="inline-code">@xmlns</code> was renamed to |
| @@xmlns. Reserved namespace prefix <code class="inline-code">default</code> |
| was renamed to <code class="inline-code">@@default</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">ftl</code> directive now accepts |
| non-string types.</p> |
| </li> |
| |
| <li> |
| <p>New special keys were introduced for XML node wrappers |
| in the freemarker.ext.dom package. The |
| <code class="inline-code">@@markup</code> key returns the literal markup |
| that make up that element and the <code class="inline-code">@@content</code> |
| key returns all the element's markup excluding the opening and |
| closing tags.</p> |
| </li> |
| |
| <li> |
| <p>Minor bugfixes here and there...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_188">Differences between the Preview 6 and Preview 5 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Existence built-ins (<code class="inline-code">?default</code>, |
| <code class="inline-code">?exists</code>, etc.) now work with sequence |
| subvariables as well. Read the <a href="#ref.directive.default">documentation of the |
| <code>default</code> built-in</a> for more |
| information.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">matches</code> built-in now returns a |
| sequence instead of a collection.</p> |
| </li> |
| |
| <li> |
| <p>Refinements in handling of XML namespaces in the XML |
| processing functionality. A new setting, |
| <code class="inline-code">strict_namespace_handling</code> was introduced. |
| If this is set (it is off by default) any node-handling macro |
| used in with the visit/recurse machinery must be from a macro |
| library that declares in its ftl header that it handles the |
| namespace in question.</p> |
| </li> |
| |
| <li> |
| <p>Minor bugfixes here and there...</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_189">Differences between the Preview 5 and Preview 4 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">replace</code> and |
| <code class="inline-code">split</code> built-ins now support |
| case-insensitive comparison and regular expressions (J2SE 1.4+ |
| only), and some other new options. More information can be |
| found <a href="#ref_builtin_string_flags">here</a>.</p> |
| </li> |
| |
| <li> |
| <p>New butilt-in for regular expression matching (J2SE 1.4+ |
| only): <a href="#ref_builtin_matches"><code>matches</code></a></p> |
| </li> |
| |
| <li> |
| <p>Minor bugfixes here and there...</p> |
| </li> |
| |
| <li> |
| <p>Manual: More browser-safe HTML-s. More updated |
| content.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_190">Differences between the Preview 4 and Preview 3 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: with multi-type variables, <code class="inline-code">+</code> |
| operator overload for hash type had higher precedence than the |
| precedence of some older overloads.</p> |
| </li> |
| |
| <li> |
| <p>The API documentation was missing from the distribution |
| <code class="inline-code">tar.gz</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_191">Differences between the Preview 3 and Preview 2 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>XML processing: Many various bugfixes, especially with |
| the declarative processing.</p> |
| </li> |
| |
| <li> |
| <p>XML processing: the <code class="inline-code">namespace_uri</code> |
| built-in, the <code class="inline-code">xmlnsuri</code> header parameter, |
| and the <code class="inline-code">TemplateNodeModel.getNodeNamespace</code> |
| method were renamed to <code class="inline-code">node_namespace</code> and |
| <code class="inline-code">getNodeNamespace</code> respectively.</p> |
| </li> |
| |
| <li> |
| <p>XML processing: Better documentation. Especially, note: |
| <a href="#xgui">XML Processing Guide</a></p> |
| </li> |
| |
| <li> |
| <p>A new header parameter, <code class="inline-code">strip_text</code>, |
| that removes all top-level text from a template. See <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>Support for a variable number of macro parameters. If |
| the last parameter in a macro declaration ends with |
| <code class="inline-code">...</code>, all extra parameters passed to the |
| macro will be available via that parameter. For macros called |
| with positional parameters, the parameter will be a sequence. |
| For named parameters, the parameter will be a hash.</p> |
| </li> |
| |
| <li> |
| <p>For <code class="inline-code">BeansWrapper</code> generated models, |
| you can now use the <code class="inline-code">${obj.method(args)}</code> |
| syntax to invoke methods whose return type is |
| <code class="inline-code">void</code>. <code class="inline-code">void</code> methods now |
| return <code class="inline-code">TemplateModel.NOTHING</code> as their |
| return value.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_192">Differences between the Preview 2 and Preview 1 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">freemarker.ext.dom.NodeModel</code> API |
| changed slightly. The <code class="inline-code">setDocumentBuilder()</code> |
| method was changed to |
| <code class="inline-code">setDocumentBuilderFactory()</code> because the |
| older scheme was not thread-safe. The |
| <code class="inline-code">stripComments</code> and |
| <code class="inline-code">stripPIs</code> methods are renamed to The |
| <code class="inline-code">removeComments</code> and |
| <code class="inline-code">removePIs</code>, and are fixed now. A new method, |
| <code class="inline-code">simplify</code> has been added.</p> |
| </li> |
| |
| <li> |
| <p>The expressions <code class="inline-code">as</code>, |
| <code class="inline-code">in</code>, and <code class="inline-code">using</code> are now |
| keywords in the template language and cannot be used as |
| top-level variable names without square-bracket syntax (as |
| <code class="inline-code">.vars["in"]</code>). If, by some chance, you have |
| top-level variables that use one of these names, you will have |
| to rename them (or use the square-bracket syntax). Sorry for |
| the inconvenience.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">?new</code> built-in, as it was |
| implemented, was a security hole. Now, it only allows you to |
| instantiate a java object that implements the |
| <code class="inline-code">freemarker.template.TemplateModel</code> |
| interface. If you want the functionality of the |
| <code class="inline-code">?new</code> built-in as it existed in prior |
| versions, make available an instance of the new |
| <code class="inline-code">freemarker.template.utility.ObjectConstructor</code> |
| class to your template.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code"><#recurse></code> directive was |
| broken. It did not work with a <code class="inline-code">using</code> |
| clause. This is now fixed.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_8">2.2.8</h4> |
| |
| |
| <p>Date of release: 2004-June-15</p> |
| |
| <p>Bugfix and maintenance release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_193">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Added a new special variable to print the FreeMarker |
| version number: <code class="inline-code">version</code>. See more <a href="#ref_specvar">in the reference...</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_194">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> has been improved to |
| prevent some security exceptions when introspecting.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">FileTemplateLoader</code> is now |
| more robust when it receives paths that are malformed according |
| the native file system. In the earlier version such paths |
| sometimes caused unexpected <code class="inline-code">IOException</code> that |
| aborted the searching for the template in further |
| <code class="inline-code">FileTemplateLoader</code>-s when you use the |
| <code class="inline-code">MultiTemplateLoader</code>.</p> |
| </li> |
| |
| <li> |
| <p>Some parts of the FreeMarker code has been marked as |
| privileged code section, so you can grant extra privileges to |
| FreeMarker when you use a security manager (this is a |
| backporting from 2.3). See more <a href="#pgui_misc_secureenv">here...</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_195">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Minor documentation fixes and improvements.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_7">2.2.7</h4> |
| |
| |
| <p>Date of release: 2004-March-17</p> |
| |
| <p>Important bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_196">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: Fixing a fatal bug in the template cache that was |
| introduced with the latest cache ``bugfix''. The template cache |
| has always reloaded the unchanged template when the update delay |
| has been elapsed, until the template has been actually changed, |
| in which case it has never reloaded the template anymore.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_6">2.2.6</h4> |
| |
| |
| <p>Date of release: 2004-March-13</p> |
| |
| <p>Maintenance and bugfix release. Some of improvements are |
| back-portings from FreeMarker 2.3rc1.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_197">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New <a href="#ref_specvar">special variable</a>: |
| <code class="inline-code">.vars</code>. This is useful to read top-level |
| variables with square bracket syntax, for example |
| <code class="inline-code">.vars["name-with-hyphens"]</code> and |
| <code class="inline-code">.vars[dynamicName]</code>.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for Java and JavaScript string escaping: |
| <a href="#ref_builtin_j_string">j_string</a> and <a href="#ref_builtin_js_string">js_string</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_198">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: The template cache didn't reload the template when |
| it was replaced with an older version.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">freemarker.template.utility.DeepUnwrap</code> |
| unwrapped sequences to empty |
| <code class="inline-code">ArrayList</code>-s.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: In error messages, when the quoted FTL directive |
| had nested content, that was quoted as well, so the quotation |
| could be very long and expose nested lines needlessly.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER</code> |
| now prints more HTML-context-proof messages.</p> |
| </li> |
| |
| <li> |
| <p>You can query the FreeMarker version number with static |
| method <code class="inline-code">Configuration.getVersionNumber()</code>. |
| Also, the <code class="inline-code">Manifest.mf</code> included in |
| <code class="inline-code">freemarker.jar</code> now contains the FreeMarker |
| version number, furthermore, executing it with <code class="inline-code">java |
| -jar freemarker.jar</code> will print the version number to |
| the stdout.</p> |
| </li> |
| |
| <li> |
| <p>Date support is now labeled as final. (It was experimental |
| earlier.) There was no change since FreeMarker 2.2.1.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_199">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Fixes and improvements in the Manual and in the API |
| JavaDoc. The documentation now works with the Eclipse help |
| plugin (accessible in the ``Editor/IDE plugins'' section of the |
| FreeMarker Web page).</p> |
| </li> |
| |
| <li> |
| <p>Minor site improvements.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_5">2.2.5</h4> |
| |
| |
| <p>Date of release: 2003-09-19</p> |
| |
| <p>Maintenance and bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_200">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Creating a <code class="inline-code">Configuration</code> instance using |
| the default constructor no longer fails if the current directory |
| is unreadable due to I/O problems, lack of security permissions, |
| or any other exception.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_4">2.2.4</h4> |
| |
| |
| <p>Date of release: 2003-09-03</p> |
| |
| <p>Maintenance and bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_201">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Improvements to JSP taglib support. If some third party |
| taglib didn't work for you with FreeMarker, maybe now it |
| will.</p> |
| |
| <ul> |
| <li> |
| <p>The JSP <code class="inline-code">PageContext</code> now implements |
| <code class="inline-code">forward</code> and <code class="inline-code">include</code> |
| methods.</p> |
| </li> |
| |
| <li> |
| <p>Accepting <code class="inline-code">EVAL_PAGE</code> as an alias to |
| <code class="inline-code">SKIP_BODY</code> in return values from |
| <code class="inline-code">doStartTag</code>. It's a common bug in some |
| widespread tag libraries, and now FreeMarker is less strict |
| and accepts it.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Fixes for some rare problems regarding namespaces of |
| macros.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_202">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Minor improvements to the documentation.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_3">2.2.3</h4> |
| |
| |
| <p>Date of release: 2003-07-19</p> |
| |
| <p>Bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_203">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Added the <code class="inline-code">is_date</code> built-in.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Various <code class="inline-code">is_xxx</code> built-ins were |
| returning <code class="inline-code">false</code> when applied to undefined |
| expressions. Now they correctly fail on them.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_204">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: The JSP taglib support can now read JSP 1.2 |
| compliant TLD XML files.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The JSP taglib support now emits more helpful |
| exception messages when the specified TLD XML file is not found |
| (previously it threw a |
| <code class="inline-code">NullPointerException</code>).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The JSP taglib support now initializes a custom |
| tag after its parent and page context is set as some tags expect |
| them to be set when attribute setters are called.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The <code class="inline-code">BeansWrapper</code> could fail to |
| analyze classes under very rare circumstances due to a premature |
| storage optimization.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_2">2.2.2</h4> |
| |
| |
| <p>Date of release: 2003-05-02</p> |
| |
| <p>Bugfix release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_205">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: The <code class="inline-code">_text</code> key of the |
| <code class="inline-code">freemarker.ext.xml.NodeListModel</code> was not |
| returning the text of the element when used with W3C DOM |
| trees.</p> |
| </li> |
| |
| <li> |
| <p>The classes are now built against JDK 1.2.2 classes, |
| ensuring the binary compatibility of FreeMarker distribution |
| with JDK 1.2.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2_1">2.2.1</h4> |
| |
| |
| <p>Date of release: 2003-04-11</p> |
| |
| <p>This version introduces important new features, such as the |
| native FTL date/time type, and the auto-include and auto-import |
| settings.</p> |
| |
| <p>The date/time support is experimental, but we hope it will not |
| substantially change. We would like to label it as final ASAP, so we |
| urge everybody to send feedback on this topic to the mailing |
| lists.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_206">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New scalar type: date. For more information read: <a href="#dgui_datamodel_scalar">Template Author's Guide/Values, Types/The types/Scalars</a>, <a href="#dgui_datamodel_scalar">Template Author's Guide/Values, Types/The types/Scalars</a>, <a href="#dgui_template_valueinserion_universal_date">interpolation</a>, |
| <a href="#ref_builtin_string_for_date">?string built-in for |
| dates</a></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_207">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>New <code class="inline-code">TemplateModel</code> subinterface: |
| <code class="inline-code">TemplateDateModel</code>. For more information read |
| <a href="#pgui_datamodel_scalar">Programmer's Guide/The Data Model/Scalars</a></p> |
| </li> |
| |
| <li> |
| <p>auto-include and auto-import: With these new configuration |
| level settings, you can include and import commonly used |
| templates (usually collection of macro definitions) at the top |
| of all templates, without actually typing <code class="inline-code"><#include |
| <em class="code-color">...</em>></code> or |
| <code class="inline-code"><#import |
| <em class="code-color">...</em>></code> into the templates |
| again and again. For more information please read the Java API |
| documentation of <code class="inline-code">Configuration</code></p> |
| </li> |
| |
| <li> |
| <p>New template method: |
| <code class="inline-code">createProcessingEnvironment</code>. This method |
| makes it possible for you to do some special initialization on |
| the <a href="#gloss.environment"><code>Environment</code></a> |
| before template processing, or to read the environment after |
| template processing. For more information please read the Java |
| API documentation.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">freemarker.ext.beans</code> |
| package: <code class="inline-code">BeanModel</code>, |
| <code class="inline-code">MapModel</code>, and |
| <code class="inline-code">ResourceModel</code> now implement |
| <code class="inline-code">TemplateHashModelEx</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: |
| <code class="inline-code">Configurable.setSettings(Properties)</code> didn't |
| removed redundant spaces/tabs at the end of property |
| values.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_2">2.2</h4> |
| |
| |
| <p>Date of release: 2003-03-27</p> |
| |
| <p>This release introduces some really important new features. |
| Unfortunately, evolution was painful again; we have a few non-backward |
| compatible changes (see below). Also, for those of you awaiting |
| desired native date/time type, sorry, it is still not here (because of |
| some internal chaos in the team... stand by, it's coming).</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_208">Non backward-compatible changes!</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Macros are now plain variables. This means that if you are |
| unlucky and you have both a macro and another variable with the |
| same name, now the variable will overwrite the macro, so your |
| old template will malfunction. If you have a collection of |
| common macros, you should use the new <a href="#dgui_misc_namespace">namespace feature</a> to |
| prevent accidental clashes with the variables used in the |
| templates.</p> |
| </li> |
| |
| <li> |
| <p>With the introduction of the new <a href="#dgui_misc_namespace">namespace support</a>, |
| <code class="inline-code">global</code> and <code class="inline-code">assign</code> |
| directives are no longer synonyms. <code class="inline-code">assign</code> |
| creates a variable in the current <code class="inline-code">namespace</code>, |
| while <code class="inline-code">global</code> creates variable that is visible |
| from all namespaces (as if the variable would be in the |
| data-model). Thus, the variable created with |
| <code class="inline-code">assign</code> is more specific, and hides the |
| variable of the same name created with |
| <code class="inline-code">global</code>. As a result, if you use both |
| <code class="inline-code">global</code> and <code class="inline-code">assign</code> mixed |
| for the same variable in your templates, now they will |
| malfunction. The solution is to search-and-replace all |
| <code class="inline-code">global</code>s in your old templates with |
| <code class="inline-code">assign</code>.</p> |
| </li> |
| |
| <li> |
| <p>The reserved hash <code class="inline-code">root</code> no longer exists |
| as a predefined variable (we no longer have reserved variables). |
| Use <a href="#dgui_template_exp_var_special">special |
| variable expressions</a> to achieve similar effects. However, |
| we have no equivalent replacement for <code class="inline-code">root</code> |
| because of the changes in the variable scopes caused by the |
| introduction of namespaces. You may should use |
| <code class="inline-code">.globals</code> or |
| <code class="inline-code">.namespace</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> no longer exposes |
| native Java arrays, booleans, numbers, enumerations, iterators, |
| and resource bundles as <code class="inline-code">TemplateScalarModel</code>. |
| This way, number objects wrapped through |
| <code class="inline-code">BeansWrapper</code> are subject to FreeMarker's |
| number formatting machinery. Also, booleans can be formatted |
| using the <code class="inline-code">?string</code> built-in.</p> |
| </li> |
| |
| <li> |
| <p>The signature of |
| <code class="inline-code">Configuration.setServletContextForTemplateLoading</code> |
| has been changed: the first parameter is now |
| <code class="inline-code">Object</code> instead of |
| <code class="inline-code">javax.servlet.ServletContext</code>. Thus, you have |
| to recompile your classes that call this method. The change was |
| required to prevent class-loading failure when |
| <code class="inline-code">javax.servlet</code> classes are not available and |
| you would not call this method.</p> |
| </li> |
| |
| <li> |
| <p>This release introduces a <a href="#dgui_misc_whitespace">parse-time white-space |
| remover</a> that strips some of the typical superfluous |
| white-space around FreeMarker tags and comments. <em>This |
| feature is on by default!</em> Most probably this will not |
| cause problems if you generate white-space neutral output like |
| HTML. But if it does cause undesirable reformatting in output |
| you generate, you can disable it with |
| <code class="inline-code">config.setWhitespaceStripping(false)</code>. Also, |
| you can enable/disable it on a per-template basis with the new |
| <a href="#ref.directive.ftl"><code>ftl</code></a> |
| directive.</p> |
| </li> |
| |
| <li> |
| <p>Some new directives were introduced: |
| <code class="inline-code">nested</code>, <code class="inline-code">import</code>, |
| <code class="inline-code">escape</code>, <code class="inline-code">noescape</code>, |
| <code class="inline-code">t</code>, <code class="inline-code">rt</code>, |
| <code class="inline-code">lt</code>. This means that if you are unlucky and |
| the text of your template contains something like |
| <code class="inline-code"><nested></code>, then that will be |
| misinterpreted as a directive. To prevent this kind of problem |
| in the future, we recommend everybody to switch from the old |
| syntax to the new syntax (``strict syntax''). The strict syntax |
| will be the the default syntax starting from some of the later |
| releases anyway. We plan to release a conversion tool for |
| converting old templates. For more information please read: |
| <a href="#ref_depr_oldsyntax">Reference/Deprecated FTL constructs/Old FTL syntax</a></p> |
| </li> |
| |
| <li> |
| <p>The data-model created by the |
| <code class="inline-code">FreemarkerServlet</code> now uses automatic scope |
| discovery, so writing |
| <code class="inline-code">Application.<em class="code-color">attrName</em></code>, |
| <code class="inline-code">Session.<em class="code-color">attrName</em></code>, |
| <code class="inline-code">Request.<em class="code-color">attrName</em></code> |
| is no longer mandatory; it's enough to write |
| <code class="inline-code"><em class="code-color">attrName</em></code> (for more |
| information <a href="#topic.servlet.scopeAttr">read |
| this</a>). This may break an old template if that rely on the |
| non-existence of certain top-level variables.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FreemarkerServlet</code> now uses the encoding |
| of the template file for the output, unless you specify the |
| encoding in the <code class="inline-code">ContentType</code> init-param, such |
| as <code class="inline-code">text/html; charset=UTF-8</code>.</p> |
| </li> |
| |
| <li> |
| <p>The format of template paths is now more restricted than |
| before. The path must not use <code class="inline-code">/</code>, |
| <code class="inline-code">./</code> and <code class="inline-code">../</code> and |
| <code class="inline-code">://</code> with other meaning as they have in URL |
| paths (or in UN*X paths). The characters <code class="inline-code">*</code> |
| and <code class="inline-code">?</code> are reserved. Also, the template loader |
| must not want paths starting with <code class="inline-code">/</code>. For more |
| information please read: <a href="#pgui_config_templateloading">Programmer's Guide/The Configuration/Template loading</a></p> |
| </li> |
| |
| <li> |
| <p>Till now |
| <code class="inline-code">TemplateTransformModel.getWriter</code> has received |
| null as parameter map if the transform was called without |
| parameters. From now, it will receive an empty Map instead. Note |
| that the previous API documentation didn't state that it always |
| receives null if there are no parameters, so hopelessly only |
| very few classes exploit this design mistake.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_209">Changes in FTL (FreeMarker Template Language)</h5> |
| |
| |
| <ul> |
| <li> |
| <p>User-defined directives: Transform and macro call syntax |
| has been unified; they can be called in the same way, as |
| user-defined directives. This also means that macros support |
| named parameters and nested content (like the -- now deprecated |
| -- <code class="inline-code">transform</code> directive did). For example, if |
| you have a macro called <code class="inline-code">sect</code>, you may call it |
| via <code class="inline-code"><@sect title="Blah" style="modern">Blah |
| blah...</@sect></code>. For more information read: |
| <a href="#dgui_misc_userdefdir">Template Author's Guide/Miscellaneous/Defining your own directives</a></p> |
| </li> |
| |
| <li> |
| <p>Macros are now plain variables. This significantly |
| simplifies FreeMarker semantics, while providing more |
| flexibility; for example you can pass macros as parameters to |
| other macros and transforms. As for the problem of clashing |
| commonly-used-macro and variable names, we provide a more |
| powerful solution: namespaces.</p> |
| </li> |
| |
| <li> |
| <p>Namespaces: Names-spaces are invaluable if you want to |
| assemble collections (``libraries'') of macros and transforms |
| (and other variables), and then use them in any template without |
| worrying about accidental name clashes with the application |
| specific and temporary variables, or with the variables of other |
| collections you want to use in the same template. This is |
| extremely important if FreeMarker users want to share their |
| macro/transform collections. For more information read: <a href="#dgui_misc_namespace">Template Author's Guide/Miscellaneous/Namespaces</a></p> |
| </li> |
| |
| <li> |
| <p>With the introduction of namespaces our variable related |
| terminology changed. As a result, <code class="inline-code">assign</code> is |
| no longer synonymous with <code class="inline-code">global</code>. The |
| <code class="inline-code">assign</code> directive has been undeprecated, and |
| should be used instead of <code class="inline-code">global</code> almost |
| everywhere. In the new approach <code class="inline-code">assign</code> |
| creates variables in the current namespace, while |
| <code class="inline-code">global</code> creates a variable that is visible |
| from all namespaces (as if the variable were in the root of the |
| data-model). A variable created with <code class="inline-code">assign</code> |
| in the current namespace hides the variable of the same name |
| that was created with <code class="inline-code">global</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ftl</code> directive: With this directive you |
| can give information about the template for FreeMarker, like the |
| encoding (charset) of the template, the used FTL syntax variant, |
| etc. Also, this directive helps you to write templates that are |
| less dependent on FreeMarker configuration settings, also it |
| helps third-party tools to identify and correctly parse |
| FreeMarker templates. For more information see: <a href="#ref.directive.ftl"><code>ftl</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>White-space stripping: FreeMarker now automatically |
| removes some of the typical superfluous white-spaces around |
| FreeMarker tags and comments, like the indentation spaces |
| before- and line-break after <code class="inline-code"><#if ...></code> |
| tags. For more information read: <a href="#dgui_misc_whitespace_stripping">Template Author's Guide/Miscellaneous/White-space handling/White-space stripping</a></p> |
| </li> |
| |
| <li> |
| <p>New directive to apply a common ("escaping") expression to |
| all interpolations in a block: <a href="#ref.directive.escape"><code>escape</code></a>. |
| The name comes from the common usage of this directive for |
| automatic HTML-escaping of interpolations.</p> |
| </li> |
| |
| <li> |
| <p>The new and preferred way of number formatting with |
| <code class="inline-code">string</code> built-in is |
| <code class="inline-code">foo?string(format)</code>, instead of the less |
| natural <code class="inline-code">foo?string[format]</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">string</code> built-in works for boolean |
| values. For example: <code class="inline-code">${spamFilter?string("enabled", |
| "disabled")}</code>. For more information <a href="#ref_builtin_string_for_boolean">read the |
| reference</a>.</p> |
| </li> |
| |
| <li> |
| <p>The default strings for outputting boolean value using the |
| <code class="inline-code">string</code> built-in can be set using the |
| <code class="inline-code">boolean_format</code> setting.</p> |
| </li> |
| |
| <li> |
| <p>Comments can be placed inside FTL tags and interpolations. |
| For example: <code class="inline-code"><#assign <#-- a comment --> x = |
| 3></code></p> |
| </li> |
| |
| <li> |
| <p>All letters and numbers are enabled in variable names, |
| also <code class="inline-code">$</code> is allowed (as in Java programming |
| language). Thus you can use accents, Arabic letters, Chinese |
| letters, etc.</p> |
| </li> |
| |
| <li> |
| <p>String literals can be quoted with apostrophe-quote. |
| <code class="inline-code">"foo"</code> and <code class="inline-code">'foo'</code> are |
| equivalent.</p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_builtins_string">string |
| built-ins</a>: <code class="inline-code">index_of</code>, |
| <code class="inline-code">last_index_of</code>, |
| <code class="inline-code">starts_with</code>, <code class="inline-code">ends_with</code>, |
| <code class="inline-code">replace</code>, <code class="inline-code">split</code>, |
| <code class="inline-code">chop_linebreak</code>, |
| <code class="inline-code">uncap_first</code>.</p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_builtins_sequence">sequence |
| built-ins</a>: <code class="inline-code">sort</code>, |
| <code class="inline-code">sort_by</code>.</p> |
| </li> |
| |
| <li> |
| <p>New built-ins for experts to check the type of a variable. |
| See: <a href="#ref_builtin_isType"><code>is_<em>...</em></code> |
| built-ins</a></p> |
| </li> |
| |
| <li> |
| <p>New built-in for experts to create a variable of certain |
| Java <code class="inline-code">TemplateModel</code> implementation. See: <a href="#ref_builtin_new"><code>new</code> |
| built-in</a></p> |
| </li> |
| |
| <li> |
| <p>New built-in, <a href="#ref_builtin_namespace"><code>namespace</code></a>, |
| to get the namespace of a macro.</p> |
| </li> |
| |
| <li> |
| <p>New expression type: special variable expression. To |
| prevent backward compatibility problems when we introduce new |
| predefined variables, from now <a href="#dgui_template_exp_var_special">special variable |
| expressions</a> are used to access them.</p> |
| </li> |
| |
| <li> |
| <p>New directives: <code class="inline-code">t</code>, |
| <code class="inline-code">rt</code> and <code class="inline-code">lt</code> directives allow |
| you to do explicit white-space removal in extreme FTL |
| applications. For more information read <a href="#ref.directive.t">the reference</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">assign</code>, <code class="inline-code">local</code> and |
| <code class="inline-code">global</code> now can capture the output generated |
| be the nested template fragment into the variable. This |
| deprecates <code class="inline-code">capture_output</code> transform. More |
| information: <a href="#ref.directive.assign">assign |
| directive reference</a></p> |
| </li> |
| |
| <li> |
| <p>Bulk assignments (as <code class="inline-code"><#assign x=1, y=2, |
| z=3></code>) no longer need colon to separate the |
| assignments (as <code class="inline-code"><#assign x=1 y=2 z=3></code>), |
| although it is still allowed to preserve backward |
| compatibility.</p> |
| </li> |
| |
| <li> |
| <p>Path that contains <code class="inline-code">//:</code> is considered as |
| absolute path.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">include</code> and |
| <code class="inline-code">transform</code> directives no longer need a |
| semicolon to separate the template or transform name from the |
| parameter list, although it is still allowed to preserve |
| backward compatibility.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">#</code>-less tag syntax is deprecated (but |
| still working). That is, you should write |
| <code class="inline-code"><#<em class="code-color">directive |
| ...</em>></code> instead of |
| <code class="inline-code"><<em class="code-color">directive |
| ...</em>></code>, and |
| <code class="inline-code"></#<em class="code-color">directive |
| ...</em>></code> instead of |
| <code class="inline-code"></<em class="code-color">directive |
| ...</em>></code>. For more info read: <a href="#ref_depr_oldsyntax">Reference/Deprecated FTL constructs/Old FTL syntax</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">foreach</code> is depreciated (but still |
| working). Use <a href="#ref.directive.list"><code>list</code></a> |
| instead.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Undefined variables in hash and sequence |
| constructors (as <code class="inline-code">[a, b, c]</code>) didn't caused |
| errors.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: String concatenation had performance problem if |
| there was multiple concatenations chained, as: |
| <code class="inline-code">"a"+x+"a"+x+"a"+x+"a"+x+"a"+x</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_210">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Arbitrary JSP custom tags can be used as FreeMarker |
| transforms in <code class="inline-code">FreemarkerServlet</code>-driven |
| templates. More information: <a href="#pgui_misc_servlet">Programmer's Guide/Miscellaneous/Using FreeMarker with servlets</a></p> |
| </li> |
| |
| <li> |
| <p>Various improvements for |
| <code class="inline-code">BeansWrapper</code>:</p> |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">BeansWrapper</code> no longer exposes |
| arbitrary objects as |
| <code class="inline-code">TemplateScalarModel</code>s, only |
| <code class="inline-code">java.lang.String</code> and |
| <code class="inline-code">Character</code> objects. This way, number |
| objects wrapped through <code class="inline-code">BeansWrapper</code> are |
| subject to FreeMarker's number formatting machinery. As a |
| side effect, non-string and non-number objects that were |
| previously accepted in equality and inequality operations |
| (because they had a string representation) will now cause |
| the engine to throw exception on comparison attempt.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">java.lang.Character</code> objects are |
| exposed as scalars through |
| <code class="inline-code">BeansWrapper</code>.</p> |
| </li> |
| |
| <li> |
| <p>Experimental feature: With the |
| <code class="inline-code">setSimpleMapWrapper</code> method of |
| <code class="inline-code">BeansWrapper</code> you can configure it to wrap |
| <code class="inline-code">java.util.Map</code>-s as |
| <code class="inline-code">TemplateHashModelEx</code>-s, and do not expose |
| the methods of the object.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TransformControl</code> interface (was |
| experimental earlier): If the <code class="inline-code">Writer</code> returned |
| by <code class="inline-code">TemplateTransformModel.getWriter</code> |
| implements this interface, it can instruct the engine to skip or |
| to repeat evaluation of the nested content, and gets notified |
| about exceptions that are thrown during the nested content |
| evaluation. Note that the <code class="inline-code">onStart</code> and |
| <code class="inline-code">afterBody</code> methods now are allowed to throw |
| <code class="inline-code">IOException</code>. For more information please read |
| the API documentation.</p> |
| </li> |
| |
| <li> |
| <p>Localized lookup can be disabled with the new |
| <code class="inline-code">Configuration</code> methods: |
| <code class="inline-code">set/getLocalizedLookup</code>, |
| <code class="inline-code">clearTemplateCache</code></p> |
| </li> |
| |
| <li> |
| <p>The new interface |
| <code class="inline-code">freemarker.cache.CacheStorage</code> allows users to |
| plug custom template caching strategies with the |
| <code class="inline-code">cache_storage</code> setting. The core package now |
| ships with two implementations: |
| <code class="inline-code">SoftCacheStorage</code> and |
| <code class="inline-code">StrongCacheStorage</code>. For more information |
| read: <a href="#pgui_config_templateloading">Programmer's Guide/The Configuration/Template loading</a></p> |
| </li> |
| |
| <li> |
| <p>You can set settings with string name and string value |
| with the new <code class="inline-code">setSetting(String key, String |
| value)</code> method of <code class="inline-code">Configurable</code> |
| super-classes (as <code class="inline-code">Configuration</code>). Also you |
| can load settings from <code class="inline-code">.properties</code> file with |
| the <code class="inline-code">setSettings</code> method.</p> |
| </li> |
| |
| <li> |
| <p>Other new <code class="inline-code">Configuration</code> methods: |
| <code class="inline-code">clearTemplateCache</code>, |
| <code class="inline-code">clearSharedVariables</code>, |
| <code class="inline-code">getTemplateLoader</code>, and |
| <code class="inline-code">clone</code>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">TemplateTransformModel</code> |
| interface: <code class="inline-code">getWriter</code> can throw |
| <code class="inline-code">IOException</code>, and can return |
| <code class="inline-code">null</code> if the transform does not support body |
| content.</p> |
| </li> |
| |
| <li> |
| <p>Till now |
| <code class="inline-code">TemplateTransformModel.getWriter</code> has received |
| null as parameter map if the transform was called without |
| parameters. From now, it will receive an empty Map instead. Note |
| that the previous API documentation didn't state that it always |
| receives null if there are no parameters, so hopelessly only |
| very few classes exploit this design mistake.</p> |
| </li> |
| |
| <li> |
| <p>Various improvements for |
| <code class="inline-code">FreemarkerServlet</code>:</p> |
| |
| <ul> |
| <li> |
| <p>The data-model now uses automatic scope discovery, so |
| writing |
| <code class="inline-code">Application.<em class="code-color">attrName</em></code>, |
| <code class="inline-code">Session.<em class="code-color">attrName</em></code>, |
| <code class="inline-code">Request.<em class="code-color">attrName</em></code> |
| is no longer mandatory; it's enough to write |
| <code class="inline-code"><em class="code-color">attrName</em></code>. For |
| more information <a href="#topic.servlet.scopeAttr">read this</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FreemarkerServlet</code> now uses the |
| encoding of the template file for the output, unless you |
| specify the encoding in the <code class="inline-code">ContentType</code> |
| init-param, such as <code class="inline-code">text/html; |
| charset=UTF-8</code>.</p> |
| </li> |
| |
| <li> |
| <p>All <code class="inline-code">Configuration</code> level settings |
| can by set with Servlet init-params |
| (<code class="inline-code">template_exception_handler</code>, |
| <code class="inline-code">locale</code>, <code class="inline-code">number_format</code>, |
| etc.).</p> |
| </li> |
| |
| <li> |
| <p>The object wrapper the servlet internally uses is now |
| set as the default object wrapper for its |
| <code class="inline-code">Configuration</code> instance.</p> |
| </li> |
| |
| <li> |
| <p>It no longer forces session creation for requests that |
| don't belong to an existing session, improving |
| scalability.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>JDOM independent XML-wrapping: |
| <code class="inline-code">freemarker.ext.xml.NodeListModel</code> is a |
| re-implementation of |
| <code class="inline-code">freemarker.ext.jdom.NodeListModel</code> that does |
| not rely on JDOM; you don't need JDOM .jar anymore. The new |
| <code class="inline-code">NodeListModel</code> automatically uses W3C DOM, |
| dom4j, or JDOM, depending on which library is available (that |
| is, depending on what object do you pass to its |
| constructor).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">WebappTemplateLoader</code>: Template |
| updating didn't worked correctly with Tomcat due the caching of |
| resources. Now <code class="inline-code">WebappTemplateLoader</code> tries to |
| access the resources directly as <code class="inline-code">File</code>, if it |
| is possible, thus bypasses the caching.</p> |
| </li> |
| |
| <li> |
| <p>Various bug-fixes for |
| <code class="inline-code">FreemarkerServlet</code>:</p> |
| |
| <ul> |
| <li> |
| <p>The servlet now loads the correct template if it was |
| called through |
| <code class="inline-code">RequestDispatcher.include</code>.</p> |
| </li> |
| |
| <li> |
| <p>The caching of <code class="inline-code">HttpServletRequest</code> |
| objects is now compliant with the servlet |
| specification.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateException</code>s was suppressed |
| in certain situations resulting in half-rendered pages |
| without error message.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Bugfix: FreeMarker didn't work if the |
| <code class="inline-code">javax.servlet</code> classes was not available, |
| because <code class="inline-code">Configuration</code> explicitly referred to |
| <code class="inline-code">javax.servlet.ServletContext</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: classes may were not found if they was available |
| only in the <code class="inline-code">WEB-INF</code>, and FreeMarker tried to |
| load the class dynamically.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: the <code class="inline-code">Template</code> constructor (and |
| thus <code class="inline-code">Configuration.getTemplate</code>) sometimes |
| threw <code class="inline-code">TokenMgrError</code> (a non-checked exception) |
| instead of <code class="inline-code">ParseException</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_211">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The Web application related examples has been |
| replaced.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_212">The history of the releases before the final version</h5> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_213">Differences between the final and RC2 releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>You can load settings from |
| <code class="inline-code">.properties</code> file with the |
| <code class="inline-code">setSettings</code> method of |
| <code class="inline-code">Configuration</code> and other |
| <code class="inline-code">Configurable</code> subclasses.</p> |
| </li> |
| |
| <li> |
| <p>New string built-in: |
| <code class="inline-code">uncap_first</code></p> |
| </li> |
| |
| <li> |
| <p>Bugfix: When exposing an XML document to a template and |
| accessing it with XPath using Jaxen a |
| <code class="inline-code">ClassCastException</code> has occurred.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: The template cache has loaded templates with bad |
| <code class="inline-code">Configuration</code> instance in certain |
| situations if you use not the static default |
| <code class="inline-code">Configuration</code> instance.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_214">Differences between the RC2 and RC1 releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>Non backward compatible change!: |
| <code class="inline-code">FreemarkerServlet</code> now uses the encoding of |
| the template file for the output, unless you specify the |
| encoding in the <code class="inline-code">ContentType</code> init-param, |
| such as <code class="inline-code">text/html; charset=UTF-8</code>.</p> |
| </li> |
| |
| <li> |
| <p>Non backward compatible change compared to RC1!: The |
| <code class="inline-code">capture_output</code> transform creates variable |
| in the current namespace (as <code class="inline-code">assign</code> |
| directive) with the <code class="inline-code">var</code> parameter, not a |
| global variable.</p> |
| </li> |
| |
| <li> |
| <p>The new and preferred way of number formatting with |
| <code class="inline-code">string</code> built-in is |
| <code class="inline-code">foo?string(format)</code>, instead of the less |
| natural <code class="inline-code">foo?string[format]</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">string</code> built-in works for boolean |
| values. For example: <code class="inline-code">${spamFilter?string("enabled", |
| "disabled")}</code>. For more information <a href="#ref_builtin_string_for_boolean">read the |
| reference</a>.</p> |
| </li> |
| |
| <li> |
| <p>The default strings for outputting boolean value using |
| the <code class="inline-code">string</code> built-in can be set using the |
| <code class="inline-code">boolean_format</code> setting.</p> |
| </li> |
| |
| <li> |
| <p>String literals can be quoted with apostrophe-quote. |
| <code class="inline-code">"foo"</code> and <code class="inline-code">'foo'</code> are |
| equivalent.</p> |
| </li> |
| |
| <li> |
| <p>The new interface |
| <code class="inline-code">freemarker.cache.CacheStorage</code> allows users |
| to plug custom template caching strategies with the |
| <code class="inline-code">cache_storage</code> setting. The core package now |
| ships with two implementations: |
| <code class="inline-code">SoftCacheStorage</code> and |
| <code class="inline-code">StrongCacheStorage</code>. For more information |
| read: <a href="#pgui_config_templateloading">Programmer's Guide/The Configuration/Template loading</a></p> |
| </li> |
| |
| <li> |
| <p>You can set settings with string name and string value |
| with the new <code class="inline-code">setSetting(String key, String |
| value)</code> method of <code class="inline-code">Configurable</code> |
| super-classes (as <code class="inline-code">Configuration</code>).</p> |
| </li> |
| |
| <li> |
| <p>Other new <code class="inline-code">Configuration</code> methods: |
| <code class="inline-code">getTemplateLoader</code>, |
| <code class="inline-code">clone</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">assign</code>, <code class="inline-code">local</code> and |
| <code class="inline-code">global</code> now can capture the output generated |
| be the nested template fragment into the variable. This |
| deprecates <code class="inline-code">capture_output</code> transform. More |
| information: <a href="#ref.directive.assign">assign |
| directive reference</a></p> |
| </li> |
| |
| <li> |
| <p>Other new <code class="inline-code">Configuration</code> methods: |
| <code class="inline-code">getTemplateLoader</code>, |
| <code class="inline-code">clone</code>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">TemplateTransformModel</code> |
| interface: <code class="inline-code">getWriter</code> can throw |
| <code class="inline-code">IOException</code>, and can return |
| <code class="inline-code">null</code> if the transform does not support body |
| content.</p> |
| </li> |
| |
| <li> |
| <p>Till now |
| <code class="inline-code">TemplateTransformModel.getWriter</code> has |
| received null as parameter map if the transform was called |
| without parameters. From now, it will receive an empty Map |
| instead. Note that the previous API documentation didn't state |
| that it always receives null if there are no parameters, so |
| hopelessly only very few classes exploit this design |
| mistake.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">TemplateControl</code> interface: |
| <code class="inline-code">onStart</code> and <code class="inline-code">afterBody</code> |
| methods are now allowed to throw |
| <code class="inline-code">IOException</code>.</p> |
| </li> |
| |
| <li> |
| <p>Path that contains <code class="inline-code">//:</code> is considered |
| as absolute path.</p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_builtins_string">string |
| built-ins</a>: <code class="inline-code">index_of</code>, |
| <code class="inline-code">last_index_of</code>, |
| <code class="inline-code">starts_with</code>, <code class="inline-code">ends_with</code>, |
| <code class="inline-code">replace</code>, <code class="inline-code">split</code>, |
| <code class="inline-code">chop_linebreak</code>.</p> |
| </li> |
| |
| <li> |
| <p>New <a href="#ref_builtins_sequence">sequence |
| built-ins</a>: <code class="inline-code">sort</code>, |
| <code class="inline-code">sort_by</code>.</p> |
| </li> |
| |
| <li> |
| <p>All <code class="inline-code">Configuration</code> level settings can |
| by set with Servlet init-params |
| (<code class="inline-code">template_exception_handler</code>, |
| <code class="inline-code">locale</code>, <code class="inline-code">number_format</code>, |
| etc.).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: classes may were not found if they was available |
| only in the <code class="inline-code">WEB-INF</code>, and FreeMarker tried |
| to load the class dynamically.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">setLocalizedLookup(false)</code> of |
| <code class="inline-code">Configuration</code> was overridden when you have |
| called <code class="inline-code">setTemplateLoader</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: String concatenation had performance problem if |
| there was multiple concatenations chained, as: |
| <code class="inline-code">"a"+x+"a"+x+"a"+x+"a"+x+"a"+x</code>.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: white-space stripping was not worked with tags |
| spanning over multiple lines.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Removing several dependencies on JDK 1.3, so |
| FreeMarker can be build for JDK 1.2.2.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_215">Differences between the Preview 2 and RC1 releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">ftl</code> is now stricter, and does not |
| allow custom parameters. To associate custom attributes to |
| templates, we may add a new directive later, if there is a |
| demand for it.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">escape</code> directive does not affect |
| numerical interpolations |
| (<code class="inline-code">#{<em class="code-color">...</em>}</code>) |
| anymore, as it has caused errors with string escapes as |
| <code class="inline-code">?html</code>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">normalizeName</code> method of |
| <code class="inline-code">freemarker.cache.TemplateLoader</code> has been |
| removed, because it has caused too many complications. |
| Instead, normalization happens on a single point in the |
| <code class="inline-code">TempateCache</code>. In consequence, FreeMarker is |
| now stricter about the format of template paths, as things |
| like <code class="inline-code">/../</code> are interpreted by the |
| core.</p> |
| </li> |
| |
| <li> |
| <p>Experimental feature: With the |
| <code class="inline-code">setSimpleMapWrapper</code> method of |
| <code class="inline-code">BeansWrapper</code> you can configure it to wrap |
| <code class="inline-code">java.util.Map</code>-s as |
| <code class="inline-code">TemplateHashModelEx</code>-s, and do not expose |
| the methods of the object.</p> |
| </li> |
| |
| <li> |
| <p>New <code class="inline-code">Configuration</code> methods: |
| <code class="inline-code">set/getLocalizedLookup</code>, |
| <code class="inline-code">clearTemplateCache</code>, |
| <code class="inline-code">clearSharedVariables</code>.</p> |
| </li> |
| |
| <li> |
| <p>More cleanups in the <code class="inline-code">Environment</code> |
| API.</p> |
| </li> |
| |
| <li> |
| <p>Better JSP standard compliance: JSP page-scope variables |
| are the global variables that were created in the template |
| (not the variables of the data-model).</p> |
| </li> |
| |
| <li> |
| <p>JDOM independent XML-wrapping: |
| <code class="inline-code">freemarker.ext.xml.NodeListModel</code> is a |
| re-implementation of |
| <code class="inline-code">freemarker.ext.jdom.NodeListModel</code> that does |
| not rely on JDOM; you don't need JDOM .jar anymore. The new |
| <code class="inline-code">NodeListModel</code> automatically uses W3C DOM, |
| dom4j, or JDOM, depending on which library is available (that |
| is, depending on what object do you pass to its |
| constructor).</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">WebappTemplateLoader</code>: |
| Template updating didn't worked correctly with Tomcat due the |
| caching of resources. Now |
| <code class="inline-code">WebappTemplateLoader</code> tries to access the |
| resources directly as <code class="inline-code">File</code>, if it is |
| possible, thus bypasses the caching.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Templates loaded with |
| <code class="inline-code">MultiTemplateLoader</code> subclasses was removed |
| from the template cache after the template update delay has |
| elapsed (5 seconds by default) even if the template file was |
| unchanged. This can cause lot of extra load for a high-traffic |
| server if you have many templates or if the template update |
| delay was set to 0 second.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Undefined variables in hash and sequence |
| constructors (as <code class="inline-code">[a, b, c]</code>) didn't caused |
| errors.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h6 class="content-header header-section3" id="autoid_216">Differences between the Preview 1 and Preview 2 |
| releases</h6> |
| |
| |
| <ul> |
| <li> |
| <p>All 16-bit Unicode letters and numbers are allowed in |
| identifiers, as well as the <code class="inline-code">$</code> character (as |
| in Java programming language). Thus you can use accented |
| letters, Arabic letters, Chinese letters, etc. as identifiers |
| in templates</p> |
| </li> |
| |
| <li> |
| <p>Macros now can create loop variables for the nested |
| content. For more information <a href="#dgui_misc_userdefdir_loopvar">read |
| this</a>.</p> |
| </li> |
| |
| <li> |
| <p>New directives: <code class="inline-code">t</code>, |
| <code class="inline-code">rt</code> and <code class="inline-code">lt</code> directives |
| allow you to do explicit white-space removal in extreme FTL |
| applications. For more information read <a href="#ref.directive.t">the reference</a>.</p> |
| </li> |
| |
| <li> |
| <p>The syntax of assignment-with-namespace has changed from |
| <code class="inline-code"><#assign foo=123 namespace=myLib></code>) to |
| <code class="inline-code"><#assign foo=123 in myLib></code>, since the |
| previous syntax was confusing because its similarity to a |
| bulk-assignment.</p> |
| </li> |
| |
| <li> |
| <p>Bulk assignments (as <code class="inline-code"><#assign x=1, y=2, |
| z=3></code>) no longer need colon to separate the |
| assignments (as <code class="inline-code"><#assign x=1 y=2 |
| z=3></code>), although it is still allowed to preserve |
| backward compatibility.</p> |
| </li> |
| |
| <li> |
| <p>Positional parameter passing is supported for macro |
| calls as shorthand form of normal named parameter passing. For |
| more details read <a href="#ref_directive_userDefined_positionalParam">read the |
| reference</a>.</p> |
| </li> |
| |
| <li> |
| <p>New built-in, <code class="inline-code">namespace</code>, to get the |
| namespace of the currently executing macro.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TransformControl</code> interface (was |
| experimental earlier): If the <code class="inline-code">Writer</code> |
| returned by |
| <code class="inline-code">TemplateTransformModel.getWriter</code> implements |
| this interface, it can instruct the engine to skip or to |
| repeat evaluation of the nested content, and gets notified |
| about exceptions that are thrown during the nested content |
| evaluation. For more information please read the API |
| documentation.</p> |
| </li> |
| |
| <li> |
| <p>Jython wrapper can now wrap arbitrary Java objects, not |
| only <code class="inline-code">PyObject</code>-s. If an object is passed to |
| the wrapper that is neither a |
| <code class="inline-code">TemplateModel</code>, nor a |
| <code class="inline-code">PyObject</code>, it is first coerced into a |
| <code class="inline-code">PyObject</code> using Jython's own wrapping |
| machinery, and then wrapped into a |
| <code class="inline-code">TemplateModel</code> as any other |
| <code class="inline-code">PyObject</code>.</p> |
| </li> |
| |
| <li> |
| <p>Some cleanups in the <code class="inline-code">Environment</code> |
| API.</p> |
| </li> |
| |
| <li> |
| <p>The Web application related examples has been |
| replaced.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Templates loaded with |
| <code class="inline-code">URLTemplateLoader</code> subclasses was removed |
| from the template cache after the template update delay has |
| elapsed (5 seconds by default) even if the template file was |
| unchanged. This can cause lot of extra load for a high-traffic |
| server if you have many templates or if the template update |
| delay was set to 0 second.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">FreeMarkerServlet</code> has thrown |
| <code class="inline-code">ServletException</code> even if a debug |
| <code class="inline-code">TemplateException</code> handler was in use (so |
| you may got Error 500 page instead of debug |
| information).</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1_5">2.1.5</h4> |
| |
| |
| <p>Date of release: 2003-02-08</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_217">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: Fixed a bug that forced the cache to frequently |
| reload templates accessed through URL and multi template |
| loaders: Templates loaded with |
| <code class="inline-code">URLTemplateLoader</code> subclasses and |
| <code class="inline-code">MultiTemplateLoader</code> was removed from the |
| template cache after the template update delay has elapsed (5 |
| seconds by default) even if the template file was unchanged. |
| This can cause lot of extra load for a high-traffic server if |
| you have many templates or if the template update delay was set |
| to 0 second.)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Many anomalies in the |
| <code class="inline-code">JythonWrapper</code> were resolved, making the |
| integration with Jython much smoother: Jython wrapper can now |
| wrap arbitrary Java objects, not only |
| <code class="inline-code">PyObject</code>-s. If an object is passed to the |
| wrapper that is neither a <code class="inline-code">TemplateModel</code>, nor |
| a <code class="inline-code">PyObject</code>, it is first coerced into a |
| <code class="inline-code">PyObject</code> using Jython's own wrapping |
| machinery, and then wrapped into a |
| <code class="inline-code">TemplateModel</code> as any other |
| <code class="inline-code">PyObject</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1_4">2.1.4</h4> |
| |
| |
| <p>Date of release: 2002-12-26</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_218">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: Log4J is now found when automatically discovering |
| the logging library to use.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: An exception is no longer thrown in the static |
| initializer of the <code class="inline-code">Configuration</code> if the |
| directory specified in the <code class="inline-code">"user.dir"</code> system |
| property is not readable.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1_3">2.1.3</h4> |
| |
| |
| <p>Date of release: 2002-12-09</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_219">Changes on the FTL side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: <code class="inline-code">cap_first</code> built-in did what |
| <code class="inline-code">double</code> built-in does.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_220">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The official extension of FreeMarker template files is |
| <code class="inline-code">ftl</code> from now, not <code class="inline-code">fm</code>. |
| (This is the name of the template language; FTL, for FreeMarker |
| Template Language.) Of course you can use any extensions, since |
| FreeMarker does not deal with the file extension. But we |
| recommend <code class="inline-code">ftl</code> extension as default.</p> |
| </li> |
| |
| <li> |
| <p>Web application examples got tweaked again, as under JDK |
| 1.4 a class in an explicit (named) package can no longer import |
| classes from the default (unnamed) package. Our webapp example |
| was using classes in the default package, they are now moved |
| into named packages.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1_2">2.1.2</h4> |
| |
| |
| <p>Date of release: 2002-11-28</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_221">Changes in FTL (FreeMarker Template Language)</h5> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">FreeMarkerServlet</code> now has a setting for |
| the <code class="inline-code">Content-Type</code> header of the response, |
| defaulting to <code class="inline-code">text/html</code>. Previously it set no |
| content type, which made it not play nicely when integrated with |
| software that expected it (i.e. OpenSymphony SiteMesh).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">FreeMarkerServlet</code> now works correctly |
| when mapped to an URL extension instead of URL path |
| prefix.</p> |
| </li> |
| |
| <li> |
| <p>You can emulate <code class="inline-code">include</code> directive call |
| within Java code by calling |
| <code class="inline-code">Environment.include(<em class="code-color">templateName</em>, |
| <em class="code-color">charset</em>, |
| <em class="code-color">parse</em>)</code>.</p> |
| </li> |
| </ul> |
| |
| <ul> |
| <li> |
| <p>Bugfix: When <code class="inline-code">Template.process()</code> was |
| called from another template processing, it set |
| <code class="inline-code">currentEnvironment</code> to null when it returned, |
| thus crashed the parent template processing.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: the <code class="inline-code">_descendant</code> key in JDOM |
| support incorrectly left the document root element out of the |
| result when applied to a Document node.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: because we incorrectly assumed certain behavior of |
| JDK 1.4 Beans introspector, calls to public interface methods on |
| non-public classes that implement the interface were causing |
| exceptions on JDK 1.4</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_222">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Various minor supplements to the manual.</p> |
| </li> |
| |
| <li> |
| <p>Documentation HTML pages don't try to load the SourceForge |
| logo from the Internet anymore.</p> |
| </li> |
| |
| <li> |
| <p>The default ant target is <code class="inline-code">jar</code>, not |
| <code class="inline-code">dist</code>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1_1">2.1.1</h4> |
| |
| |
| <p>Date of release: 2002-11-04</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_223">Changes in FTL (FreeMarker Template Language)</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Multi-type variables that are both string and number or |
| string and date are now output using their number or date value |
| instead of the string value when used in the |
| <code class="inline-code">${...}</code> interpolation. This practically makes |
| the string part of a string/number or a string/date variables |
| useless.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: operator ``or'' (<code class="inline-code">||</code>) worked |
| wrongly when its left operand was a composite expression (e.g. |
| the second <code class="inline-code">||</code> in <code class="inline-code">false || true || |
| false</code>; this was evaluated to <code class="inline-code">false</code>, |
| but it should be <code class="inline-code">true</code>)</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Less-than sign inside comments confused the FTL |
| parser (e.g. <code class="inline-code"><#-- blah < blah --></code>); |
| it commented out everything after the problematic |
| comment.</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: Comparing two numerical constants (e.g. <code class="inline-code">3 |
| == 3</code>) caused internal error in the FTL parser, and |
| aborted template processing with error.</p> |
| </li> |
| |
| <li> |
| <p>Experimental date/time type support was removed, since it |
| seems that this initial implementation was misguided. FreeMarker |
| 2.2 will certainly support data/time.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_224">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Bugfix: <code class="inline-code">Number</code>s wrapped with |
| <code class="inline-code">BEANS_WRAPPER</code> was displayed with the |
| <code class="inline-code">toString()</code> method of wrapped object. Now they |
| are rendered according to the <code class="inline-code">number_format</code> |
| setting, because multi-type variables that are both string and |
| number are now output using their number value instead of the |
| string value.</p> |
| </li> |
| |
| <li> |
| <p>Experimental date/time type support was removed, since it |
| seems that this initial implementation was misguided. FreeMarker |
| 2.2 will certainly support data/time.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_1">2.1</h4> |
| |
| |
| <p>Date of release: 2002-10-17</p> |
| |
| <p>Templates and the Java API are <em>not</em> fully |
| compatible with 2.0 releases. You will need to revisit existing code |
| and templates, or use 2.1 for new projects only. Sorry for this |
| inconvenience; FreeMarker has undergone some revolutionary changes |
| since the 1.x series. We hope things will soon be sufficiently mature |
| for us to offer (almost) backward-compatible releases. Note that there |
| is a backward-compatibility flag that can be set via |
| <code class="inline-code">Configuration.setClassicCompatible(true)</code> that |
| causes the new FreeMarker to emulate most of FreeMarker 1.x's |
| quirks.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_225">Changes in FTL (FreeMarker Template Language)</h5> |
| |
| |
| <ul> |
| <li> |
| <p>More strict, reveals accidental mistakes in the templates, |
| prevents showing incorrect information when something went |
| wrong:</p> |
| |
| <ul> |
| <li> |
| <p>An attempt to access an undefined variable causes an |
| error and aborts template processing (by default at least; |
| see later). In earlier versions undefined variables were |
| silently treated as empty (zero-length) strings. However, |
| you can handle undefined variables in the template with some |
| new built-ins. For example, |
| <code class="inline-code">${foo?if_exists}</code> is equivalent with the |
| <code class="inline-code">${foo}</code> of earlier versions. Another way |
| of looking at this is that null values no longer exist from |
| the viewpoint of a template designer. Anything referenced |
| must be a defined variable.</p> |
| |
| <p>Note however that the programmer can configure |
| FreeMarker so that it ignores certain errors (say, undefined |
| variables), and continues template processing by skipping |
| the problematic part. This ``loose'' policy should be used |
| only for sites that don't show critical information.</p> |
| </li> |
| |
| <li> |
| <p>New variable type: <a href="#gloss.boolean">boolean</a>. Conditions in |
| <code class="inline-code">if</code>/<code class="inline-code">elseif</code> and operands |
| of logical operators (<code class="inline-code">&&</code>, |
| <code class="inline-code">||</code>, <code class="inline-code">!</code>) must be |
| booleans. Empty strings are no longer treated as a logical |
| false.</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Local and global variables. More info: <a href="#dgui_misc_var">Template Author's Guide/Miscellaneous/Defining variables in the template</a></p> |
| |
| <ul> |
| <li> |
| <p>Local variables for macros. You can create/replace |
| local variables in macro definition bodies with the <a href="#ref.directive.local"><code>local</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>You can create/replace global (non-local) variables |
| with the <a href="#ref.directive.global"><code>global</code> |
| directive</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>The <a href="#ref.directive.include"><code>include</code></a> |
| directive now by default treats the passed filename as being |
| relative to the including template's path. To specify absolute |
| template paths, you now have to prepend them with a |
| slash.</p> |
| </li> |
| |
| <li> |
| <p>The <a href="#ref.directive.include"><code>include</code></a> |
| directive can now use the <em>acquisition |
| algorithm</em> (familiar from the Zope system) to look up |
| the template to include. Basically, if a template is not found |
| where it is looked up first, it is looked up in parent |
| directories. This is however not a default behavior, rather it |
| is triggered by a new syntactic element.</p> |
| </li> |
| |
| <li> |
| <p>Strict syntax mode: Allows you to generate arbitrary SGML |
| (XML) without worrying about clashes with FreeMarker directives. |
| For more information read: <a href="#ref_depr_oldsyntax">Reference/Deprecated FTL constructs/Old FTL syntax</a></p> |
| </li> |
| |
| <li> |
| <p>Terse comments: you can use <code class="inline-code"><#-- |
| <em class="code-color">...</em> --></code> instead of |
| <code class="inline-code"><comment><em class="code-color">...</em></comment></code></p> |
| </li> |
| |
| <li> |
| <p>Directive that you can use to change the locale (and other |
| settings) inside the template: <a href="#ref.directive.setting"><code>setting</code></a></p> |
| </li> |
| |
| <li> |
| <p>Directive to explicitly flush the output buffer: <a href="#ref.directive.flush"><code>flush</code></a></p> |
| </li> |
| |
| <li> |
| <p>The top-level (root) hash is available via the variable |
| <code class="inline-code">root</code>, which is now a reserved name.</p> |
| </li> |
| |
| <li> |
| <p>The misnamed <code class="inline-code">function</code> directive has |
| been renamed to <code class="inline-code">macro</code>.</p> |
| </li> |
| |
| <li> |
| <p>String literals support various new <a href="#topic.escapeSequence">escape sequences</a>, |
| including UNICODE escapes |
| (<code class="inline-code">\x<em class="code-color">CODE</em></code>)</p> |
| </li> |
| |
| <li> |
| <p>The <a href="#ref.directive.compress"><code>compress</code></a> |
| directive is now more conservative in removing line |
| breaks.</p> |
| </li> |
| |
| <li> |
| <p>Built-in to capitalize the first word: <a href="#ref_builtin_cap_first"><code>cap_first</code></a></p> |
| </li> |
| |
| <li> |
| <p>Built-in to generate on-the-fly templates: <a href="#ref_builtin_interpret"><code>interpret</code></a></p> |
| </li> |
| |
| <li> |
| <p><a href="#ref.directive.stop"><code>stop</code></a> |
| directive has an optional parameter to describe the reason of |
| termination</p> |
| </li> |
| |
| <li> |
| <p>Better error messages.</p> |
| </li> |
| |
| <li> |
| <p>New variable type: date. <em>Date support is |
| experimental. It can change substantially in the future. Keep |
| this in mind if you use it.</em></p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_226">Changes on the Java side</h5> |
| |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">ObjectWrapper</code>: You can put |
| non-<code class="inline-code">TemplateModel</code> objects directly into |
| hashes, sequences and collections, and they will be |
| automatically wrapped with the appropriate |
| <code class="inline-code">TemplateModel</code> implementation. The API of |
| objects that are exposed to templates |
| (<code class="inline-code">Simple<em class="code-color">XXX</em></code>) has |
| been changed according to this, for example in |
| <code class="inline-code">SimpleHash</code> the old <code class="inline-code">put(String key, |
| TemplateModel value)</code> is now <code class="inline-code">put(String key, |
| Object object)</code>. Also, you can pass any kind of object |
| as data-model to <code class="inline-code">Template.process</code>. The |
| alternative reflection based <code class="inline-code">ObjectWrapper</code> |
| can expose the members of any Java object automatically for the |
| designer. More information: <a href="#pgui_datamodel_objectWrapper">Object wrapping</a>, |
| <a href="#pgui_misc_beanwrapper">Bean wrapper</a>, <a href="#pgui_misc_jythonwrapper">Jython wrapper</a>.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">Configuration</code> object was introduced |
| as a central point to hold all your FreeMarker-related global |
| settings, as well as commonly used variables that you want to |
| have available from any template. Also it encapsulates the |
| template cache and can be used to load templates. For more |
| information read <a href="#pgui_config">Programmer's Guide/The Configuration</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateLoader</code>: pluggable template |
| loader, separates caching from template loading</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateNumberModel</code>-s do not control |
| their formatting anymore. They just store the data (i.e. a |
| number). Number formatting is done by the FreeMarker core based |
| on the <code class="inline-code">locale</code> and |
| <code class="inline-code">number_format</code> settings. This logic applies to |
| the new experimental date type as well.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateBooleanModel</code> introduced: Only |
| objects that implements this interface can be used as a boolean |
| in true/false conditions. More info: <a href="#pgui_datamodel_scalar">Programmer's Guide/The Data Model/Scalars</a></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateDateModel</code> introduced: objects |
| that implements this interface are recognized as dates and can |
| be locale-sensitively formatted. <em>Date support is |
| experimental in FreeMarker 2.1. It can change substantially in |
| the future. Keep this in mind if you use it.</em></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">TemplateModelRoot</code> interface was |
| deprecated. As of FreeMarker 2.1, you can simply use any |
| instance of <code class="inline-code">TemplateHashModel</code> instead. This |
| actually is due to a significant architectural change. Variables |
| set or defined in a template are stored in a separate |
| <code class="inline-code">Environment</code> object that only exists while the |
| template is being rendered. Thus, the template doesn't modify |
| the root hash.</p> |
| </li> |
| |
| <li> |
| <p>Changes to transformations</p> |
| |
| <ul> |
| <li> |
| <p>Completely rewritten |
| <code class="inline-code">TemplateTransformModel</code> interface. More |
| flexible, and does not impose output holding. More |
| information: <a href="#pgui_datamodel_directive">Programmer's Guide/The Data Model/Directives</a></p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">transform</code> directive now takes |
| an optional set of key/value pairs. <code class="inline-code"><transform |
| myTransform; |
| <em class="code-color">key1</em>=<em class="code-color">value1</em>, |
| <em class="code-color">key2</em>=<em class="code-color">value2</em> |
| <em class="code-color">...</em>></code>. More |
| information: <a href="#ref.directive.transform"><code>transform</code> |
| directive</a></p> |
| </li> |
| |
| <li> |
| <p>The transforms that ship with the FreeMarker core are |
| now available by default to all templates - i.e. |
| <code class="inline-code"><transform html_escape></code> will invoke |
| the |
| <code class="inline-code">freemarker.template.utility.HtmlEscape</code> |
| transform. More information: <a href="#pgui_config_sharedvariables">Programmer's Guide/The Configuration/Shared variables</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>User-defined <code class="inline-code">TemplateModel</code> objects now |
| can access the runtime environment (read and set variables, get |
| the current locale, etc.) using an |
| <code class="inline-code">Environment</code> instance, which can be obtained |
| by the static |
| <code class="inline-code">Environment.getCurrentEnvironment()</code> method. |
| As a result, <code class="inline-code">TemplateScalarModel.getAsString</code> |
| has been changed: it has no locale parameter.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">TemplateExceptionHandler</code>-s make it |
| possible to define your own rules on what to do when a runtime |
| error occurs (e.g. accessing a non existing variable) during |
| template processing. For example, you can abort template |
| processing (recommended for most sites), or skip the problematic |
| statement and continue template processing (similar to old |
| behavior). DebugMode has been removed, use |
| <code class="inline-code">TemplateExceptionHandler.DEBUG_HANDLER</code> or |
| <code class="inline-code">HTML_DEBUG_HANDLER</code> instead.</p> |
| </li> |
| |
| <li> |
| <p>Logging: FreeMarker logs certain events (runtime errors |
| for example). For more information read <a href="#pgui_misc_logging">Programmer's Guide/Miscellaneous/Logging</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">SimpleIterator</code> was removed, but we |
| provide a <code class="inline-code">TemplateCollectionModel</code> |
| implementation: <code class="inline-code">SimpleCollection</code>.</p> |
| </li> |
| |
| <li> |
| <p>Arithmetic engine is pluggable |
| (<code class="inline-code">Configuration.setArithmeticEngine</code>). The core |
| distribution comes with two engines: |
| <code class="inline-code">ArithmeticEngine.BIGDECIMAL_ENGINE</code> (the |
| default) that converts all numbers to |
| <code class="inline-code">BigDecimal</code> and then operates on them, and |
| <code class="inline-code">ArithmeticEngine.CONSERVATIVE_ENGINE</code> that |
| uses (more-or-less) the widening conversions of Java language, |
| instead of converting everything to |
| <code class="inline-code">BigDecimal</code>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">freemarker.ext.beans</code> |
| package: The JavaBeans adapter layer has suffered several major |
| changes. First, <code class="inline-code">BeansWrapper</code> is no longer a |
| static utility class - you can now create instances of it, and |
| every instance can have its own instance caching policy and |
| security settings. These security settings are also new - you |
| can now create JavaBeans wrappers that hide methods that are |
| considered unsafe or inappropriate in a templating environment. |
| By default, you can no longer call methods like |
| <code class="inline-code">System.exit()</code> from the template (although you |
| can manually turn off these safeguards). The |
| <code class="inline-code">StaticModel</code> and |
| <code class="inline-code">StaticModels</code> classes are gone; their |
| functionality is now replaced with the |
| <code class="inline-code">BeansWrapper.getStaticModels()</code> method.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">freemarker.ext.jython</code> package: |
| FreeMarker can now directly use Jython objects as data-models |
| using the <a href="#pgui_misc_jythonwrapper">Jython |
| wrapper</a>.</p> |
| </li> |
| |
| <li> |
| <p>Changes to <code class="inline-code">freemarker.ext.jdom</code> package: |
| The package now uses the <em>Jaxen</em> package |
| instead of its predecessor, the |
| <em>werken.xpath</em> package to evaluate XPath |
| expressions. Since <em>Jaxen</em> is a successor to |
| <em>werken.xpath</em>, this can be considered to be |
| an upgrade. As a consequence, namespace prefixes are now |
| recognized in XPath expressions and the overall XPath |
| conformance is better.</p> |
| </li> |
| |
| <li> |
| <p>Better error reporting: If the processing of a template is |
| aborted by a <code class="inline-code">TemplateException</code> being thrown, |
| or using a <code class="inline-code"><#stop></code> directive, |
| FreeMarker will now output an execution trace with line and |
| column numbers relative to the template source.</p> |
| </li> |
| |
| <li> |
| <p>The output is written to a simple |
| <code class="inline-code">Writer</code>; no more |
| <code class="inline-code">PrintWriter</code>. This redesign causes FreeMarker |
| to no longer swallow <code class="inline-code">IOException</code>s during |
| template processing.</p> |
| </li> |
| |
| <li> |
| <p>Various API cleanups, primarily the removing of |
| superfluous constructor and method overloads.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_227">Other changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Documentation has been rewritten from scratch</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_228">Differences between the RC1 and final release</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Added the support for date models and locale-sensitive |
| date formatting. <em>Date support is experimental in |
| FreeMarker 2.1. It can change substantially in the future. Keep |
| this in mind if you use it.</em></p> |
| </li> |
| |
| <li> |
| <p>Added the <code class="inline-code">default</code> built-in which makes |
| it possible to specify default values for undefined |
| expressions.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">SimpleIterator</code> has been removed, |
| <code class="inline-code">SimpleCollection</code> has been introduced</p> |
| </li> |
| |
| <li> |
| <p>Arithmetic engine is pluggable. The core now contains two |
| arithmetic engines: |
| <code class="inline-code">ArithmeticEngine.BIGDECIMAL_ENGINE</code> and |
| <code class="inline-code">ArithmeticEngine.CONSERVATIVE_ENGINE</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">BeansWrapper</code> supports a new exposure |
| level: <code class="inline-code">EXPOSE_NOTHING</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Constants</code> interface was removed. |
| <code class="inline-code"><em class="code-color">...</em>_WRAPPER</code> |
| constants have been moved from <code class="inline-code">Constants</code> to |
| <code class="inline-code">ObjectWrapper</code>, |
| <code class="inline-code">EMPTY_STRING</code> constant was moved to |
| <code class="inline-code">TemplateScalarModel</code>, |
| <code class="inline-code">NOTHING</code> constant was moved to |
| <code class="inline-code">TemplateModel</code>, <code class="inline-code">TRUE</code> and |
| <code class="inline-code">FALSE</code> constants were moved to |
| <code class="inline-code">TemplateBooleanModel</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">JAVABEANS_WRAPPER</code> was renamed to |
| <code class="inline-code">BEANS_WRAPPER</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Configuration.get</code> and |
| <code class="inline-code">put</code>, <code class="inline-code">putAll</code> were renamed |
| to <code class="inline-code">getSharedVariable</code> and |
| <code class="inline-code">setSharedVariable</code>, |
| <code class="inline-code">setAllSharedVariables</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Configuration.getClassicCompatibility</code>, |
| <code class="inline-code">setClassicCompatibility</code> were renamed to |
| <code class="inline-code">isClassicCompatible</code>, |
| <code class="inline-code">setClassicCompatible</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">Template.process</code> method overloads with |
| <code class="inline-code">useReflection</code> parameter was removed. But now |
| we have <code class="inline-code">setObjectWrapper</code> method in the |
| <code class="inline-code">Configuration</code>, so you can set the preferred |
| root-object wrapper there.</p> |
| </li> |
| |
| <li> |
| <p>Some superfluous method overloads were removed; these |
| changes are backward compatible with RC1</p> |
| </li> |
| |
| <li> |
| <p>Various minor JavaDoc and Manual improvements</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: <code class="inline-code">include</code> directive has |
| calculated the base path of relative paths wrongly</p> |
| </li> |
| |
| <li> |
| <p>Bugfix: We have accidentally used a J2SE 1.3 class, but |
| FreeMarker 2.1 must able to run on J2SE 1.2</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_01">2.01</h4> |
| |
| |
| <p>The main improvement is in error reporting. Now exceptions are |
| much more informative since they come with complete line number and |
| column information.</p> |
| |
| <p>The only API change between 2.0 and 2.01 was the elimination of |
| the CacheListener/CacheEvent API. Now, if the updating of a template |
| file fails, the exception is thrown back to the caller to handle. If |
| you want logging to occur when a template file is updated |
| successfully, you can override the logFileUpdate() method in |
| FileTemplateCache.</p> |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_0">2.0</h4> |
| |
| |
| <p>FreeMarker 2.0 final was released on 18 April 2002. The changes |
| with respect to the previous release, 2.0 RC3 are fairly minor.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_229">Bugfixes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>There were a couple of bugs in handling null values, where |
| Lazarus did not do the same thing as FreeMarker Classic. |
| Traditionally, in FreeMarker, nulls were treated as being |
| equivalent to an empty string in the appropriate context. At |
| this point, to the best of our knowledge, there is backward |
| compatibility with FreeMarker Classic in this respect.</p> |
| </li> |
| |
| <li> |
| <p>Literal strings can now include line breaks. This was a |
| backward compatibility issue with FreeMarker Classic that has |
| been fixed.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_230">Changes to the Template language</h5> |
| |
| |
| <ul> |
| <li> |
| <p>You can use the extra built-in of |
| <code class="inline-code">myString?web_safe</code> to convert a string to its |
| "web-safe" equivalent, where problematic characters such as |
| '<' are converted to &lt;.</p> |
| </li> |
| |
| <li> |
| <p>In displaying numbers with a fractional part, the |
| rendering apparatus now respects the decimal separator of the |
| template's locale, so that, for example, in continental Europe, |
| you would see 1,1 and in the U.S. locale, 1.1.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_231">Changes to the API</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">getAsString()</code> method in the |
| <code class="inline-code">TemplateScalarModel</code> interface now takes a |
| <code class="inline-code">java.util.Locale</code> as a parameter. For the most |
| part, this is a hook for later use. In the default |
| implementation, <code class="inline-code">SimpleScalar</code>, this parameter |
| is unused. If you are implementing this interface yourself, your |
| implementation may ignore the parameter. However, it will be |
| appealing for certain implementations.</p> |
| </li> |
| |
| <li> |
| <p>The constructors of <code class="inline-code">FileTemplateCache</code> |
| have changed. If you are using an absolute directory on the file |
| system as the location of your templates, you need to pass in an |
| instance of <code class="inline-code">java.io.File</code> to indicate the |
| location. If you use the constructors that take a string, this |
| is taken to mean relative to the classloader classpath.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_232">Miscellany</h5> |
| |
| |
| <p>The ant build script build.xml now contains a target that |
| builds a .war file containing the Hello, World and Guestbook |
| examples. It builds a fmexamples.war. For example, if you are using |
| Tomcat in its out-of-the-box configuration, you would place this |
| under <TOMCAT_HOME>/webapps and then you would use |
| http://localhost:8080/fmexamples/servlet/hello and |
| http://localhost:8080/fmexamples/servlet/guestbook for the Hello, |
| World and Guestbook examples respectively.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_0RC3">2.0 RC3</h4> |
| |
| |
| <p>FreeMarker 2.0 RC3 was released on 11 April 2002. This release |
| was primarily devoted to fixing bugs that were reported in RC2.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_233">Bug Fixes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Variables defined in an <include...> were not |
| available in the enclosing page. This has been fixed.</p> |
| </li> |
| |
| <li> |
| <p>The JavaCC parser was not configured to handle Unicode |
| input correctly. Now, Unicode support is working.</p> |
| </li> |
| |
| <li> |
| <p>There was a bug when comparing a number with null. It |
| should have returned false, but threw an exception instead. This |
| has been fixed.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_234">Changes to the Template Language</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The syntax of the include directive has changed. To |
| indicate an unparsed include file, you do as follows:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><include "included.html" ; parsed="n" ></pre></div> |
| |
| <p>You can also indicate the encoding of the included file |
| this way:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> <include "included.html" ; encoding="ISO-8859-5"></pre></div> |
| </li> |
| |
| <li> |
| <p>The built-in myString?trim was added for trimming the |
| leading and trailing white-space from strings.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_235">API changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The TemplateEventAdapter machinery was taken out. This was |
| never set up in a very useful manner and we anticipate that |
| version 2.1 will have more complete support for logging |
| events.</p> |
| </li> |
| |
| <li> |
| <p>The template caching mechanism was streamlined and |
| simplified.</p> |
| </li> |
| |
| <li> |
| <p>The FileTemplateCache can now be configured to load files |
| relative to a class loader, using the Class.getResource() call. |
| This allows templates to be bundled up in .jar files or in a |
| .war file for easy deployment of web-based apps.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_0RC2">2.0 RC2</h4> |
| |
| |
| <p>FreeMarker 2.0 RC 2 was released on 4 April 2002. Here is a |
| summary of changes wrt to the first release.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_236">Changes to Template Language</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Certain built-in functionality is provided via a new |
| operator, '?'. Thus, <code class="inline-code">myList?size</code> provides the |
| number of elements in a list. Similarly, |
| <code class="inline-code">myString?length</code> provides the length of a |
| string, <code class="inline-code">myString?upper_case</code> puts the string |
| all in capital letters, and <code class="inline-code">myHash?keys</code> |
| provides a sequence containing the keys in the hash. See <a href="#ref_builtins">Reference/Built-in Reference</a> for list of all available |
| built-ins.</p> |
| </li> |
| |
| <li> |
| <p>Numerical comparisons can now be made using the "natural" |
| operators < and > but there are also "web-safe" |
| alternatives, such as <em>\lt</em> and |
| <em>\gt</em>, since the use of these characters may |
| confuse HTML editors and parsers. Note that these changed |
| between rc1 and rc2, they now start with a backslash. A little |
| asymmetry is the fact that if you use the natural greater-than |
| or greater-than-or-equals operators (i.e. > or >=) the |
| expression must be in parentheses. With any other operator, the |
| parentheses are optional.</p> |
| </li> |
| |
| <li> |
| <p>Within an iteration loop -- i.e. a |
| <code class="inline-code">foreach</code> or a <code class="inline-code">list</code> block -- |
| the current count in the loop is available as the special |
| variable |
| <code class="inline-code"><em class="code-color">index</em>_count</code>. where |
| <em>index</em> is the name of the variable in |
| the iteration. A boolean variable called |
| <code class="inline-code"><em class="code-color">index</em>_has_next</code> is |
| also defined that indicates whether there are any more items in |
| the iteration after this one. Note that the index starts at |
| zero, so you will often be adding one to it in practice.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code"><#break></code> directive can now be |
| used to break out of a <code class="inline-code"><#foreach...></code> or |
| a <code class="inline-code"><list...></code> loop. (Prior to this |
| version, it only worked within a switch-case block.) There is a |
| new directive called <code class="inline-code"><#stop></code> that, when |
| encountered, simply halts processing of the template. This can |
| be useful for debugging purposes.</p> |
| </li> |
| |
| <li> |
| <p>When invoking java methods that have been exposed to the |
| page, using the code in freemarker.ext.*, there are built-ins |
| that allow you to indicate the numerical type that you wish to |
| pass as the value. For instance, if you had two methods, one |
| that takes an int and another that takes a long, and you wanted |
| to pass in a value, you would have to specify which method. |
| <code class="inline-code">myMethod(1?int)</code> or |
| <code class="inline-code">myMethod(1?long)</code>. This is unnecessary if |
| there is only one method of the given name.</p> |
| </li> |
| |
| <li> |
| <p>Ranges can be used to get the sublist from a list or the |
| substring of a string. For example: |
| <code class="inline-code">myList[0..3]</code> will return items 0 through 3 of |
| the list in question. Or, for example, you could get all the |
| elements of the list except for the first and last ones via: |
| <code class="inline-code">myList[1..(myList?size-2)]</code></p> |
| </li> |
| |
| <li> |
| <p>Or we could get the first 6 characters of a string via |
| <code class="inline-code">myString[0..5]</code></p> |
| </li> |
| |
| <li> |
| <p>Lists can be concatenated using the '+' operator. |
| Previously, this overloading of '+' only applied to |
| strings.</p> |
| </li> |
| |
| <li> |
| <p>An attempt to compare a number to a string now throws an |
| exception, since it is indicative of a coding error. Note that |
| there is a backward compatibility mode that can be set (see |
| below) that loosens this up in order to be able to process |
| legacy templates.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_237">API Changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">TemplateSequenceModel</code> interface now |
| has a <code class="inline-code">size()</code> method for getting the number of |
| elements in the sequence in question.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">TemplateModelIterator</code> interface now |
| has a <code class="inline-code">hasNext()</code> method.</p> |
| </li> |
| |
| <li> |
| <p>The default sequence and hash implementations, |
| <code class="inline-code">freemarker.template.SimpleSequence</code> and |
| <code class="inline-code">freemarker.template.SimpleHash</code> are now |
| unsynchronized. If you need the methods to be synchronized, you |
| can get a synchronized wrapper via the |
| <code class="inline-code">synchronizedWrapper()</code> in either class.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">freemarker.utility.ExtendedList</code> and |
| <code class="inline-code">freemarker.utility.ExtendedHash</code> classes were |
| removed, since all of the extra keys that it defined are now |
| available using the appropriate '?' built-in operation, i.e. |
| <code class="inline-code">myHash?keys</code> or <code class="inline-code">myList?size</code> |
| or <code class="inline-code">myList?last</code>.</p> |
| </li> |
| |
| <li> |
| <p>There is a method in |
| <code class="inline-code">java.freemarker.Configuration</code> named |
| <code class="inline-code">setDebugMode()</code> which allows you to decide |
| whether stack traces are simply output to the web client (the |
| best situation in development) or thrown back to the caller to |
| be handled more gracefully (the best situation in |
| production).</p> |
| </li> |
| |
| <li> |
| <p>There is a flag that can be set to turn on a processing |
| mode that is more backward-compatible with FreeMarker Classic. |
| This is off by default, but you can set it via |
| <code class="inline-code">Template.setClassicCompatibility(true)</code>. What |
| this does is that it allows scalars to be treated as a |
| single-item list in a list directive. Also, it allows somewhat |
| more looseness about types. In FreeMarker 1.x, <code class="inline-code"><#if |
| x=="1"></code> and <code class="inline-code"><#if x==1></code> |
| were in fact equivalent. This meant that legacy templates might |
| tend to be slack about this. If classic compatibility is not |
| set, an attempt to compare the string "1" with the number 1 will |
| result in an exception being thrown. (Note that it is preferable |
| to get your templates working without the backward compatibility |
| flag, since it usually will require only minor changes. However, |
| for people with a lot of templates and no time to check over |
| them, this flag may be of use.)</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h4 class="content-header header-section1" id="versions_2_0RC1">2.0 RC1</h4> |
| |
| |
| <p>The first public release of FreeMarker 2.0 was on 18 March 2002. |
| Here is a summary of the changes in the Lazarus release, with respect |
| to the last stable release of FreeMarker Classic.</p> |
| |
| <p><em>NOTA BENE</em>:</p> |
| |
| <p>Despite the changes delineated above, the Lazarus release is |
| almost entirely backward-compatible with FreeMarker Classic. We |
| believe that <em>most</em> existing code and templates |
| that work under FreeMarker Classic will continue working under |
| Lazarus, with at most minimal changes. In practice, the most common |
| cases where legacy template code is broken will be where assumptions |
| were made about numbers and strings being equivalent. Note that in |
| FreeMarker 2, 2 + 2 does not result in "22". The String "1" and the |
| number 1 are entirely different animals and thus, any code will be |
| broken if it relies on the boolean expression ("1"==1) being true. |
| There is a "classic compatibility mode" that can be set via: |
| <code class="inline-code">Template.setClassCompatibility()</code> that can be set so |
| that Lazarus emulates some of the quirky behavior of FreeMarker |
| Classic. However, any code that relied on the above "features" of |
| FreeMarker classic really should be reworked. You are less likely to |
| run into the other incompatibilities that are listed above. If you |
| come across any other anomalies, please do tell us about them.</p> |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_238">Support for Numerical operations, both arithmetic and |
| boolean, as well as numerical ranges.</h5> |
| |
| |
| <ul> |
| <li> |
| <p>Scalars can now be either strings or numbers. (In |
| FreeMarker Classic all scalars were strings.) The basic |
| operations allowed are addition, subtraction, multiplication, |
| division, and modulus using the <code class="inline-code">+</code>, |
| <code class="inline-code">-</code>, <code class="inline-code">*</code>, |
| <code class="inline-code">/</code>, and <code class="inline-code">%</code> operators |
| respectively. Arbitrary-precision arithmetic with integers and |
| floating point numbers are provided. Though our goal is |
| definitely to follow the principle of least surprise, for |
| backward compatibility, the <code class="inline-code">+</code> operator still |
| is used for string concatenation. If either the left hand side |
| or the right hand side of <code class="inline-code">lhs + rhs</code> is |
| non-numerical, we revert to interpreting this as string |
| concatenation. Thus, in FreeMarker 2, 2+2 evaluates to the |
| number 4, while any of "2"+2 or 2+"2" or "2"+"2" evaluate to the |
| string "22". In FreeMarker Classic, rather embarrassingly, all |
| of the above, including 2+2, evaluated to the string "22". An |
| attempt to use any other arithmetic operator besides the |
| <code class="inline-code">+</code> with non-numerical operands will cause an |
| exception to be thrown.</p> |
| </li> |
| |
| <li> |
| <p>Output of a numerical expression can be made explicit via |
| the alternative <code class="inline-code">#{....}</code> syntax. If the |
| expression within the curly parentheses does not evaluate to a |
| numerical value, an exception is thrown. The older ${....} |
| syntax can evaluate to either a number or a string. In general, |
| if, for logical reasons, the output <em>must</em> be |
| numerical, it is preferable to use the #{...} syntax, since it |
| adds an extra sanity check. Note that if, by some miracle, the |
| character sequence "#{" occurs in your template, you will have |
| to use a workaround to prevent problems. (The <noparse> |
| directive is one possibility.)</p> |
| </li> |
| |
| <li> |
| <p>In this release, there is a facility for specifying the |
| number of digits to show after the decimal point. The following |
| code specifies to show at least 3 digits after the decimal point |
| but not more than 6. This is optional. This option is only |
| available if you use the #{...} syntax.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template">#{foo + bar ; m3M6} </pre></div> |
| |
| <p>(Note that the above is something of a stopgap measure. |
| Future releases will move toward supporting fully |
| internationalization and localization of number and currency |
| formatting.</p> |
| </li> |
| |
| <li> |
| <p>Numerical expressions can be used in boolean expressions |
| via the comparison operators: <code class="inline-code">lt</code>, |
| <code class="inline-code">gt</code>, <code class="inline-code">lte</code>, and |
| <code class="inline-code">gte</code>. In the web space, where FreeMarker is |
| most used in practice, using the more natural operators such as |
| < and > would tend to confuse HTML-oriented editors. An |
| attempt to compare non-numerical expressions using these |
| operators leads to a <code class="inline-code">TemplateException</code> being |
| thrown. If, by some coincidence, you have variables named "lt", |
| "gt", "lte", or "gte", you will have to change their names, |
| since they are now keywords in the language.</p> |
| </li> |
| |
| <li> |
| <p>Numerical ranges are supported.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list 1990..2001 as year> |
| blah blah in the year ${year} blah |
| </#list> </pre></div> |
| |
| <p>The left hand and right hand sides of the |
| <code class="inline-code">..</code> operator must be numerical, or an |
| exception is thrown. They also need not be literal numbers, but |
| can be more complex expressions that evaluate to a numerical |
| scalar value. Note that it is also possible to write a range |
| that descends in value:</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"><#list 2001..1990 as year> |
| blah blah in the year ${year} blah blah |
| </#list> </pre></div> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_239">API Changes</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The <code class="inline-code">TemplateNumberModel</code> interface and |
| the <code class="inline-code">SimpleNumber</code> implementation were added to |
| support exposing numerical values.</p> |
| </li> |
| |
| <li> |
| <p>The <code class="inline-code">TemplateListModel</code> API in FreeMarker |
| Classic had some design problems -- particularly in terms of |
| supporting thread-safe code. It has been deprecated in favor of |
| the following API's: <code class="inline-code">TemplateCollectionModel</code> |
| and <code class="inline-code">TemplateSequenceModel</code>. The |
| <code class="inline-code">SimpleList</code> class was refactored to implement |
| the above interfaces (and paradoxically, does not implement the |
| TemplateListModel interface.) Code that uses the deprecated |
| <code class="inline-code">TemplateListModel</code> should be |
| refactored.</p> |
| </li> |
| |
| <li> |
| <p>The Expose Package by Attila Szegedi has been made an |
| integral part of the FreeMarker distribution and is now under |
| the freemarker.ext.* hierarchy. This package provides advanced |
| models for representing arbitrary Java objects as template |
| models, for representing XML documents as template models, as |
| well as classes to facilitate the integration of FreeMarker with |
| servlets and Ant.</p> |
| </li> |
| |
| <li> |
| <p>In FreeMarker Classic, there were some utility classes |
| such as <code class="inline-code">freemarker.template.utility.Addition</code> |
| etcetera that existed as workarounds for the lack of numerical |
| operations in FreeMarker. Those have been removed and will |
| probably not be missed.</p> |
| </li> |
| |
| <li> |
| <p>In FreeMarker Classic, the <code class="inline-code">SimpleScalar</code> |
| object was mutable, it had a <code class="inline-code">setValue</code> method. |
| This was fairly obviously a design mistake. Any code that relied |
| on this must be refactored. Note that in this release, both |
| <code class="inline-code">SimpleScalar</code> and the newly introduced |
| <code class="inline-code">SimpleNumber</code> are both immutable and |
| final.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| <h5 class="content-header header-section2" id="autoid_240">Syntactical Miscellany</h5> |
| |
| |
| <ul> |
| <li> |
| <p>The if-elseif-else syntax was introduced. FreeMarker |
| classic only had if-else. This construct should probably (in the |
| opinion of the author of this document -- Revusky) be used in |
| preference to switch-case since the switch-case with |
| fall-through is a notoriously error-prone construct for most |
| mortal men.</p> |
| </li> |
| |
| <li> |
| <p>You can now do a multiple assignment in one |
| <assign...> directive. For example: <code class="inline-code"><assign x |
| = 1, y = price*items, message="foo"></code></p> |
| </li> |
| |
| <li> |
| <p>A scalar will no longer be interpreted as a one-item list |
| in a <list...> or <#foreach...> block. If you have |
| code that relied on this feature, there is an easy workaround, |
| since you can simply define a list literal with exactly one |
| item.</p> |
| |
| |
| |
| <div class="code-wrapper"><pre class="code-block code-template"> <assign y=[x]> |
| <strong>and then...</strong> |
| <list y as item>...</list> </pre></div> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3 class="content-header header-chapter" id="app_license">License</h3> |
| |
| |
| |
| |
| <p>FreeMarker 1.x was released under the LGPL license. Later, by |
| community consensus, we have switched over to a BSD-style license. As of |
| FreeMarker 2.2pre1, the original author, <em>Benjamin |
| Geer</em>, has relinquished the copyright in behalf of Visigoth |
| Software Society. The current copyright holder is the Visigoth Software |
| Society.</p> |
| |
| <p> </p> |
| |
| <p>Copyright (c) 2003 The Visigoth Software Society. All rights |
| reserved.</p> |
| |
| <p>Redistribution and use in source and binary forms, with or without |
| modification, are permitted provided that the following conditions are |
| met:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>Redistributions of source code must retain the above copyright |
| notice, this list of conditions and the following disclaimer.</p> |
| </li> |
| |
| <li> |
| <p>The end-user documentation included with the redistribution, |
| if any, must include the following acknowledgement: <em>"This |
| product includes software developed by the Visigoth Software Society |
| (http://www.visigoths.org/)."</em> Alternately, this |
| acknowledgement may appear in the software itself, if and wherever |
| such third-party acknowledgements normally appear.</p> |
| </li> |
| |
| <li> |
| <p>Neither the name "FreeMarker", "Visigoth", nor any of the |
| names of the project contributors may be used to endorse or promote |
| products derived from this software without prior written |
| permission. For written permission, please contact |
| visigoths@visigoths.org.</p> |
| </li> |
| |
| <li> |
| <p>Products derived from this software may not be called |
| "FreeMarker" or "Visigoth" nor may "FreeMarker" or "Visigoth" appear |
| in their names without prior written permission of the Visigoth |
| Software Society.</p> |
| </li> |
| </ol></div> |
| |
| <p>THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED |
| WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN |
| NO EVENT SHALL THE VISIGOTH SOFTWARE SOCIETY OR ITS CONTRIBUTORS BE |
| LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF |
| THE POSSIBILITY OF SUCH DAMAGE.</p> |
| |
| <p> </p> |
| |
| <p>This software consists of voluntary contributions made by many |
| individuals on behalf of the Visigoth Software Society. For more |
| information on the Visigoth Software Society, please see <a href="http://www.visigoths.org/">http://www.visigoths.org/</a></p> |
| |
| <p> |
| <a href="#gloss.attribute">A</a> | <a href="#gloss.boolean">B</a> | <a href="#gloss.character">C</a> | <a href="#gloss.dataModel">D</a> | <a href="#gloss.element">E</a> | <a href="#gloss.FTL">F</a> | <a href="#gloss.hashVariable">H</a> | <a href="#gloss.lineBreak">L</a> | <a href="#gloss.macroDefinitionBody">M</a> | <a href="#gloss.outputEncoding">O</a> | <a href="#gloss.predefinedDirective">P</a> | <a href="#gloss.regularExpression">R</a> | <a href="#gloss.scalarVariable">S</a> | <a href="#gloss.tag">T</a> | <a href="#gloss.UCS">U</a> | <a href="#gloss.whiteSpace">W</a> | <a href="#autoid_243">X</a> </p> |
| |
| <dl> |
| |
| <dt><a name="gloss.attribute"></a>Attribute</dt> |
| |
| |
| <dd> |
| <p>In connection with <a href="#gloss.XML">XML</a> or HTML |
| (or <a href="#gloss.SGML">SGML</a> in general), attributes are |
| the named values associated with elements. For example, in |
| <code class="inline-code"><body bgcolor=black |
| text=green><em class="code-color">...</em></body></code>, |
| the attributes are <code class="inline-code">bgcolor=black</code> and |
| <code class="inline-code">text=green</code>. On the left side of |
| <code class="inline-code">=</code> is the name of the attribute, while on the right |
| side is the value of the attribute. Note that in XML, the values must |
| be quoted (for example: <code class="inline-code"><body bgcolor="black" |
| text='green'></code>), while in HTML it is optional for certain |
| values.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.startTag">Start-tag</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.boolean"></a>Boolean</dt> |
| |
| |
| <dd> |
| <p>This is a variable type. A boolean variable represents a logical |
| true or false (yes or no). For example, if the visitor has been logged |
| in or not. There are only two possible boolean values: |
| <code class="inline-code">true</code> and <code class="inline-code">false</code>. Typically, you |
| will use booleans with an <code class="inline-code"><#if |
| <em class="code-color">...</em>></code> directive when you want |
| to display text based on some condition, say, you show a certain part |
| of the page only for visitors who has logged in.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.character"></a>Character</dt> |
| |
| |
| <dd> |
| <p>A symbol that people use in writing. Examples of characters: |
| Latin capital letter A (``A''), Latin small letter A (``a''), digit |
| four (``4''), number sign (``#''), colon (``:'')</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.charset"></a>Charset</dt> |
| |
| |
| <dd> |
| <p>A charset is a rule (algorithm) for transforming a sequence of |
| <a href="#gloss.character">characters</a> (text) to a sequence |
| of bits (or in practice, to a sequence of bytes). Whenever a character |
| sequence is stored on a digital media, or sent through a digital |
| channel (network), a charset must be applied. Examples of charsets are |
| ISO-8859-1, ISO-8859-6, Shift_JIS , UTF-8.</p> |
| |
| <p>The capabilities of different charsers are different, that is, |
| not all charsets can be used for all languages. For example ISO-8859-1 |
| can't represent Arabic letters, but ISO-8859-6 can, however it can't |
| represent the accented letters that that ISO-8859-1 can. Most charsets |
| are highly restrictive regarding the allowed characters. UTF-8 allows |
| virtually all possible characters, but most text editors can't handle |
| it yet (2004).</p> |
| |
| <p>When different software components exchange text (as the HTTP |
| server and the browser, or the text editor you use for saving |
| templates and FreeMarker who loads them), it's very important that |
| they agree in the charset used for the binary encoding of the text. If |
| they don't, then the binary data will be misinterpreted by the |
| receiver (loader) component, which usually results in the distortion |
| of the non-English letters.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.collectionVariable"></a>Collection</dt> |
| |
| |
| <dd> |
| <p>A variable that (in conjunction with the <code class="inline-code">list</code> |
| directive) can spit out a series of variables.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.dataModel"></a>Data-model</dt> |
| |
| |
| <dd> |
| <p>Something that holds the information the template has to show |
| (or use in some other ways) when the template processor assembles the |
| output (e.g. a Web page). In FreeMarker this is best visualized as a |
| tree.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.directive"></a>Directive</dt> |
| |
| |
| <dd> |
| <p>Instructions to FreeMarker used in <a href="#gloss.FTL">FTL</a> <a href="#gloss.template">templates</a>. They are invoked by <a href="#gloss.FTLTag">FTL tags</a>.</p> |
| |
| |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.predefinedDirective">Predefined directive</a>, |
| <a href="#gloss.userDefinedDirective">User-defined directive</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.element"></a>Element</dt> |
| |
| |
| <dd> |
| <p>Elements are the most fundamental building pieces of <a href="#gloss.SGML">SGML</a> documents; an SGML document is |
| basically a tree of elements. Example of elements used in HTML: body, |
| head, title, p, h1, h2.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.endTag"></a>End-tag</dt> |
| |
| |
| <dd> |
| <p><a href="#gloss.tag">Tag</a>, which indicates that the |
| following content is not under the element. Example: |
| <code class="inline-code"></body></code>.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.startTag">Start-tag</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.environment"></a>Environment</dt> |
| |
| |
| <dd> |
| <p>An <code class="inline-code">Environment</code> object stores the runtime |
| state of a single template <a href="#gloss.templateProcessingJob">template processing job</a>. |
| That is, for each |
| <code class="inline-code">Template.process(<em class="code-color">...</em>)</code> |
| call, an <code class="inline-code">Environment</code> instance will be created, and |
| then discarded when <code class="inline-code">process</code> returns. This object |
| stores the set of temporary variables created by the template, the |
| value of settings set by the template, the reference to the data-model |
| root, etc. Everything that is needed to fulfill the template |
| processing job.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.XML"></a>Extensible Markup Language</dt> |
| |
| |
| <dd> |
| <p>A subset (restricted version) of <a href="#gloss.SGML">SGML</a>. This is less powerful than SGML, but |
| it easier to learn and much easier to process with programs. If you |
| are an HTML author: XML documents are similar to HTML documents, but |
| the XML standard doesn't specify the usable elements. XML is a much |
| more general-purpose thing than HTML. For example you can use XML to |
| describe Web pages (like HTML) or to describe non-visual information |
| like a phone book database.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.SGML">Standard Generalized Markup Language</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.FTL"></a>FreeMarker Template Language</dt> |
| |
| |
| <dd> |
| <p>Simple programming language designed to write text file |
| templates, especially HTML templates.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="autoid_241"></a>FTL</dt> |
| |
| |
| <dd>See |
| <a href="#gloss.FTL">FreeMarker Template Language</a> |
| </dd> |
| |
| |
| <dt><a name="gloss.FTLTag"></a>FTL tag</dt> |
| |
| |
| <dd> |
| <p><a href="#gloss.tag">Tag</a>-like text fragment used to |
| invoke FreeMarker <a href="#gloss.directive">directives</a> in |
| <a href="#gloss.FTL">FTL</a> <a href="#gloss.template">templates</a>. These are similar to HTML |
| or XML tags at the first glance. The most prominent difference is that |
| the tag name is started with <code class="inline-code">#</code> or |
| <code class="inline-code">@</code>. Another important difference is that FTL tags do |
| not use <a href="#gloss.attribute">attributes</a>, but a |
| substantially different syntax to specify parameters. Examples of FTL |
| tags: <code class="inline-code"><#if newUser></code>, |
| <code class="inline-code"></#if></code>, <code class="inline-code"><@menuitem |
| title="Projects" link="projects.html"/></code></p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.fullQualifiedName"></a>Full-qualified name</dt> |
| |
| |
| <dd> |
| <p>... of nodes (XML node or other FTL node variable): The |
| full-qualified name of a node specifies not only the node name |
| (<code class="inline-code"><em class="code-color">node</em>?node_name</code>), but |
| also the node namespace |
| (<code class="inline-code"><em class="code-color">node</em>?node_namespace</code>), |
| this way it unambiguously identify a certain kind of node. The format |
| of the full-qualified name is |
| <code class="inline-code"><em class="code-color">nodeName</em></code> or |
| <code class="inline-code"><em class="code-color">prefix</em>:<em class="code-color">nodeName</em></code>. |
| The prefix is shorthand to identify the node namespace (the a node |
| namespace is usually specified with a long ugly URI). In FTL, prefixes |
| are associated with the node namespaces with the |
| <code class="inline-code">ns_prefixes</code> parameter of <a href="#ref.directive.ftl">the <code>ftl</code> |
| directive</a>. In XML files, prefixes are associated with the node |
| namespaces with the |
| <code class="inline-code">xmlns:<em class="code-color">prefix</em></code> attributes. |
| The lack of the prefix means that the node uses the default node |
| namespace, if a default node namespace is defined; otherwise it means |
| that the node does not belong to any node namespace. The default node |
| namespace is defined in FTL by registering reserved prefix |
| <code class="inline-code">D</code> with the <code class="inline-code">ns_prefixes</code> parameter |
| of the <code class="inline-code">ftl</code> directive. In XML files it is defined |
| with attribute <code class="inline-code">xmlns</code>.</p> |
| |
| <p>... of Java classes: The full-qualified name of a Java class |
| contains both the class name and the name of the package the class |
| belongs to. This way it unambiguously specifies the class, regardless |
| of the context. An example of full-qualifed class name: |
| <code class="inline-code">java.util.Map</code> (as opposed to |
| <code class="inline-code">Map</code>).</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.hashVariable"></a>Hash</dt> |
| |
| |
| <dd> |
| <p>A variable that acts as a container that stores subvariables |
| that can be retrieved via a string that is a lookup name.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.sequenceVariable">Sequence</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.lineBreak"></a>Line break</dt> |
| |
| |
| <dd> |
| <p>Line break is a special character (or a sequence of special |
| characters) that causes a line breaking when you see the text as plain |
| text (say, when you read the text with Windows notepad). Typically you |
| type this character by hitting ENTER or RETURN key. The line break is |
| represented with different characters on different platforms (to cause |
| incompatibility and confusion...): ``line feed'' character on UNIX-es, |
| ``carriage return'' character on Macintosh, ``carriage return''+``line |
| feed'' (two characters!) on Windows and DOS. Note that line breaks in |
| HTML do not have a visual effect when viewed in a browser; you must |
| use markup such as <code class="inline-code"><BR></code> for that. This manual |
| never means <code class="inline-code"><BR></code> when it says |
| ``line-break''.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.macroDefinitionBody"></a>Macro definition body</dt> |
| |
| |
| <dd> |
| <p>The template fragment between the <code class="inline-code"><#macro |
| <em class="code-color">...</em>></code> and |
| <code class="inline-code"></#macro></code>. This template fragment will be |
| executed when you call the macro (for example as |
| <code class="inline-code"><@myMacro/></code>).</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.methodVariable"></a>Method</dt> |
| |
| |
| <dd> |
| <p>A variable that calculates something based on parameters you |
| give, and returns the result.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.MVC"></a>MVC pattern</dt> |
| |
| |
| <dd> |
| <p>MVC stands for Model View Controller. It's a design pattern |
| started his life in the 70's as a framework developer by Trygve |
| Reenskaug for Smalltalk, and was used primary for for UI-s (user |
| interfaces). MVC considers three roles:</p> |
| |
| <ul> |
| <li> |
| Model: Model represents application (domain) specific |
| information in a non-visual way. For example, an array of product |
| objects in the memory of your computer is the part of the |
| model. |
| </li> |
| |
| <li> |
| View: View displays the model and provides UI. For example, |
| it's the task of the view component to render the array of product |
| objects to a HTML page. |
| </li> |
| |
| <li> |
| Controller: The controller handles user input, modifies the |
| model, and ensures that the view is updated when needed. For |
| example it is the task of controller to take the incoming HTTP |
| requests, parse the received parameters (forms), dispatch the |
| requests to the proper business logic object, and chose the right |
| template for the HTTP response. |
| </li> |
| </ul> |
| |
| <p>The most important thing for us when applying MVC for Web |
| applications is the separation of View from the other two roles. This |
| allows the separation of designers (HTML authors) from programmers. |
| Designers deal with the visual aspects, programmers deal with the |
| application logic and other technical issues; everybody works on what |
| he is good at. Designers and programmers are less dependent on each |
| other. Designers can change the appearance without programmers having |
| to change or recompile the program.</p> |
| |
| <p>For more information I recommend reading <a href="http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/web-tier/web-tier5.html">chapter |
| 4.4</a> of Designing Enterprise Applications with the J2EE Platform |
| blueprint.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.outputEncoding"></a>Output encoding</dt> |
| |
| |
| <dd> |
| <p>Means output <a href="#gloss.charset">charset</a>. In |
| the Java world the term ``encoding'' is commonly (mis)used as a |
| synonym to ``charset''.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.predefinedDirective"></a>Predefined directive</dt> |
| |
| |
| <dd> |
| <p>Directive what is defined by FreeMarker, thus always available. |
| Example of predefined directives: <code class="inline-code">if</code>, |
| <code class="inline-code">list</code>, <code class="inline-code">include</code></p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.userDefinedDirective">User-defined directive</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.regularExpression"></a>Regular expression</dt> |
| |
| |
| <dd> |
| <p>A regular expression is a string that specifies a set of strings |
| that matches it. For example, the regular expression |
| <code class="inline-code">"fo*"</code> matches <code class="inline-code">"f"</code>, |
| <code class="inline-code">"fo"</code>, <code class="inline-code">"foo"</code>, etc. Regular |
| expressions are used in several languages and other tools. In |
| FreeMarker, the usage of them is a ``power user'' option. So if you |
| have never used them before, there is no need to worry about not being |
| familiar with them. But if you are interested in regular expressions, |
| you can find several Web pages and books about them. FreeMarker uses |
| the variation of regular expressions described at: <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html</a></p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.scalarVariable"></a>Scalar</dt> |
| |
| |
| <dd> |
| <p>A scalar variable stores a single value. A scalar is either a |
| string or a number or a date/time or a <a href="#gloss.boolean">boolean</a>.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.sequenceVariable"></a>Sequence</dt> |
| |
| |
| <dd> |
| <p>A sequence is a variable that contains a sequence of |
| subvariables. The sequence's subvariables are accessible via numerical |
| index, where the index of the very first object is 0, the index of the |
| second objects is 1, the index of the third object is 2, etc.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.hashVariable">Hash</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="autoid_242"></a>SGML</dt> |
| |
| |
| <dd>See |
| <a href="#gloss.SGML">Standard Generalized Markup Language</a> |
| </dd> |
| |
| |
| <dt><a name="gloss.SGML"></a>Standard Generalized Markup Language</dt> |
| |
| |
| <dd> |
| <p>This is an international standard (ISO 8879) that specifies the |
| rules for the creation of platform-independent markup languages. HTML |
| is a markup language created with SGML. <a href="#gloss.XML">XML</a> is a subset (restricted version) of |
| SGML.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.XML">Extensible Markup Language</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.startTag"></a>Start-tag</dt> |
| |
| |
| <dd> |
| <p><a href="#gloss.tag">Tag</a>, which indicates that the |
| following content is under the element, up to the <a href="#gloss.endTag">end-tag</a>. The start-tag may also |
| specifies <a href="#gloss.attribute">attributes</a> for the |
| element. An example of a start-tag: <code class="inline-code"><body |
| bgcolor=black></code></p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.string"></a>String</dt> |
| |
| |
| <dd> |
| <p>A sequence of <a href="#gloss.character">characters</a> |
| such as ``m'', ``o'', ``u'', ``s'', ``e''.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.tag"></a>Tag</dt> |
| |
| |
| <dd> |
| <p>Text fragment indicating the usage of an element in SGML. |
| Examples of tags: <code class="inline-code"><body bgcolor=black></code>, |
| <code class="inline-code"></body></code></p> |
| |
| |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.startTag">Start-tag</a>, |
| <a href="#gloss.endTag">End-tag</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.template"></a>Template</dt> |
| |
| |
| <dd> |
| <p>A template is a text file with some special character sequences |
| embedded into it. A template processor (e.g. FreeMarker) will |
| interpret special character sequences and it outputs a more or less |
| different text from the original text file, where the differences are |
| often based on a <a href="#gloss.dataModel">data-model</a>. |
| Thus, the original text acts as a template of the possible |
| outputs.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.templateEncoding"></a>Template encoding</dt> |
| |
| |
| <dd> |
| <p>Means template <a href="#gloss.charset">charset</a>. In |
| the Java world the term ``encoding'' is commonly (mis)used as a |
| synonym to ``charset''.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.templateProcessingJob"></a>Template processing job</dt> |
| |
| |
| <dd> |
| <p>A template processing job is the act when FreeMarker merges a |
| template with a data-model to produce the output for a visitor. Note |
| that this may includes the execution of multiple template files |
| because the template file used for the Web page may invokes other |
| templates with <code class="inline-code">include</code> and |
| <code class="inline-code">import</code> directives. Each template-processing job is |
| a separated cosmos that exists only for the short period of time while |
| the given page is being rendered for the visitor, and then it vanishes |
| with all the variables created in the templates (for example, |
| variables created with <code class="inline-code">assign</code>, |
| <code class="inline-code">macro</code> or <code class="inline-code">global</code> |
| directives).</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.threadSafe"></a>Thread-safe</dt> |
| |
| |
| <dd> |
| <p>An object is thread-safe if it is safe to call its methods from |
| multiple threads, even in parallel (i.e. multiple threads execute the |
| methods of the object at the same time). Non-thread-safe objects may |
| behave unpredictably in this situation, and generate wrong results, |
| corrupt internal data structures, etc. Thread-safety is typically |
| achieved in two ways with Java: with the usage |
| <code class="inline-code">synchronized</code> statement (or |
| <code class="inline-code">synchronized</code> methods), and with the immutability of |
| encapsulated data (i.e. you can't modify the field after you have |
| created the object).</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.transformVariable"></a>Transform</dt> |
| |
| |
| <dd> |
| <p>This term refers to user-defined directives that are implemetned |
| with the now obsolete <code class="inline-code">TemplateTransformModel</code> Java |
| interface. The feature was originally made for implementing output |
| filters, hence the name.</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.UCS"></a>UCS</dt> |
| |
| |
| <dd> |
| <p>This is international standard (ISO-10646) that defines a huge |
| set of <a href="#gloss.character">characters</a> and assigns a |
| unique number for each character (``!'' is 33, ..., ``A'' is 61, ``B'' |
| is 62, ..., Arabic letter hamza is 1569... etc.). This character set |
| (not charset) contains almost all characters used today (Latin |
| alphabet, Cyrillic alphabet, Chinese letters, etc.). The idea behind |
| UCS is that we can specify any character with a unique number, not |
| mater what the platform or the language is.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.unicode">Unicode</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.unicode"></a>Unicode</dt> |
| |
| |
| <dd> |
| <p>De-facto standard developed by Unicode organization. It deals |
| with the classification of the characters in <a href="#gloss.UCS">UCS</a> (which is letter, which is digit, which |
| is uppercase, which is lowercase, etc.), and with other problems of |
| processing text made from the characters of UCS (e.g. |
| normalization).</p> |
| |
| </dd> |
| |
| |
| <dt><a name="gloss.userDefinedDirective"></a>User-defined directive</dt> |
| |
| |
| <dd> |
| <p>Directive that is not defined by the FreeMarker core, but by the |
| user. These are typically application domain specific directives, like |
| pull-down menu generation directives, HTML form handling |
| directives.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.predefinedDirective">Predefined directive</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="gloss.whiteSpace"></a>White-space</dt> |
| |
| |
| <dd> |
| <p>Characters that are totally transparent but have impact on the |
| visual appearance of the text. Examples of white-space characters: |
| space, tab (horizontal and vertical), line breaks (CR and LF), form |
| feed.</p> |
| |
| |
| |
| <p>See Also |
| <a href="#gloss.lineBreak">Line break</a> |
| </p> |
| </dd> |
| |
| |
| <dt><a name="autoid_243"></a>XML</dt> |
| |
| |
| <dd>See |
| <a href="#gloss.XML">Extensible Markup Language</a> |
| </dd> |
| |
| </dl> |
| |
| <p> |
| <a href="#idx_x24">$</a> | <a href="#idx_x23">#</a> | <a href="#idx_x3C"><</a> | <a href="#idx_A">A</a> | <a href="#idx_B">B</a> | <a href="#idx_C">C</a> | <a href="#idx_D">D</a> | <a href="#idx_E">E</a> | <a href="#idx_F">F</a> | <a href="#idx_G">G</a> | <a href="#idx_H">H</a> | <a href="#idx_I">I</a> | <a href="#idx_J">J</a> | <a href="#idx_K">K</a> | <a href="#idx_L">L</a> | <a href="#idx_M">M</a> | <a href="#idx_N">N</a> | <a href="#idx_O">O</a> | <a href="#idx_P">P</a> | <a href="#idx_R">R</a> | <a href="#idx_S">S</a> | <a href="#idx_T">T</a> | <a href="#idx_U">U</a> | <a href="#idx_V">V</a> | <a href="#idx_W">W</a> | <a href="#idx_X">X</a> </p> |
| |
| <div class="indexdiv"> |
| <a name="idx_x24"></a> |
| <h2 class="indexLabel">$</h2> |
| <dl> |
| <dt> |
| ${...}, <a href="#dgui_template_valueinsertion">Interpolations</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_x23"></a> |
| <h2 class="indexLabel">#</h2> |
| <dl> |
| <dt> |
| #, <a href="#dgui_template_overallstructure">Overall structure</a>, |
| <a href="#dgui_template_directives">Directives</a> |
| </dt> |
| <dt> |
| #{...}, <a href="#ref_depr_numerical_interpolation">#{...}: Numerical interpolation</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_x3C"></a> |
| <h2 class="indexLabel"><</h2> |
| <dl> |
| <dt> |
| <#...>, <a href="#dgui_template_directives">Directives</a> |
| </dt> |
| <dt> |
| <#--...-->, <a href="#dgui_template_overallstructure">Overall structure</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_A"></a> |
| <h2 class="indexLabel">A</h2> |
| <dl> |
| <dt> |
| acquisition, <a href="#ref_directive_include_acquisition">Using acquisition</a> |
| </dt> |
| <dt> |
| adding hashes, <a href="#dgui_template_exp_hashop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| adding sequences, <a href="#dgui_template_exp_sequenceop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| adding strings, <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a> |
| </dt> |
| <dt> |
| addition, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| alternative syntax, <a href="#dgui_misc_alternativesyntax">Alternative (square bracket) syntax</a> |
| </dt> |
| <dt> |
| ancestors built-in, <a href="#ref_builtin_ancestors">ancestors</a> |
| </dt> |
| <dt> |
| and, <a href="#dgui_template_exp_logicalop">Logical operations</a> |
| </dt> |
| <dt> |
| ant task, <a href="#pgui_misc_ant">Using FreeMarker with Ant</a> |
| </dt> |
| <dt> |
| arithmetic, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| assign directive, <a href="#ref_directive_assign">assign</a> |
| </dt> |
| <dt> |
| attempt directive, <a href="#ref_directive_attempt">attempt, recover</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_B"></a> |
| <h2 class="indexLabel">B</h2> |
| <dl> |
| <dt> |
| beans </dt> |
| <dd><dl> |
| <dt>wrapping, <a href="#pgui_misc_beanwrapper">Bean wrapper</a></dt> |
| </dl></dd> |
| <dt> |
| boolean </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_boolean">Built-ins for booleans</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| <dt>literal, <a href="#dgui_template_exp_direct_boolean">Booleans</a></dt> |
| <dt>operations, <a href="#dgui_template_exp_logicalop">Logical operations</a></dt> |
| <dt>printing, <a href="#ref_builtin_string_for_boolean">string (when used with a boolean value)</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| boolean_format, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| break directive, <a href="#ref_directive_switch">switch, case, default, break</a>, |
| <a href="#ref_directive_list">list, break</a> |
| </dt> |
| <dt> |
| build, <a href="#app_build">Building FreeMarker</a> |
| </dt> |
| <dt> |
| built-in, <a href="#dgui_template_exp_builtin">Built-ins</a>, |
| <a href="#ref_builtins">Built-in Reference</a> |
| </dt> |
| <dt> |
| byte built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_C"></a> |
| <h2 class="indexLabel">C</h2> |
| <dl> |
| <dt> |
| caching, <a href="#pgui_config_templateloading_caching">Template caching</a> |
| </dt> |
| <dt> |
| call a method, <a href="#dgui_template_exp_methodcall">Method call</a> |
| </dt> |
| <dt> |
| cap_first built-in, <a href="#ref_builtin_cap_first">cap_first</a> |
| </dt> |
| <dt> |
| capitalize built-in, <a href="#ref_builtin_capitalize">capitalize</a> |
| </dt> |
| <dt> |
| case directive, <a href="#ref_directive_switch">switch, case, default, break</a> |
| </dt> |
| <dt> |
| ceiling built-in, <a href="#ref_builtin_rounding">round, floor, ceiling</a> |
| </dt> |
| <dt> |
| charAt, <a href="#dgui_template_exp_get_character">Getting a character</a> |
| </dt> |
| <dt> |
| charset, <a href="#pgui_misc_charset">Charset issues</a>, |
| <a href="#ref_directive_ftl">ftl</a> |
| </dt> |
| <dt> |
| children built-in, <a href="#ref_builtin_children">children</a> |
| </dt> |
| <dt> |
| chop_linebreak built-in, <a href="#ref_builtin_chop_linebreak">chop_linebreak</a> |
| </dt> |
| <dt> |
| chunk built-in, <a href="#ref_builtin_chunk">chunk</a> |
| </dt> |
| <dt> |
| classic_compatible, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| collection </dt> |
| <dd><dl> |
| <dt>Java side, <a href="#autoid_34">Containers</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_container">Containers</a></dt> |
| </dl></dd> |
| <dt> |
| columnar printing of sequences, <a href="#ref_builtin_chunk">chunk</a> |
| </dt> |
| <dt> |
| command-line, <a href="#pgui_misc_ant">Using FreeMarker with Ant</a> |
| </dt> |
| <dt> |
| comment, <a href="#dgui_template_overallstructure">Overall structure</a> |
| </dt> |
| <dt> |
| comparison operators, <a href="#dgui_template_exp_comparison">Comparison</a> |
| </dt> |
| <dt> |
| compress directive, <a href="#ref_directive_compress">compress</a> |
| </dt> |
| <dt> |
| concatenate hashes, <a href="#dgui_template_exp_hashop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| concatenate sequences, <a href="#dgui_template_exp_sequenceop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| concatenate strings, <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a> |
| </dt> |
| <dt> |
| configuration, <a href="#pgui_quickstart_createconfiguration">Create a configuration instance</a> |
| </dt> |
| <dt> |
| Configuration, <a href="#pgui_config">The Configuration</a> |
| </dt> |
| <dt> |
| constant, <a href="#dgui_template_exp_direct">Specify values directly</a> |
| </dt> |
| <dt> |
| contact, <a href="#autoid_5">Preface</a> |
| </dt> |
| <dt> |
| containers </dt> |
| <dd><dl> |
| <dt>Java side, <a href="#pgui_datamodel_parent">Containers</a></dt> |
| </dl></dd> |
| <dt> |
| contains built-in, <a href="#ref_builtin_contains">contains</a> |
| </dt> |
| <dt> |
| converting between types, <a href="#ref_builtin_string_date">date, time, datetime</a>, |
| <a href="#ref_builtin_number">number</a>, |
| <a href="#ref_builtin_c">c</a>, |
| <a href="#ref_builtin_string_for_number">string (when used with a numerical value)</a>, |
| <a href="#ref_builtin_string_for_date">string (when used with a date value)</a>, |
| <a href="#ref_builtin_date_datetype">date, time, datetime</a>, |
| <a href="#ref_builtin_string_for_boolean">string (when used with a boolean value)</a>, |
| <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| custom directive, <a href="#dgui_misc_userdefdir">Defining your own directives</a> |
| </dt> |
| <dt> |
| custom tags, <a href="#autoid_55">Using FreeMarker with servlets</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_D"></a> |
| <h2 class="indexLabel">D</h2> |
| <dl> |
| <dt> |
| data-model, <a href="#dgui_quickstart_basics">Template + data-model = output</a> |
| </dt> |
| <dd><dl> |
| <dt>assembling with Java, <a href="#pgui_quickstart_createdatamodel">Create a data-model</a></dt> |
| <dt>assembling with Java, without object wrapper, <a href="#pgui_datamodel_basics">Basics</a></dt> |
| </dl></dd> |
| <dt> |
| date </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_date">Built-ins for dates</a></dt> |
| <dt>Java API related difficulties, <a href="#autoid_31">Scalars</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| date_format, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| date built-in, <a href="#ref_builtin_string_date">date, time, datetime</a>, |
| <a href="#ref_builtin_date_datetype">date, time, datetime</a> |
| </dt> |
| <dt> |
| date-time </dt> |
| <dd><dl> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| datetime_format, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| datetime built-in, <a href="#ref_builtin_string_date">date, time, datetime</a>, |
| <a href="#ref_builtin_date_datetype">date, time, datetime</a> |
| </dt> |
| <dt> |
| default built-in, <a href="#ref_depr_builtin">List of deprecated built-ins</a> |
| </dt> |
| <dt> |
| default directive, <a href="#ref_directive_switch">switch, case, default, break</a> |
| </dt> |
| <dt> |
| default value operator, <a href="#dgui_template_exp_missing_default">Default value operator</a> |
| </dt> |
| <dt> |
| defining macro, <a href="#autoid_21">Defining your own directives</a> |
| </dt> |
| <dt> |
| deprecated, <a href="#ref_deprecated">Deprecated FTL constructs</a> |
| </dt> |
| <dt> |
| directive, <a href="#dgui_template_directives">Directives</a>, |
| <a href="#ref_directives">Directive Reference</a> |
| </dt> |
| <dd><dl> |
| <dt>the FTL value type, <a href="#dgui_datamodel_userdefdir">User-defined directives</a></dt> |
| <dt>user-defined, <a href="#dgui_misc_userdefdir">Defining your own directives</a></dt> |
| </dl></dd> |
| <dt> |
| directives </dt> |
| <dd><dl> |
| <dt>Java side, <a href="#pgui_datamodel_directive">Directives</a></dt> |
| </dl></dd> |
| <dt> |
| division, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| double built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| download, <a href="#autoid_5">Preface</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_E"></a> |
| <h2 class="indexLabel">E</h2> |
| <dl> |
| <dt> |
| else directive, <a href="#ref_directive_if">if, else, elseif</a> |
| </dt> |
| <dt> |
| elseif directive, <a href="#ref_directive_if">if, else, elseif</a> |
| </dt> |
| <dt> |
| encoding, <a href="#pgui_misc_charset">Charset issues</a>, |
| <a href="#ref_directive_ftl">ftl</a> |
| </dt> |
| <dd><dl> |
| <dt>URL, <a href="#ref_builtin_url">url</a></dt> |
| </dl></dd> |
| <dt> |
| ends_with built-in, <a href="#ref_builtin_ends_with">ends_with</a> |
| </dt> |
| <dt> |
| error, <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| error handling, <a href="#dgui_template_exp_missing">Handling missing values</a>, |
| <a href="#pgui_config_errorhandling">Error handling</a>, |
| <a href="#ref_directive_attempt">attempt, recover</a> |
| </dt> |
| <dt> |
| escape directive, <a href="#ref_directive_escape">escape, noescape</a> |
| </dt> |
| <dt> |
| escape sequences, <a href="#dgui_template_exp_direct_string">Strings</a> |
| </dt> |
| <dt> |
| escaping </dt> |
| <dd><dl> |
| <dt>output, <a href="#ref_builtin_html">html</a>, <a href="#ref_builtin_rtf">rtf</a>, <a href="#ref_builtin_xhtml">xhtml</a>, <a href="#ref_builtin_xml">xml</a></dt> |
| <dt>URL, <a href="#ref_builtin_url">url</a></dt> |
| </dl></dd> |
| <dt> |
| eval, <a href="#ref_builtin_eval">eval</a> |
| </dt> |
| <dt> |
| evaluate string, <a href="#ref_builtin_eval">eval</a> |
| </dt> |
| <dt> |
| exception handling, <a href="#pgui_config_errorhandling">Error handling</a> |
| </dt> |
| <dt> |
| existence test operator, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| <dt> |
| exists built-in, <a href="#ref_depr_builtin">List of deprecated built-ins</a> |
| </dt> |
| <dt> |
| expression, <a href="#dgui_template_exp">Expressions</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_F"></a> |
| <h2 class="indexLabel">F</h2> |
| <dl> |
| <dt> |
| fallback directive, <a href="#ref_directive_visit">visit, recurse, fallback</a> |
| </dt> |
| <dt> |
| FAQ, <a href="#app_faq">FAQ</a> |
| </dt> |
| <dt> |
| first built-in, <a href="#ref_builtin_first">first</a> |
| </dt> |
| <dt> |
| float built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| floor built-in, <a href="#ref_builtin_rounding">round, floor, ceiling</a> |
| </dt> |
| <dt> |
| flush directive, <a href="#ref_directive_flush">flush</a> |
| </dt> |
| <dt> |
| format </dt> |
| <dd><dl> |
| <dt>boolean, <a href="#ref_builtin_string_for_boolean">string (when used with a boolean value)</a>, <a href="#autoid_101">setting</a></dt> |
| <dt>date, <a href="#ref_builtin_string_for_date">string (when used with a date value)</a>, <a href="#autoid_101">setting</a></dt> |
| <dt>number, <a href="#ref_builtin_c">c</a>, <a href="#ref_builtin_string_for_number">string (when used with a numerical value)</a>, <a href="#ref.setting.number_format">setting</a></dt> |
| </dl></dd> |
| <dt> |
| FTL, <a href="#dgui_template_overallstructure">Overall structure</a> |
| </dt> |
| <dt> |
| ftl directive, <a href="#ref_directive_ftl">ftl</a> |
| </dt> |
| <dt> |
| FTL tag, <a href="#dgui_template_overallstructure">Overall structure</a>, |
| <a href="#dgui_template_directives">Directives</a> |
| </dt> |
| <dt> |
| function directive, <a href="#ref_directive_function">function, return</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_G"></a> |
| <h2 class="indexLabel">G</h2> |
| <dl> |
| <dt> |
| get character, <a href="#dgui_template_exp_get_character">Getting a character</a> |
| </dt> |
| <dt> |
| global directive, <a href="#ref_directive_global">global</a> |
| </dt> |
| <dt> |
| groups built-in, <a href="#ref_builtin_groups">groups</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_H"></a> |
| <h2 class="indexLabel">H</h2> |
| <dl> |
| <dt> |
| handling null-s, <a href="#dgui_template_exp_missing">Handling missing values</a> |
| </dt> |
| <dt> |
| has_content built-in, <a href="#ref_builtin_has_content">has_content</a> |
| </dt> |
| <dt> |
| hash </dt> |
| <dd><dl> |
| <dt>accessing subvariable, <a href="#dgui_template_exp_var_hash">Retrieving data from a hash</a></dt> |
| <dt>built-ins, <a href="#ref_builtins_hash">Built-ins for hashes</a></dt> |
| <dt>concatenate, <a href="#dgui_template_exp_hashop_cat">Concatenation</a></dt> |
| <dt>Java side, <a href="#autoid_32">Containers</a></dt> |
| <dt>key type, <a href="#app_faq">FAQ</a></dt> |
| <dt>literal, <a href="#dgui_template_exp_direct_hash">Hashes</a></dt> |
| <dt>modify, <a href="#faq_modify_seq_and_map">FAQ</a></dt> |
| <dt>operations, <a href="#dgui_template_exp_hashop">Hash operations</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_container">Containers</a></dt> |
| </dl></dd> |
| <dt> |
| header, <a href="#ref_directive_ftl">ftl</a> |
| </dt> |
| <dt> |
| help, <a href="#autoid_5">Preface</a> |
| </dt> |
| <dt> |
| homepage, <a href="#autoid_5">Preface</a> |
| </dt> |
| <dt> |
| html built-in, <a href="#ref_builtin_html">html</a> |
| </dt> |
| <dt> |
| HTTP, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_I"></a> |
| <h2 class="indexLabel">I</h2> |
| <dl> |
| <dt> |
| if_exists built-in, <a href="#ref_depr_builtin">List of deprecated built-ins</a> |
| </dt> |
| <dt> |
| if directive, <a href="#ref_directive_if">if, else, elseif</a> |
| </dt> |
| <dt> |
| import directive, <a href="#ref_directive_import">import</a> |
| </dt> |
| <dt> |
| include </dt> |
| <dd><dl> |
| <dt>JSP, <a href="#pgui_misc_servlet_include">Including content from other web application |
| resources</a></dt> |
| <dt>servlet, <a href="#pgui_misc_servlet_include">Including content from other web application |
| resources</a></dt> |
| </dl></dd> |
| <dt> |
| include directive, <a href="#ref_directive_include">include</a> |
| </dt> |
| <dt> |
| index_of built-in, <a href="#ref_builtin_index_of">index_of</a> |
| </dt> |
| <dt> |
| install, <a href="#app_install">Installing FreeMarker</a> |
| </dt> |
| <dt> |
| instantiating variable, <a href="#ref_builtin_new">new</a> |
| </dt> |
| <dt> |
| int built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| integer division, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| integer part, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| interpolation, <a href="#dgui_template_overallstructure">Overall structure</a>, |
| <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a>, |
| <a href="#dgui_template_valueinsertion">Interpolations</a> |
| </dt> |
| <dt> |
| interpret built-in, <a href="#ref_builtin_interpret">interpret</a> |
| </dt> |
| <dt> |
| is_... built-in, <a href="#ref_builtin_isType">is_...</a> |
| </dt> |
| <dt> |
| is null, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_J"></a> |
| <h2 class="indexLabel">J</h2> |
| <dl> |
| <dt> |
| j_string built-in, <a href="#ref_builtin_j_string">j_string</a> |
| </dt> |
| <dt> |
| joining hashes, <a href="#dgui_template_exp_hashop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| joining sequences, <a href="#dgui_template_exp_sequenceop_cat">Concatenation</a> |
| </dt> |
| <dt> |
| joining strings, <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a> |
| </dt> |
| <dt> |
| js_string built-in, <a href="#ref_builtin_js_string">js_string</a> |
| </dt> |
| <dt> |
| JSP, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a>, |
| <a href="#faq_jsp_vs_freemarker">FAQ</a> |
| </dt> |
| <dd><dl> |
| <dt>include, <a href="#pgui_misc_servlet_include">Including content from other web application |
| resources</a></dt> |
| <dt>taglib, <a href="#autoid_55">Using FreeMarker with servlets</a>, <a href="#autoid_56">Using FreeMarker with servlets</a></dt> |
| </dl></dd> |
| <dt> |
| jython </dt> |
| <dd><dl> |
| <dt>wrapping, <a href="#pgui_misc_jythonwrapper">Jython wrapper</a></dt> |
| </dl></dd> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_K"></a> |
| <h2 class="indexLabel">K</h2> |
| <dl> |
| <dt> |
| keys built-in, <a href="#ref_builtin_keys">keys</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_L"></a> |
| <h2 class="indexLabel">L</h2> |
| <dl> |
| <dt> |
| language, <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| last_index_of built-in, <a href="#ref_builtin_last_index_of">last_index_of</a> |
| </dt> |
| <dt> |
| last built-in, <a href="#ref_builtin_last">last</a> |
| </dt> |
| <dt> |
| left_pad built-in, <a href="#ref_builtin_left_pad">left_pad</a> |
| </dt> |
| <dt> |
| length built-in, <a href="#ref_builtin_length">length</a> |
| </dt> |
| <dt> |
| libraries, <a href="#dgui_misc_namespace">Namespaces</a> |
| </dt> |
| <dt> |
| library path, <a href="#autoid_29">Namespaces</a> |
| </dt> |
| <dt> |
| license, <a href="#app_license">License</a> |
| </dt> |
| <dt> |
| list directive, <a href="#ref_directive_list">list, break</a> |
| </dt> |
| <dt> |
| literal, <a href="#dgui_template_exp_direct">Specify values directly</a> |
| </dt> |
| <dd><dl> |
| <dt>boolean, <a href="#dgui_template_exp_direct_boolean">Booleans</a></dt> |
| <dt>hash, <a href="#dgui_template_exp_direct_hash">Hashes</a></dt> |
| </dl></dd> |
| <dt> |
| loading templates, <a href="#pgui_config_templateloading">Template loading</a> |
| </dt> |
| <dt> |
| local directive, <a href="#ref_directive_local">local</a> |
| </dt> |
| <dt> |
| locale, <a href="#autoid_101">setting</a>, |
| <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| localization, <a href="#ref_directive_include_localized">Localized lookup</a> |
| </dt> |
| <dt> |
| local variable, <a href="#dgui_misc_var">Defining variables in the template</a> |
| </dt> |
| <dt> |
| logging, <a href="#pgui_misc_logging">Logging</a> |
| </dt> |
| <dt> |
| logical operations, <a href="#dgui_template_exp_logicalop">Logical operations</a> |
| </dt> |
| <dt> |
| long built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| loop variable, <a href="#dgui_misc_userdefdir_loopvar">Macros with loop variables</a>, |
| <a href="#dgui_misc_var">Defining variables in the template</a> |
| </dt> |
| <dt> |
| lower_case built-in, <a href="#ref_builtin_lower_case">lower_case</a> |
| </dt> |
| <dt> |
| lt directive, <a href="#ref_directive_t">t, lt, rt</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_M"></a> |
| <h2 class="indexLabel">M</h2> |
| <dl> |
| <dt> |
| macro, <a href="#dgui_misc_userdefdir">Defining your own directives</a> |
| </dt> |
| <dd><dl> |
| <dt>the FTL value type, <a href="#dgui_datamodel_userdefdir">User-defined directives</a></dt> |
| </dl></dd> |
| <dt> |
| macro directive, <a href="#ref_directive_macro">macro, nested, return</a> |
| </dt> |
| <dt> |
| matches built-in, <a href="#ref_builtin_matches">matches</a> |
| </dt> |
| <dt> |
| math, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| merging, <a href="#pgui_quickstart_merge">Merging the template with the data-model</a> |
| </dt> |
| <dt> |
| method </dt> |
| <dd><dl> |
| <dt>call, <a href="#dgui_template_exp_methodcall">Method call</a></dt> |
| <dt>defining with FTL, <a href="#ref_directive_function">function, return</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_method">Methods</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_method">Methods and functions</a></dt> |
| </dl></dd> |
| <dt> |
| missing value test operator, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| <dt> |
| missing variable, <a href="#dgui_template_exp_missing">Handling missing values</a> |
| </dt> |
| <dt> |
| Model 2, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a> |
| </dt> |
| <dt> |
| modify hashes, <a href="#faq_modify_seq_and_map">FAQ</a> |
| </dt> |
| <dt> |
| modify sequences, <a href="#faq_modify_seq_and_map">FAQ</a> |
| </dt> |
| <dt> |
| modulus, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| multithreading, <a href="#pgui_misc_multithreading">Multithreading</a> |
| </dt> |
| <dt> |
| Multi-typed value, <a href="#topic.multitype">Basics</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_N"></a> |
| <h2 class="indexLabel">N</h2> |
| <dl> |
| <dt> |
| namespace built-in, <a href="#ref_builtin_namespace">namespace</a> |
| </dt> |
| <dt> |
| namespaces, <a href="#dgui_misc_namespace">Namespaces</a> |
| </dt> |
| <dt> |
| nested directive, <a href="#ref_directive_macro">macro, nested, return</a> |
| </dt> |
| <dt> |
| new built-in, <a href="#ref_builtin_new">new</a> |
| </dt> |
| <dt> |
| new FTL syntax, <a href="#ref_depr_oldsyntax">Old FTL syntax</a> |
| </dt> |
| <dt> |
| node </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_node">Built-ins for nodes (for XML)</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_node">Node variables</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_node">Nodes</a></dt> |
| </dl></dd> |
| <dt> |
| node_name built-in, <a href="#ref_builtin_node_name">node_name</a> |
| </dt> |
| <dt> |
| node_namespace built-in, <a href="#ref_builtin_node_namespace">node_namespace</a> |
| </dt> |
| <dt> |
| node_type built-in, <a href="#ref_builtin_node_type">node_type</a> |
| </dt> |
| <dt> |
| noescape directive, <a href="#ref_directive_escape">escape, noescape</a> |
| </dt> |
| <dt> |
| noparse directive, <a href="#ref_directive_noparse">noparse</a> |
| </dt> |
| <dt> |
| not, <a href="#dgui_template_exp_logicalop">Logical operations</a> |
| </dt> |
| <dt> |
| nt directive, <a href="#ref_directive_nt">nt</a> |
| </dt> |
| <dt> |
| null, <a href="#dgui_template_exp_missing">Handling missing values</a>, |
| <a href="#faq_null">FAQ</a> |
| </dt> |
| <dt> |
| number </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_number">Built-ins for numbers</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| <dt>literal, <a href="#dgui_template_exp_direct_number">Numbers</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| number_format, <a href="#ref.setting.number_format">setting</a> |
| </dt> |
| <dt> |
| number built-in, <a href="#ref_builtin_number">number</a> |
| </dt> |
| <dt> |
| numerical range expression, <a href="#dgui_template_exp_direct_seuqence">Sequences</a> |
| </dt> |
| <dt> |
| numerical sequence, <a href="#dgui_template_exp_direct_seuqence">Sequences</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_O"></a> |
| <h2 class="indexLabel">O</h2> |
| <dl> |
| <dt> |
| object wrapper, <a href="#pgui_datamodel_basics">Basics</a>, |
| <a href="#pgui_datamodel_objectWrapper">Object wrappers</a> |
| </dt> |
| <dt> |
| old FTL syntax, <a href="#ref_depr_oldsyntax">Old FTL syntax</a> |
| </dt> |
| <dt> |
| operator precedence, <a href="#dgui_template_exp_precedence">Operator precedence</a> |
| </dt> |
| <dt> |
| or, <a href="#dgui_template_exp_logicalop">Logical operations</a> |
| </dt> |
| <dt> |
| output </dt> |
| <dd><dl> |
| <dt>generate with Java, <a href="#pgui_quickstart_merge">Merging the template with the data-model</a></dt> |
| </dl></dd> |
| <dt> |
| output charset, <a href="#autoid_47">Charset issues</a>, |
| <a href="#ref_builtin_url">url</a>, |
| <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| output encoding, <a href="#autoid_47">Charset issues</a>, |
| <a href="#ref_builtin_url">url</a>, |
| <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_P"></a> |
| <h2 class="indexLabel">P</h2> |
| <dl> |
| <dt> |
| padding, <a href="#ref_builtin_left_pad">left_pad</a>, |
| <a href="#ref_builtin_right_pad">right_pad</a> |
| </dt> |
| <dt> |
| parent built-in, <a href="#ref_builtin_parent">parent</a> |
| </dt> |
| <dt> |
| parentheses, <a href="#dgui_template_exp_parentheses">Parentheses</a> |
| </dt> |
| <dt> |
| path, <a href="#autoid_42">Template loading</a> |
| </dt> |
| <dt> |
| positional parameter passing, <a href="#ref_directive_userDefined_positionalParam">Positional parameter passing</a> |
| </dt> |
| <dt> |
| precedence, <a href="#dgui_template_exp_precedence">Operator precedence</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_R"></a> |
| <h2 class="indexLabel">R</h2> |
| <dl> |
| <dt> |
| range expression, <a href="#dgui_template_exp_direct_seuqence">Sequences</a> |
| </dt> |
| <dt> |
| raw string literal, <a href="#dgui_template_exp_direct_string">Strings</a> |
| </dt> |
| <dt> |
| recover directive, <a href="#ref_directive_attempt">attempt, recover</a> |
| </dt> |
| <dt> |
| recurse directive, <a href="#ref_directive_visit">visit, recurse, fallback</a> |
| </dt> |
| <dt> |
| recursion </dt> |
| <dd><dl> |
| <dt>iterate, <a href="#ref_directive_visit">visit, recurse, fallback</a></dt> |
| </dl></dd> |
| <dt> |
| regular expression </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtin_string_flags">Common flags</a></dt> |
| </dl></dd> |
| <dt> |
| replace built-in, <a href="#ref_builtin_replace">replace</a> |
| </dt> |
| <dt> |
| reserved name, <a href="#ref_reservednames">Reserved names in FTL</a> |
| </dt> |
| <dt> |
| return directive, <a href="#ref_directive_macro">macro, nested, return</a>, |
| <a href="#ref_directive_function">function, return</a> |
| </dt> |
| <dt> |
| reverse built-in, <a href="#ref_builtin_reverse">reverse</a> |
| </dt> |
| <dt> |
| right_pad built-in, <a href="#ref_builtin_right_pad">right_pad</a> |
| </dt> |
| <dt> |
| root built-in, <a href="#ref_builtin_root">root</a> |
| </dt> |
| <dt> |
| round built-in, <a href="#ref_builtin_rounding">round, floor, ceiling</a> |
| </dt> |
| <dt> |
| rounding, <a href="#ref_builtin_rounding">round, floor, ceiling</a> |
| </dt> |
| <dt> |
| rt directive, <a href="#ref_directive_t">t, lt, rt</a> |
| </dt> |
| <dt> |
| rtf built-in, <a href="#ref_builtin_rtf">rtf</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_S"></a> |
| <h2 class="indexLabel">S</h2> |
| <dl> |
| <dt> |
| scalar </dt> |
| <dd><dl> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| security, <a href="#pgui_misc_secureenv">Configuring security policy for FreeMarker</a> |
| </dt> |
| <dt> |
| seq_contains built-in, <a href="#ref_builtin_seq_contains">seq_contains</a> |
| </dt> |
| <dt> |
| seq_index_of built-in, <a href="#ref_builtin_seq_index_of">seq_index_of</a> |
| </dt> |
| <dt> |
| seq_last_index_of built-in, <a href="#ref_builtin_seq_last_index_of">seq_last_index_of</a> |
| </dt> |
| <dt> |
| sequence </dt> |
| <dd><dl> |
| <dt>accessing subvariable, <a href="#dgui_template_exp_var_sequence">Retrieving data from a sequence</a></dt> |
| <dt>built-ins, <a href="#ref_builtins_sequence">Built-ins for sequences</a></dt> |
| <dt>concatenate, <a href="#dgui_template_exp_sequenceop_cat">Concatenation</a></dt> |
| <dt>iterate, <a href="#ref_directive_list">list, break</a></dt> |
| <dt>Java side, <a href="#autoid_33">Containers</a></dt> |
| <dt>literal, <a href="#dgui_template_exp_direct_seuqence">Sequences</a></dt> |
| <dt>modify, <a href="#faq_modify_seq_and_map">FAQ</a></dt> |
| <dt>operations, <a href="#dgui_template_exp_sequenceop">Sequence operations</a></dt> |
| <dt>slice, <a href="#dgui_template_exp_seqenceop_slice">Sequence slice</a></dt> |
| <dt>sorting, <a href="#ref_builtin_sort">sort</a>, <a href="#ref_builtin_sort_by">sort_by</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_container">Containers</a></dt> |
| </dl></dd> |
| <dt> |
| sequence slice, <a href="#dgui_template_exp_seqenceop_slice">Sequence slice</a> |
| </dt> |
| <dt> |
| servlet </dt> |
| <dd><dl> |
| <dt>include, <a href="#pgui_misc_servlet_include">Including content from other web application |
| resources</a></dt> |
| </dl></dd> |
| <dt> |
| Servlet, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a> |
| </dt> |
| <dt> |
| setting, <a href="#pgui_config_settings">Settings</a> |
| </dt> |
| <dt> |
| setting directive, <a href="#ref_directive_setting">setting</a> |
| </dt> |
| <dt> |
| shared variable, <a href="#pgui_config_sharedvariables">Shared variables</a> |
| </dt> |
| <dt> |
| short built-in, <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| size built-in, <a href="#ref_builtin_size">size</a> |
| </dt> |
| <dt> |
| sort_by built-in, <a href="#ref_builtin_sort_by">sort_by</a> |
| </dt> |
| <dt> |
| sort built-in, <a href="#ref_builtin_sort">sort</a> |
| </dt> |
| <dt> |
| special variable, <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| special variables, <a href="#dgui_template_exp_var_special">Special variables</a> |
| </dt> |
| <dt> |
| split built-in, <a href="#ref_builtin_split">split</a> |
| </dt> |
| <dt> |
| square bracket syntax, <a href="#dgui_misc_alternativesyntax">Alternative (square bracket) syntax</a> |
| </dt> |
| <dt> |
| starts_with built-in, <a href="#ref_builtin_starts_with">starts_with</a> |
| </dt> |
| <dt> |
| static method </dt> |
| <dd><dl> |
| <dt>accessing from templates, <a href="#autoid_54">Bean wrapper</a></dt> |
| </dl></dd> |
| <dt> |
| stop directive, <a href="#ref_directive_stop">stop</a> |
| </dt> |
| <dt> |
| storing templates, <a href="#pgui_config_templateloading">Template loading</a> |
| </dt> |
| <dt> |
| strict syntax, <a href="#ref_depr_oldsyntax">Old FTL syntax</a> |
| </dt> |
| <dt> |
| string </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_string">Built-ins for strings</a></dt> |
| <dt>concatenate, <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a></dt> |
| <dt>interpolation, <a href="#dgui_template_exp_stringop_interpolation">Interpolation (or concatenation)</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| <dt>literal, <a href="#dgui_template_exp_direct_string">Strings</a></dt> |
| <dt>operations, <a href="#dgui_template_exp_stringop">String operations</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| string built-in, <a href="#ref_builtin_string_for_number">string (when used with a numerical value)</a>, |
| <a href="#ref_builtin_string_for_date">string (when used with a date value)</a>, |
| <a href="#ref_builtin_string_for_boolean">string (when used with a boolean value)</a> |
| </dt> |
| <dt> |
| Struts, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a> |
| </dt> |
| <dt> |
| subsequence, <a href="#dgui_template_exp_seqenceop_slice">Sequence slice</a> |
| </dt> |
| <dt> |
| substring built-in, <a href="#ref_builtin_substring">substring</a> |
| </dt> |
| <dt> |
| subtraction, <a href="#dgui_template_exp_arit">Arithmetical calculations</a> |
| </dt> |
| <dt> |
| subvariable </dt> |
| <dd><dl> |
| <dt>accessing, <a href="#dgui_template_exp_var_toplevel">Top-level variables</a>, <a href="#dgui_template_exp_var_hash">Retrieving data from a hash</a>, <a href="#dgui_template_exp_var_sequence">Retrieving data from a sequence</a></dt> |
| </dl></dd> |
| <dt> |
| switch directive, <a href="#ref_directive_switch">switch, case, default, break</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_T"></a> |
| <h2 class="indexLabel">T</h2> |
| <dl> |
| <dt> |
| tabular printing of sequences, <a href="#ref_builtin_chunk">chunk</a> |
| </dt> |
| <dt> |
| tag </dt> |
| <dd><dl> |
| <dt>user-defined, <a href="#dgui_misc_userdefdir">Defining your own directives</a></dt> |
| </dl></dd> |
| <dt> |
| taglib, <a href="#autoid_55">Using FreeMarker with servlets</a> |
| </dt> |
| <dt> |
| t directive, <a href="#ref_directive_t">t, lt, rt</a> |
| </dt> |
| <dt> |
| template, <a href="#dgui_template">The Template</a> |
| </dt> |
| <dd><dl> |
| <dt>Java side, <a href="#pgui_quickstart_gettemplate">Get the template</a></dt> |
| </dl></dd> |
| <dt> |
| template caching, <a href="#pgui_config_templateloading_caching">Template caching</a> |
| </dt> |
| <dt> |
| template loaders, <a href="#autoid_38">Template loading</a> |
| </dt> |
| <dt> |
| template loading, <a href="#pgui_config_templateloading">Template loading</a> |
| </dt> |
| <dt> |
| template path, <a href="#autoid_42">Template loading</a> |
| </dt> |
| <dt> |
| temporary variable, <a href="#dgui_misc_var">Defining variables in the template</a> |
| </dt> |
| <dt> |
| testing for missing, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| <dt> |
| testing for null, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| <dt> |
| testing for undefined, <a href="#dgui_template_exp_missing_test">Missing value test operator</a> |
| </dt> |
| <dt> |
| text, <a href="#dgui_template_overallstructure">Overall structure</a> |
| </dt> |
| <dt> |
| thread-safety, <a href="#pgui_misc_multithreading">Multithreading</a> |
| </dt> |
| <dt> |
| time </dt> |
| <dd><dl> |
| <dt>built-ins, <a href="#ref_builtins_date">Built-ins for dates</a></dt> |
| <dt>Java API related difficulties, <a href="#autoid_31">Scalars</a></dt> |
| <dt>Java side, <a href="#pgui_datamodel_scalar">Scalars</a></dt> |
| <dt>the FTL value type, <a href="#dgui_datamodel_scalar">Scalars</a></dt> |
| </dl></dd> |
| <dt> |
| time_format, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| time_zone, <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| time built-in, <a href="#ref_builtin_string_date">date, time, datetime</a>, |
| <a href="#ref_builtin_date_datetype">date, time, datetime</a> |
| </dt> |
| <dt> |
| transform, <a href="#dgui_misc_userdefdir">Defining your own directives</a> |
| </dt> |
| <dt> |
| transform directive, <a href="#ref_depr_transform">Transform directive</a> |
| </dt> |
| <dt> |
| tree nodes, <a href="#pgui_datamodel_node">Node variables</a> |
| </dt> |
| <dt> |
| trees, <a href="#pgui_datamodel_node">Node variables</a> |
| </dt> |
| <dt> |
| trim built-in, <a href="#ref_builtin_trim">trim</a> |
| </dt> |
| <dt> |
| trimmer directives, <a href="#ref_directive_t">t, lt, rt</a>, |
| <a href="#ref_directive_nt">nt</a> |
| </dt> |
| <dt> |
| type-casting, <a href="#ref_builtin_string_date">date, time, datetime</a>, |
| <a href="#ref_builtin_number">number</a>, |
| <a href="#ref_builtin_c">c</a>, |
| <a href="#ref_builtin_string_for_number">string (when used with a numerical value)</a>, |
| <a href="#ref_builtin_string_for_date">string (when used with a date value)</a>, |
| <a href="#ref_builtin_date_datetype">date, time, datetime</a>, |
| <a href="#ref_builtin_string_for_boolean">string (when used with a boolean value)</a>, |
| <a href="#ref_builtin_numType">byte, double, float, int, long, short</a> |
| </dt> |
| <dt> |
| type checking, <a href="#ref_builtin_isType">is_...</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_U"></a> |
| <h2 class="indexLabel">U</h2> |
| <dl> |
| <dt> |
| uncap_first built-in, <a href="#ref_builtin_uncap_first">uncap_first</a> |
| </dt> |
| <dt> |
| undefined variable, <a href="#dgui_template_exp_missing">Handling missing values</a> |
| </dt> |
| <dt> |
| upper_case built-in, <a href="#ref_builtin_upper_case">upper_case</a> |
| </dt> |
| <dt> |
| url_escaping_charset, <a href="#ref_builtin_url">url</a>, |
| <a href="#autoid_101">setting</a> |
| </dt> |
| <dt> |
| url built-in, <a href="#ref_builtin_url">url</a> |
| </dt> |
| <dt> |
| URL encoding, <a href="#ref_builtin_url">url</a> |
| </dt> |
| <dt> |
| URL escaping, <a href="#ref_builtin_url">url</a> |
| </dt> |
| <dt> |
| URL escaping charset, <a href="#ref_specvar">Special Variable Reference</a>, |
| <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| user-defined directive, <a href="#dgui_misc_userdefdir">Defining your own directives</a>, |
| <a href="#ref_directive_userDefined">User-defined directive (<@...>)</a> |
| </dt> |
| <dd><dl> |
| <dt>the FTL value type, <a href="#dgui_datamodel_userdefdir">User-defined directives</a></dt> |
| </dl></dd> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_V"></a> |
| <h2 class="indexLabel">V</h2> |
| <dl> |
| <dt> |
| value, <a href="#topic.value">What is a value?</a> |
| </dt> |
| <dt> |
| values built-in, <a href="#ref_builtin_values">values</a> |
| </dt> |
| <dt> |
| variable, <a href="#dgui_misc_var">Defining variables in the template</a> |
| </dt> |
| <dt> |
| variables, <a href="#pgui_misc_var">Variables</a> |
| </dt> |
| <dd><dl> |
| <dt>names, <a href="#faq_legal_variable_names">FAQ</a></dt> |
| </dl></dd> |
| <dt> |
| Velocity, <a href="#faq_jsp_vs_velocity">FAQ</a> |
| </dt> |
| <dt> |
| version, <a href="#ref_specvar">Special Variable Reference</a> |
| </dt> |
| <dt> |
| visit directive, <a href="#ref_directive_visit">visit, recurse, fallback</a> |
| </dt> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_W"></a> |
| <h2 class="indexLabel">W</h2> |
| <dl> |
| <dt> |
| web_safe built-in, <a href="#ref_depr_builtin">List of deprecated built-ins</a> |
| </dt> |
| <dt> |
| Web application framework, <a href="#pgui_misc_servlet">Using FreeMarker with servlets</a> |
| </dt> |
| <dt> |
| white-space removal, <a href="#dgui_misc_whitespace">White-space handling</a> |
| </dt> |
| <dd><dl> |
| <dt>compress, <a href="#autoid_30">White-space handling</a>, <a href="#ref_directive_compress">compress</a></dt> |
| <dt>stripping, <a href="#dgui_misc_whitespace_stripping">White-space stripping</a>, <a href="#ref_directive_ftl">ftl</a>, <a href="#ref_directive_nt">nt</a></dt> |
| <dt>trimming, <a href="#ref_directive_t">t, lt, rt</a>, <a href="#ref_directive_nt">nt</a></dt> |
| </dl></dd> |
| <dt> |
| word_list built-in, <a href="#ref_builtin_word_list">word_list</a> |
| </dt> |
| <dt> |
| wrapper, <a href="#pgui_datamodel_basics">Basics</a>, |
| <a href="#pgui_datamodel_objectWrapper">Object wrappers</a> |
| </dt> |
| <dt> |
| wrapping </dt> |
| <dd><dl> |
| <dt>beans, <a href="#pgui_misc_beanwrapper">Bean wrapper</a></dt> |
| <dt>jython, <a href="#pgui_misc_jythonwrapper">Jython wrapper</a></dt> |
| <dt>reflection, <a href="#pgui_misc_beanwrapper">Bean wrapper</a></dt> |
| </dl></dd> |
| </dl></div> |
| <div class="indexdiv"> |
| <a name="idx_X"></a> |
| <h2 class="indexLabel">X</h2> |
| <dl> |
| <dt> |
| xhtml built-in, <a href="#ref_builtin_xhtml">xhtml</a> |
| </dt> |
| <dt> |
| XML </dt> |
| <dd><dl> |
| <dt>declarative processing, <a href="#xgui_declarative">Declarative XML Processing</a></dt> |
| <dt>exposing, <a href="#xgui_expose">Exposing XML documents</a></dt> |
| <dt>imperative processing, <a href="#xgui_imperative">Imperative XML processing</a></dt> |
| </dl></dd> |
| <dt> |
| xml built-in, <a href="#ref_builtin_xml">xml</a> |
| </dt> |
| <dt> |
| XML namespace </dt> |
| <dd><dl> |
| <dt>in imperative processing, <a href="#autoid_72">Learning by example</a></dt> |
| </dl></dd> |
| <dt> |
| XML namespaces </dt> |
| <dd><dl> |
| <dt>in declarative processing, <a href="#autoid_77">Details</a></dt> |
| </dl></dd> |
| <dt> |
| XSLT, <a href="#xgui_declarative">Declarative XML Processing</a> |
| </dt> |
| </dl></div> |
| <div class="bottom-pagers-wrapper"></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"></div><div class="col-right"><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="2020-07-09T23:48:35Z" title="Thursday, July 9, 2020 11:48:35 PM GMT">2020-07-09 23:48:35 GMT</time> </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2020 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p> |
| </div></div></div></body> |
| </html> |
