Modified: velocity/site/production/engine/2.1/upgrading.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/upgrading.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/2.1/upgrading.html (original) +++ velocity/site/production/engine/2.1/upgrading.html Mon Mar 11 00:49:33 2019 @@ -228,10 +228,16 @@ h2:hover > .headerlink, h3:hover > .head <ul> <li><a href="#upgrading-contents">Upgrading - Contents</a></li> <li><a href="#upgrading-from-earlier-versions">Upgrading from earlier versions</a></li> -<li><a href="#upgrading-from-velocity-17x-to-velocity-2x">Upgrading from Velocity 1.7.x to Velocity 2.x</a><ul> -<li><a href="#behavior-api-changes">Behavior / API changes:</a></li> -<li><a href="#vtl-changes">VTL Changes:</a></li> -<li><a href="#dependency-changes">Dependency changes:</a></li> +<li><a href="#upgrading-from-velocity-20-to-velocity-21">Upgrading from Velocity 2.0 to Velocity 2.1</a><ul> +<li><a href="#behavior-api-changes">Behavior / API Changes</a></li> +<li><a href="#vtl-changes">VTL Changes</a></li> +<li><a href="#dependency-changes">Dependency Changes</a></li> +</ul> +</li> +<li><a href="#upgrading-from-velocity-17-to-velocity-20">Upgrading from Velocity 1.7 to Velocity 2.0</a><ul> +<li><a href="#behavior-api-changes_1">Behavior / API Changes</a></li> +<li><a href="#vtl-changes_1">VTL Changes</a></li> +<li><a href="#dependency-changes_1">Dependency Changes</a></li> </ul> </li> <li><a href="#upgrading-from-velocity-16x-to-velocity-17x">Upgrading from Velocity 1.6.x to Velocity 1.7.x</a></li> @@ -241,7 +247,45 @@ h2:hover > .headerlink, h3:hover > .head </div> <h2 id="upgrading-from-earlier-versions">Upgrading from earlier versions<a class="headerlink" href="#upgrading-from-earlier-versions" title="Permanent link">¶</a></h2> <p>Release with the same major number (1.x, 2.x) are intended to be drop-in replacements. However, in most cases the versions of dependency jars must be adjusted because newer versions of Velocity might require updates.</p> -<h2 id="upgrading-from-velocity-17x-to-velocity-2x">Upgrading from Velocity 1.7.x to Velocity 2.x<a class="headerlink" href="#upgrading-from-velocity-17x-to-velocity-2x" title="Permanent link">¶</a></h2> +<h2 id="upgrading-from-velocity-20-to-velocity-21">Upgrading from Velocity 2.0 to Velocity 2.1<a class="headerlink" href="#upgrading-from-velocity-20-to-velocity-21" title="Permanent link">¶</a></h2> +<p>For busy people: To maximize backward compatibility of Velocity 2.1 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:</p> +<div class="codehilite"><pre><span class="c"># No automatic conversion of methods arguments</span> +<span class="na">introspector.conversion_handler.class</span> <span class="o">=</span> <span class="s">none</span> + +<span class="c"># Use backward compatible space gobbling</span> +<span class="na">parser.space_gobbling</span> <span class="o">=</span> <span class="s">bc</span> + +<span class="c"># Have #if($foo) only returns false if $foo is false or null</span> +<span class="na">directive.if.empty_check</span> <span class="o">=</span> <span class="s">false</span> + +<span class="c"># Allow '-' in identifiers</span> +<span class="na">parser.allow_hyphen_in_identifiers</span> <span class="o">=</span> <span class="s">true</span> + +<span class="c"># When displaying null arguments literals, use provided arguments literals</span> +<span class="na">velocimacro.arguments.preserve_literals</span> <span class="o">=</span> <span class="s">true</span> +</pre></div> + + +<p>Also, please note that Velocity 2.1 now requires Java JDK 1.8 for bulding and Java JRE 1.8 at runtime.</p> +<h3 id="behavior-api-changes">Behavior / API Changes<a class="headerlink" href="#behavior-api-changes" title="Permanent link">¶</a></h3> +<ul> +<li>inside a macro, since 2.0, the rendering of null arguments uses the local reference literal. To revert to the 1.7 behavior, you can set the boolean property <code>velocimacro.preserve.arguments.literals</code> to true. The macros will then use the provided argument literals in such cases.</li> +<li>the <a href="apidocs/org/apache/velocity/util/introspection/ConversionHandler.html"><code>org.apache.util.introspection.ConversionHandler</code></a> interface (introduced in 2.0) has been deprecated in favor of the <a href="apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html"><code>org.apache.util.introspection.TypeConversionHandler</code></a> interface. The new interface let one specify converters towards a <code>java.lang.reflect.Type</code> rather than a <code>java.lang.class</code>.</li> +<li>most names of Velocity configuration properties have changed ; old names are still functional but will emit a deprecation warning in the log. See the <a href="configuration-property-changes-in-2.1.html">Configuration Changes in Velocity 2.1</a> page.</li> +</ul> +<h3 id="vtl-changes">VTL Changes<a class="headerlink" href="#vtl-changes" title="Permanent link">¶</a></h3> +<ul> +<li>since 2.0 the hypen ( <code>-</code> ) cannot be used in variable names anymore, but in 2.1, this behavior can be restored for backward compatibility with 1.7 by setting the new <code>parser.allow_hyphen_in_identifiers</code> boolean property to true</li> +<li>it's now possible to provide default values for references, using the syntax <code>${name|'John Doe'}</code>. The right part can be any valid VTL expression.</li> +<li>the <code>#foreach()</code> directive accepts an <code>#else</code> block which is evaluated when the loop is empty: <code>#foreach(...) ... #else ... #end</code>.</li> +</ul> +<h3 id="dependency-changes">Dependency Changes<a class="headerlink" href="#dependency-changes" title="Permanent link">¶</a></h3> +<ul> +<li>Velocity 2.1 now requires JDK 1.8+ for building and JRE 1.8+ at runtime.</li> +<li>commons-lang3 has been upgraded to 3.8.1.</li> +<li>slf4j-api has been upgraded to 1.7.26.</li> +</ul> +<h2 id="upgrading-from-velocity-17-to-velocity-20">Upgrading from Velocity 1.7 to Velocity 2.0<a class="headerlink" href="#upgrading-from-velocity-17-to-velocity-20" title="Permanent link">¶</a></h2> <div class="note"> Please note that the maven repository path has changed: <ul> @@ -250,27 +294,21 @@ Please note that the maven repository pa </ul> </div> -<p>For busy people: To maximize backward compatibility with Velocity 1.x, be sure to include the following lines in your Velocity configuration:</p> +<p>To maximize backward compatibility of Velocity 2.0 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:</p> <div class="codehilite"><pre><span class="c"># No automatic conversion of methods arguments</span> -<span class="na">runtime.conversion.handler</span> <span class="o">=</span> <span class="s">none</span> +<span class="na">runtime.conversion.handler.class</span> <span class="o">=</span> <span class="s">none</span> <span class="c"># Use backward compatible space gobbling</span> <span class="na">space.gobbling</span> <span class="o">=</span> <span class="s">bc</span> <span class="c"># Have #if($foo) only returns false if $foo is false or null</span> <span class="na">directive.if.emptycheck</span> <span class="o">=</span> <span class="s">false</span> - -<span class="c"># Allow '-' in identifiers</span> -<span class="na">parser.allows.dash.identifiers</span> <span class="o">=</span> <span class="s">true</span> - -<span class="c"># When displaying null arguments literals, use provided arguments literals</span> -<span class="na">velocimacro.preserve.arguments.literals</span> <span class="o">=</span> <span class="s">true</span> </pre></div> <p>and check the <a href="#dependencies-changes">Dependency changes</a> below.</p> <p>Read below for futher details.</p> -<h3 id="behavior-api-changes">Behavior / API changes:<a class="headerlink" href="#behavior-api-changes" title="Permanent link">¶</a></h3> +<h3 id="behavior-api-changes_1">Behavior / API Changes<a class="headerlink" href="#behavior-api-changes_1" title="Permanent link">¶</a></h3> <ul> <li>velocity is now using the SLF4J logging facade. Hence, all methods accepting or returning a logger now use the org.slf4j.Logger object. Velocity uses a logger name of <code>org.apache.velocity</code> (configurable with the <code>runtime.log.name</code> configuration entry), and <a href="developer-guide.html#logging">several other childen loggers</a>.</li> <li>the internal Context API now enforces String keys everywhere, this may break custom Context implementations at compile-time.</li> @@ -287,21 +325,18 @@ Please note that the maven repository pa <li>Initialization methods in Velocity and VelocityEngine taking an ExtendedProperties have been removed (but <code>setProperties(Properties)</code> methods are still here). All occurences of the org.apache.commons.collections.ExtendedProperties class in the runtime internal initialization API have been replaced by org.apache.velocity.util.ExtProperties.</li> <li>the macros are now using a 'call by sharing' convention (which means that all arguments are evaluated once at start, and that the macro receives a copy of the reference to each argument).</li> <li>the <code>UberspectLoggable</code> interface has been removed.</li> -<li>the <code>directive.if.tostring.nullcheck</code> configuration property has been superseded by the <code>directive.if.emptycheck</code> property, which defaults to true. It means that all empty objects (strings and collections) as long as zero numbers, do evaluate to false (see the complete <a href="configuration.html#if-directive">boolean context evaluation</a> rules.). You may want to set <code>directive.if.emptycheck</code> to false to maximize backward compatibility with 1.x.</li> -<li>inside a macro, the rendering of null arguments uses the local reference literal - to revert to the 1.7 behavior, you can set the boolean property <code>velocimacro.preserve.arguments.literals</code> to true (since 2.1). The macros will then use the provided argument literals in such cases.</li> -<li>since 2.1, the <a href="apidocs/org/apache/velocity/util/introspection/ConversionHandler.html"><code>org.apache.util.introspection.ConversionHandler</code></a> interface has been deprecated in favor of the <a href="apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html"><code>org.apache.util.introspection.TypeConversionHandler</code></a> interface. The new interface let one specify converters towards a <code>java.lang.reflect.Type</code> rather than a <code>java.lang.class</code>.</li> +<li>the <code>directive.if.tostring.nullcheck</code> configuration property has been superseded by the <code>directive.if.emptycheck</code> (warning: renamed as <code>directive.if.empty_check</code> in 2.1) property, which defaults to true. It means that all empty objects (strings and collections) as long as zero numbers, do evaluate to false (see the complete <a href="configuration.html#if-directive">boolean context evaluation</a> rules.). You may want to set <code>directive.if.emptycheck</code> to false to maximize backward compatibility with 1.x.</li> +<li>inside a macro, the rendering of null arguments uses the local reference literal (see 2.1 for an 1.7 compatibility flag).</li> </ul> -<h3 id="vtl-changes">VTL Changes:<a class="headerlink" href="#vtl-changes" title="Permanent link">¶</a></h3> +<h3 id="vtl-changes_1">VTL Changes<a class="headerlink" href="#vtl-changes_1" title="Permanent link">¶</a></h3> <ul> -<li>the hypen ( <code>-</code> ) cannot be used in variable names anymore, but this behavior can be restored for backward compatibility (since 2.1) by setting the new <code>parser.allows.dash.in.identifiers</code> boolean property to true</li> +<li>the hypen ( <code>-</code> ) cannot be used in variable names anymore (see 2.1 for an 1.7 compatibility flag).</li> <li>method arguments can be arithmetic expressions</li> -<li>method arguments are now converted as needed between all main basic Java standard types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the property <code>runtime.conversion.handler = none</code>.</li> +<li>method arguments are now converted as needed between all main basic Java standard types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the property <code>runtime.conversion.handler.class = none</code>.</li> <li>space gobbling (to control the indentation of generated code) is now configurable via the <code>space.gobbing</code> configuration key, which can take the following values: <code>none</code>, <code>bc</code> (aka. backward compatible), <code>lines</code> and <code>structured</code>. See the related documentation section for details. To maximize backward compatibility with 1.x, set it to <code>bc</code>.</li> <li>the #foreach predefined references <code>$velocityCount</code> and <code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code> (1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li> -<li>since 2.1, it's now possible to provide default values for references, using the syntax <code>${name|'John Doe'}</code>. The right part can be any valid VTL expression.</li> -<li>since 2.1, the <code>#foreach()</code> directive accepts an <code>#else</code> block which is evaluated when the loop is empty: <code>#foreach(...) ... #else ... #end</code>.</li> </ul> -<h3 id="dependency-changes">Dependency changes:<a class="headerlink" href="#dependency-changes" title="Permanent link">¶</a></h3> +<h3 id="dependency-changes_1">Dependency Changes<a class="headerlink" href="#dependency-changes_1" title="Permanent link">¶</a></h3> <ul> <li>Velocity now requires a JDK version of 1.7 or higher.</li> <li>commons-collections and commons-logging aren't needed any more at runtime.</li>
Modified: velocity/site/production/engine/2.1/user-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/user-guide.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/2.1/user-guide.html (original) +++ velocity/site/production/engine/2.1/user-guide.html Mon Mar 11 00:49:33 2019 @@ -248,7 +248,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="#formal-reference-notation">Formal Reference Notation</a></li> <li><a href="#alternate-values">Alternate values</a></li> <li><a href="#quiet-reference-notation">Quiet Reference Notation</a></li> -<li><a href="#strict-reference-mode">Strict Reference Mode</a></li> +<li><a href="#strict-rendering-mode">Strict Rendering Mode</a></li> <li><a href="#case-substitution">Case Substitution</a></li> <li><a href="#directives">Directives</a><ul> <li><a href="#set">Set</a><ul> @@ -414,7 +414,6 @@ h2:hover > .headerlink, h3:hover > .head <p>Here are some examples of valid variable references in the VTL:</p> <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"></span> <span class="p">$</span><span class="nv">mudSlinger</span><span class="x"></span> -<span class="p">$</span><span class="nv">mud</span><span class="x">-slinger</span> <span class="p">$</span><span class="nv">mud_slinger</span><span class="x"></span> <span class="p">$</span><span class="nv">mudSlinger1</span><span class="x"></span> </pre></div> @@ -566,8 +565,8 @@ h2:hover > .headerlink, h3:hover > .head </pre></div> -<h2 id="strict-reference-mode">Strict Reference Mode<a class="headerlink" href="#strict-reference-mode" title="Permanent link">¶</a></h2> -<p>Velocity 1.6 introduces the concept of strict reference mode which is activated by setting the velocity configuration property 'runtime.references.strict' to true. The general intent of this setting is to make Velocity behave more strictly in cases that are undefined or ambiguous, similar to a programming language, which may be more appropriate for some uses of Velocity. In such undefined or ambiguous cases Velocity will throw an exception. The following discussion outlines the cases in which strict behavior is different from traditional behavior.</p> +<h2 id="strict-rendering-mode">Strict Rendering Mode<a class="headerlink" href="#strict-rendering-mode" title="Permanent link">¶</a></h2> +<p>The strict rendering mode is activated by setting the velocity configuration property 'runtime.strict_mode.enable' to true. The general intent of this setting is to make Velocity behave more strictly in cases that are undefined or ambiguous, similar to a programming language, which may be more appropriate for some uses of Velocity. In such undefined or ambiguous cases Velocity will throw an exception. The following discussion outlines the cases in which strict behavior is different from traditional behavior.</p> <p>With this setting references are required to be either placed explicitly into the context or defined with a #set directive or Velocity will throw an exception. References that are in the context with a value of null will not produce an exception. Additionally, if an attempt is made to call a method or a property on an object within a reference that does not define the specified method or property then Velocity will throw an exception. This is also true if there is an attempt to call a method or property on a null value.</p> <p>In the following examples $bar is defined but $foo is not, and all these statements will throw an exception:</p> <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"> </span><span class="cp">##</span><span class="c"> Exception</span><span class="x"></span> @@ -584,7 +583,7 @@ h2:hover > .headerlink, h3:hover > .head </pre></div> -<p>In general strict reference behavior is true for all situations in which references are used except for a special case within the #if directive. If a reference is used within a #if or #elseif directive without any methods or properties, and if it is not being compared to another value, then undefined references are allowed. This behavior provides an easy way to test if a reference is defined before using it in a template. In the following example where $foo is not defined the statements will not throw an exception.</p> +<p>In general strict rendering mode behavior is true for all situations in which references are used except for a special case within the #if directive. If a reference is used within a #if or #elseif directive without any methods or properties, and if it is not being compared to another value, then undefined references are allowed. This behavior provides an easy way to test if a reference is defined before using it in a template. In the following example where $foo is not defined the statements will not throw an exception.</p> <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False</span><span class="x"></span> <span class="cp">#</span><span class="nf">if</span><span class="p"> (</span> <span class="o">!</span> <span class="p">$</span><span class="nv">foo</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> True</span><span class="x"></span> <span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">&&</span> <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False and $foo.bar will not be evaluated</span><span class="x"></span> @@ -593,7 +592,7 @@ h2:hover > .headerlink, h3:hover > .head </pre></div> -<p>Strict mode requires that comparisons of >, <, >= or <= within an #if directive makes sense. Also, the argument to #foreach must be iterable (this behavior can be modified with the property directive.foreach.skip.invalid). Finally, undefined macro references will also throw an exception in strict mode.</p> +<p>Strict rendering mode requires that comparisons of >, <, >= or <= within an #if directive makes sense. Also, the argument to #foreach must be iterable (this behavior can be modified with the property directive.foreach.skip_invalid). Finally, undefined macro references will also throw an exception in strict mode.</p> <p>References that Velocity attempts to render but evaluate to null will cause an Exception. To simply render nothing in this case the reference can be preceded by '$!' instead of '$', similar to non strict mode. Keep in mind this is different from the reference not existing in the context which will always throw an exception when attempting to render it in strict mode. For example, below $foo has a value of null in the context</p> <div class="codehilite"><pre><span class="x">this is </span><span class="p">$</span><span class="nv">foo</span><span class="x"> </span><span class="cp">##</span><span class="c"> throws an exception because $foo is null</span><span class="x"></span> <span class="x">this is </span><span class="p">$!</span><span class="nv">foo</span><span class="x"> </span><span class="cp">##</span><span class="c"> renders to "this is " without an exception</span><span class="x"></span> @@ -856,7 +855,7 @@ $foo <p>If you want a zero-based index of the #foreach loop, you can just use $foreach.index instead of $foreach.count. Likewise, $foreach.first and $foreach.last are provided to compliment $foreach.hasNext. If you want to access these properties for an outer #foreach loop, you can reference them directly through the $foreach.parent or $foreach.topmost properties (e.g. $foreach.parent.index or $foreach.topmost.hasNext).</p> <p>It's possible to set a maximum allowed number of times that a loop may be executed. By default there is no max (indicated by a value of 0 or less), but this can be set to an arbitrary number in the <code>velocity.properties</code> file. This is useful as a fail-safe.</p> <div class="codehilite"><pre><span class="c"># The maximum allowed number of loops.</span> -<span class="na">directive.foreach.maxloops</span> <span class="o">=</span> <span class="s">-1</span> +<span class="na">directive.foreach.max_loops</span> <span class="o">=</span> <span class="s">-1</span> </pre></div> @@ -894,7 +893,7 @@ $foo <p>Like the <em>#include</em> directive, <em>#parse</em> can take a variable rather than a template. Any templates to which <em>#parse</em> refers must be included under TEMPLATE_ROOT. Unlike the <em>#include</em> directive, <em>#parse</em> will only take a single argument.</p> -<p>VTL templates can have <em>#parse</em> statements referring to templates that in turn have <em>#parse</em> statements. By default set to 10, the <em>directive.parse.max.depth</em> line of the <code>velocity.properties</code> allows users to customize maximum number of <em>#parse</em> referrals that can occur from a single template. (Note: If the <em>directive.parse.max.depth</em> property is absent from the <code>velocity.properties</code> file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template <code>dofoo.vm</code> contains the following lines:</p> +<p>VTL templates can have <em>#parse</em> statements referring to templates that in turn have <em>#parse</em> statements. By default set to 10, the <em>directive.parse.max_depth</em> line of the <code>velocity.properties</code> allows users to customize maximum number of <em>#parse</em> referrals that can occur from a single template. (Note: If the <em>directive.parse.max_depth</em> property is absent from the <code>velocity.properties</code> file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template <code>dofoo.vm</code> contains the following lines:</p> <div class="codehilite"><pre><span class="x">Count down.</span> <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">count</span> <span class="o">=</span> <span class="m">8</span> <span class="p">)</span><span class="x"></span> <span class="cp">#</span><span class="nf">parse</span><span class="p">(</span> <span class="s2">"parsefoo.vm"</span> <span class="p">)</span><span class="x"></span> @@ -1046,12 +1045,12 @@ $foo <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties" title="Permanent link">¶</a></h4> <p>Several lines in the <code>velocity.properties</code> file allow for flexible implementation of Velocimacros. Note that these are also documented in the <a href="developer-guide.html">Developer Guide</a>.</p> -<p><code>velocimacro.library</code> - A comma-separated list of all Velocimacro template libraries. By default, Velocity looks for a single library: <em>VM_global_library.vm</em>. The configured template path is used to find the Velocimacro libraries.</p> -<p><code>velocimacro.permissions.allow.inline</code> - This property, which has possible values of true or false, determines whether Velocimacros can be defined in regular templates. The default, true, allows template designers to define Velocimacros in the templates themselves.</p> -<p><code>velocimacro.permissions.allow.inline.to.replace.global</code> - With possible values of true or false, this property allows the user to specify if a Velocimacro defined inline in a template can replace a globally defined template, one that was loaded on startup via the <code>velocimacro.library</code> property. The default, <code>false</code>, prevents Velocimacros defined inline in a template from replacing those defined in the template libraries loaded at startup.</p> -<p><code>velocimacro.permissions.allow.inline.local.scope</code> - This property, with possible values of true or false, defaulting to false, controls if Velocimacros defined inline are 'visible' only to the defining template. In other words, with this property set to true, a template can define inline VMs that are usable only by the defining template. You can use this for fancy VM tricks - if a global VM calls another global VM, with inline scope, a template can define a private implementation of the second VM that will be called by the first VM when invoked by that template. All other templates are unaffected.</p> -<p><code>velocimacro.library.autoreload</code> - This property controls Velocimacro library autoloading. The default value is <code>false</code>. When set to <code>true</code> the source Velocimacro library for an invoked Velocimacro will be checked for changes, and reloaded if necessary. This allows you to change and test Velocimacro libraries without having to restart your application or servlet container, just like you can with regular templates. This mode only works when caching is <i>off</i> in the resource loaders (e.g. <code>file.resource.loader.cache = false</code> ). This feature is intended for development, not for production.</p> -<p>Please note than when two templates each define a macro with the same name, you either need <code>velocimacro.permissions.allow.inline.local.scope</code> or <code>velocimacro.permissions.allow.inline.to.replace.global</code> to be set to true for each template to use its own macro version.</p> +<p><code>velocimacro.library.path</code> - A comma-separated list of all Velocimacro template libraries. By default, Velocity looks for a single library: <em>velocimacros.vtl</em> (since 2.1 ; and if not found it will also look at the old default <em>VM_global_library.vm</em>). The configured template path is used to find the Velocimacro libraries.</p> +<p><code>velocimacro.inline.allow</code> - This property, which has possible values of true or false, determines whether Velocimacros can be defined in regular templates. The default, true, allows template designers to define Velocimacros in the templates themselves.</p> +<p><code>velocimacro.inline.replace_global</code> - With possible values of true or false, this property allows the user to specify if a Velocimacro defined inline in a template can replace a globally defined template, one that was loaded on startup via the <code>velocimacro.library.path</code> property. The default, <code>false</code>, prevents Velocimacros defined inline in a template from replacing those defined in the template libraries loaded at startup.</p> +<p><code>velocimacro.inline.local_scope</code> - This property, with possible values of true or false, defaulting to false, controls if Velocimacros defined inline are 'visible' only to the defining template. In other words, with this property set to true, a template can define inline VMs that are usable only by the defining template. You can use this for fancy VM tricks - if a global VM calls another global VM, with inline scope, a template can define a private implementation of the second VM that will be called by the first VM when invoked by that template. All other templates are unaffected.</p> +<p><code>velocimacro.library.autoreload</code> - This property controls Velocimacro library autoloading. The default value is <code>false</code>. When set to <code>true</code> the source Velocimacro library for an invoked Velocimacro will be checked for changes, and reloaded if necessary. This allows you to change and test Velocimacro libraries without having to restart your application or servlet container, just like you can with regular templates. This mode only works when caching is <i>off</i> in the resource loaders (e.g. <code>resource.loader.file.cache = false</code> ). This feature is intended for development, not for production.</p> +<p>Please note than when two templates each define a macro with the same name, you either need <code>velocimacro.inline.local_scope</code> or <code>velocimacro.inline.replace_global</code> to be set to true for each template to use its own macro version.</p> <h2 id="getting-literal">Getting Literal<a class="headerlink" href="#getting-literal" title="Permanent link">¶</a></h2> <p>VTL uses special characters, such as <em>$</em> and <em>#</em>, to do its work, so some added care should be taken where using these characters in your templates. This section deals with escaping these characters.</p> <h3 id="currency">Currency<a class="headerlink" href="#currency" title="Permanent link">¶</a></h3> @@ -1391,14 +1390,14 @@ $!{foo} <p>which defaults to false. When set to true <em>along with</em></p> -<div class="codehilite"><pre>`<type>.resource.loader.cache = false` +<div class="codehilite"><pre>`resource.loader.<name>.cache = false` </pre></div> -<p>(where <type> is the name of the resource loader that you are using, such as 'file') then the Velocity engine will automatically reload changes to your Velocimacro library files when you make them, so you do not have to dump the servlet engine (or application) or do other tricks to have your Velocimacros reloaded.</p> +<p>(where <name> is the name of the resource loader that you are using, such as 'file') then the Velocity engine will automatically reload changes to your Velocimacro library files when you make them, so you do not have to dump the servlet engine (or application) or do other tricks to have your Velocimacros reloaded.</p> <p>Here is what a simple set of configuration properties would look like.</p> -<div class="codehilite"><pre>file.resource.loader.path = templates -file.resource.loader.cache = false +<div class="codehilite"><pre>resource.loader.file.path = templates +resource.loader.file.cache = false velocimacro.library.autoreload = true </pre></div> Modified: velocity/site/production/engine/2.1/vtl-reference.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/vtl-reference.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/2.1/vtl-reference.html (original) +++ velocity/site/production/engine/2.1/vtl-reference.html Mon Mar 11 00:49:33 2019 @@ -346,7 +346,7 @@ h2:hover > .headerlink, h3:hover > .head <p><em>condition</em> - Expression to evaluate. When its result is null, evaluate to false. Otherwise, check for conversion towards Boolean and non-emptiness as follow:</p> <ul> <li>return its value for a Boolean object, or the result of the getAsBoolean() method if it exists.</li> -<li>if <code>directive.if.emptycheck</code> = <code>false</code> (<code>true</code> by default), stop here and consider it true.</li> +<li>if <code>directive.if.empty_check</code> = <code>false</code> (<code>true</code> by default), stop here and consider it true.</li> <li>return whether an array is empty.</li> <li>return whether isEmpty() is false (covers String and all Collection classes).</li> <li>return whether length() is zero (covers CharSequence classes other than String).</li> @@ -464,7 +464,7 @@ h2:hover > .headerlink, h3:hover > .head </ul> <p>The maximum allowed number of loop iterations can be controlled engine-wide with <code>velocity.properties</code>. By default, there is no limit:</p> <div class="codehilite"><pre><span class="c"># The maximum allowed number of loops.</span> -<span class="na">directive.foreach.maxloops</span> <span class="o">=</span> <span class="s">-1</span> +<span class="na">directive.foreach.max_loops</span> <span class="o">=</span> <span class="s">-1</span> </pre></div> @@ -492,7 +492,7 @@ h2:hover > .headerlink, h3:hover > .head <li>String: <code>#parse( "lecorbusier.vm" )</code></li> <li>Variable: <code>#parse( $foo )</code></li> </ul> -<p>Recursion permitted. See <em>parse_directive.maxdepth</em> in <code>velocity.properties</code> to change from parse depth. (The default parse depth is 10.)</p> +<p>Recursion permitted. See <em>directive.parse.max_depth</em> in <code>velocity.properties</code> to change from parse depth. (The default parse depth is 10.)</p> <h3 id="stop-stops-the-template-engine">#stop - Stops the template engine<a class="headerlink" href="#stop-stops-the-template-engine" title="Permanent link">¶</a></h3> <p>Format:</p> <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>stop</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p> Modified: velocity/site/production/engine/2.1/webapps.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/webapps.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/2.1/webapps.html (original) +++ velocity/site/production/engine/2.1/webapps.html Mon Mar 11 00:49:33 2019 @@ -249,14 +249,14 @@ providing a consistent way to mark up te <p>Really, any of the other ResourceLoader implementations out there are preferred, but all the other ResourceLoaders shipped with Velocity Engine will require you to store your templates somewhere besides the standard file system (e.g. in the classpath, in a database, or on a remote server). If that works for you, then great! However, we recognize that these are not convenient for most people's development cycle.</p> <p>The simplest replacement for FileResourceLoader in a web application is actually a part of the VelocityTools project. It is the <a href="/tools/devel/apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html">WebappResourceLoader</a> This ResourceLoader implementation is specifically designed to work just like the FileResourceLoader, but it is aware of the servlet context and allows you to configure resource paths relative to the servlet root, rather than the local file system.</p> <p>If you are using the VelocityViewServlet, then it is automatically configured and ready to use the WebappResourceLoader. So if you want to change the configured path(s), you need only add a line like the following to your velocity.properties:</p> -<div class="codehilite"><pre><span class="na">webapp.resource.loader.path</span><span class="o">=</span><span class="s">/WEB-INF/mytemplates/</span> +<div class="codehilite"><pre><span class="na">resource.loader.webapp.path</span><span class="o">=</span><span class="s">/WEB-INF/mytemplates/</span> </pre></div> <p>If you need to set the WebappResourceLoader up on your own, then you can make your properties something like this:</p> -<div class="codehilite"><pre><span class="na">resource.loader</span><span class="o">=</span><span class="s">webapp</span> -<span class="na">webapp.resource.loader.class</span><span class="o">=</span><span class="s">org.apache.velocity.tools.view.WebappResourceLoader</span> -<span class="na">webapp.resource.loader.path</span><span class="o">=</span><span class="s">/WEB-INF/mytemplates/</span> +<div class="codehilite"><pre><span class="na">resource.loader</span> <span class="o">=</span> <span class="s">webapp</span> +<span class="na">resource.loader.webapp.class</span> <span class="o">=</span> <span class="s">org.foo.WebappResourceLoader</span> +<span class="na">resource.loader.webapp.path</span> <span class="o">=</span> <span class="s">/WEB-INF/mytemplates/</span> </pre></div> @@ -286,7 +286,7 @@ providing a consistent way to mark up te <h3 id="escaping-htmlxml-entities">Escaping HTML/XML Entities<a class="headerlink" href="#escaping-htmlxml-entities" title="Permanent link">¶</a></h3> <p>Any user-entered text that contains special HTML or XML entities (such as <, >, or &) needs to be escaped before included in the web page. This is required, both to ensure the text is visible, and also to prevent dangerous <a href="http://en.wikipedia.org/wiki/Cross_site_scripting";>cross-site scripting</a>. Unlike, for example, JSTL (the Java Standard Tag Language found in Java Server Pages), Velocity does not escape references by default.</p> <p>However, Velocity provides the ability to specify a <code>ReferenceInsertionEventHandler</code> which will alter the value of a reference before it is inserted into the page. Specifically, you can configure the <code>EscapeHtmlReference</code> handler into your <code>velocity.properties</code> file to escape all references (optionally) matching a regular expression. The following example will escape HTML entities in any reference that starts with "msg" (e.g. <code>$msgText</code>).</p> -<div class="codehilite"><pre><span class="na">eventhandler.referenceinsertion.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.app.event.implement.EscapeHtmlReference</span> +<div class="codehilite"><pre><span class="na">eventhandler.reference_insertion.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.app.event.implement.EscapeHtmlReference</span> <span class="na">eventhandler.escape.html.match</span> <span class="o">=</span> <span class="s">/msg.*/</span> </pre></div> @@ -294,7 +294,7 @@ providing a consistent way to mark up te <p>Note that other kinds of escaping are sometimes required. For example, in style sheets the @ character needs to be escaped, and in Javascript strings the single apostrophe ' needs to be escaped.</p> <h3 id="securing-the-application">Securing the Application<a class="headerlink" href="#securing-the-application" title="Permanent link">¶</a></h3> <p>Since a web application is running on a central server, that typically has multiple users and confidential resources, care must be taken to make certain that the web application is secure. Most standard web security principles apply to a web application built with Velocity. A few specific issues (such as system configuration, more on cross-site scripting, and method introspection) are written up in this article on <a href="http://wiki.apache.org/velocity/BuildingSecureWebApplications";>Building Secure Applications with Velocity</a>. In particular, you may want to prevent template designers from including "dangerous" reflection-related methods by specifying the <code>SecureUberspector</code> to get/set properties and execute method calls.</p> -<div class="codehilite"><pre><span class="na">runtime.introspector.uberspect</span> <span class="o">=</span> <span class="s">org.apache.velocity.util.introspection.SecureUberspector</span> +<div class="codehilite"><pre><span class="na">runtime.introspector.uberspect.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.util.introspection.SecureUberspector</span> </pre></div> Modified: velocity/site/production/engine/devel/apidocs/allclasses-frame.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/apidocs/allclasses-frame.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/devel/apidocs/allclasses-frame.html (original) +++ velocity/site/production/engine/devel/apidocs/allclasses-frame.html Mon Mar 11 00:49:33 2019 @@ -2,10 +2,10 @@ <!-- NewPage --> <html lang="en"> <head> -<!-- Generated by javadoc (1.8.0_191) on Wed Mar 06 16:10:22 CET 2019 --> +<!-- Generated by javadoc (1.8.0_191) on Mon Mar 11 01:36:33 CET 2019 --> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>All Classes (Apache Velocity 2.1-SNAPSHOT API)</title> -<meta name="date" content="2019-03-06"> +<meta name="date" content="2019-03-11"> <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style"> <script type="text/javascript" src="script.js"></script> </head> Modified: velocity/site/production/engine/devel/apidocs/allclasses-noframe.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/apidocs/allclasses-noframe.html?rev=1855189&r1=1855188&r2=1855189&view=diff ============================================================================== --- velocity/site/production/engine/devel/apidocs/allclasses-noframe.html (original) +++ velocity/site/production/engine/devel/apidocs/allclasses-noframe.html Mon Mar 11 00:49:33 2019 @@ -2,10 +2,10 @@ <!-- NewPage --> <html lang="en"> <head> -<!-- Generated by javadoc (1.8.0_191) on Wed Mar 06 16:10:22 CET 2019 --> +<!-- Generated by javadoc (1.8.0_191) on Mon Mar 11 01:36:33 CET 2019 --> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>All Classes (Apache Velocity 2.1-SNAPSHOT API)</title> -<meta name="date" content="2019-03-06"> +<meta name="date" content="2019-03-11"> <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style"> <script type="text/javascript" src="script.js"></script> </head>
