Modified: velocity/site/production/engine/2.0/user-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/user-guide.html?rev=1834410&r1=1834409&r2=1834410&view=diff ============================================================================== --- velocity/site/production/engine/2.0/user-guide.html (original) +++ velocity/site/production/engine/2.0/user-guide.html Tue Jun 26 10:03:18 2018 @@ -312,22 +312,22 @@ h2:hover > .headerlink, h3:hover > .head <p>Velocity makes it easy to customize web pages to your online visitors. As a web site designer at The Mud Room, you want to make the web page that the customer will see after logging into your site.</p> <p>You meet with software engineers at your company, and everyone has agreed that <em>$customer</em> will hold information pertaining to the customer currently logged in, that <em>$mudsOnSpecial</em> will be all the types mud on sale at present. The <em>$flogger</em> object contains methods that help with promotion. For the task at hand, let's concern ourselves only with these three references. Remember, you don't need to worry about how the software engineers extract the necessary information from the database, you just need to know that it works. This lets you get on with your job, and lets the software engineers get on with theirs.</p> <p>You could embed the following VTL statement in the web page:</p> -<div class="codehilite"><pre><span class="nt"><html></span> - <span class="nt"><body></span> - Hello $customer.Name! - <span class="nt"><table></span> - #foreach( $mud in $mudsOnSpecial ) - #if ( $customer.hasPurchased($mud) ) - <span class="nt"><tr></span> - <span class="nt"><td></span> - $flogger.getPromo( $mud ) - <span class="nt"></td></span> - <span class="nt"></tr></span> - #end - #end - <span class="nt"></table></span> - <span class="nt"></body></span> -<span class="nt"></html></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">html</span><span class="p">></span> + <span class="p"><</span><span class="nt">body</span><span class="p">></span> + Hello <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span>! + <span class="p"><</span><span class="nt">table</span><span class="p">></span> + <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">mud</span> <span class="o">in</span> <span class="p">$</span><span class="nv">mudsOnSpecial</span> <span class="p">)</span> + <span class="cp">#</span><span class="nf">if</span><span class="p"> (</span> <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">hasPurchased</span><span class="p">($</span><span class="nv">mud</span><span class="p">)</span> <span class="p">)</span> + <span class="p"><</span><span class="nt">tr</span><span class="p">></span> + <span class="p"><</span><span class="nt">td</span><span class="p">></span> + <span class="p">$</span><span class="nv">flogger</span><span class="p">.</span><span class="nv">getPromo</span><span class="p">(</span> <span class="p">$</span><span class="nv">mud</span> <span class="p">)</span> + <span class="p"></</span><span class="nt">td</span><span class="p">></span> + <span class="p"></</span><span class="nt">tr</span><span class="p">></span> + <span class="cp">#</span><span class="nf">end</span> + <span class="cp">#</span><span class="nf">end</span> + <span class="p"></</span><span class="nt">table</span><span class="p">></span> + <span class="p"></</span><span class="nt">body</span><span class="p">></span> +<span class="p"></</span><span class="nt">html</span><span class="p">></span> </pre></div> @@ -336,7 +336,7 @@ h2:hover > .headerlink, h3:hover > .head <h2 id="velocity-template-language-vtl-an-introduction">Velocity Template Language (VTL): An Introduction<a class="headerlink" href="#velocity-template-language-vtl-an-introduction" title="Permanent link">¶</a></h2> <p>The Velocity Template Language (VTL) is meant to provide the easiest, simplest, and cleanest way to incorporate dynamic content in a web page. Even a web page developer with little or no programming experience should soon be capable of using VTL to incorporate dynamic content in a web site.</p> <p>VTL uses <em>references</em> to embed dynamic content in a web site, and a variable is one type of reference. Variables are one type of reference that can refer to something defined in the Java code, or it can get its value from a VTL <em>statement</em> in the web page itself. Here is an example of a VTL statement that could be embedded in an HTML document:</p> -<div class="codehilite"><pre>#set( $a = "Velocity" ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">a</span> <span class="o">=</span> <span class="s2">"Velocity"</span> <span class="p">)</span><span class="x"></span> </pre></div> @@ -347,12 +347,12 @@ h2:hover > .headerlink, h3:hover > .head <p>In the example above, <em>#set</em> is used to assign a value to a variable. The variable, <em>$a</em>, can then be used in the template to output "Velocity".</p> <h2 id="hello-velocity-world">Hello Velocity World!<a class="headerlink" href="#hello-velocity-world" title="Permanent link">¶</a></h2> <p>Once a value has been assigned to a variable, you can reference the variable anywhere in your HTML document. In the following example, a value is assigned to <em>$foo</em> and later referenced.</p> -<div class="codehilite"><pre><span class="nt"><html></span> - <span class="nt"><body></span> - #set( $foo = "Velocity" ) - Hello $foo World! - <span class="nt"></body></span> -<span class="nt"></html></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">html</span><span class="p">></span> + <span class="p"><</span><span class="nt">body</span><span class="p">></span> + <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"Velocity"</span> <span class="p">)</span> + Hello <span class="p">$</span><span class="nv">foo</span> World! + <span class="p"></</span><span class="nt">body</span><span class="p">></span> +<span class="p"></</span><span class="nt">html</span><span class="p">></span> </pre></div> @@ -360,44 +360,44 @@ h2:hover > .headerlink, h3:hover > .head <p>To make statements containing VTL directives more readable, we encourage you to start each VTL statement on a new line, although you are not required to do so. The <em>set</em> directive will be revisited in greater detail later on.</p> <h2 id="comments">Comments<a class="headerlink" href="#comments" title="Permanent link">¶</a></h2> <p>Comments allows descriptive text to be included that is not placed into the output of the template engine. Comments are a useful way of reminding yourself and explaining to others what your VTL statements are doing, or any other purpose you find useful. Below is an example of a comment in VTL.</p> -<div class="codehilite"><pre>## This is a single line comment. +<div class="codehilite"><pre><span class="cp">##</span><span class="c"> This is a single line comment.</span><span class="x"></span> </pre></div> <p>A single line comment begins with <em>##</em> and finishes at the end of the line. If you're going to write a few lines of commentary, there's no need to have numerous single line comments. Multi-line comments, which begin with <em>#<strong> and end with </strong>#</em>, are available to handle this scenario.</p> -<div class="codehilite"><pre>This is text that is outside the multi-line comment. -Online visitors can see it. +<div class="codehilite"><pre><span class="x">This is text that is outside the multi-line comment.</span> +<span class="x">Online visitors can see it.</span> -#* - Thus begins a multi-line comment. Online visitors won't - see this text because the Velocity Templating Engine will - ignore it. -*# +<span class="cp">#</span><span class="c">*</span> +<span class="c"> Thus begins a multi-line comment. Online visitors won't</span> +<span class="c"> see this text because the Velocity Templating Engine will</span> +<span class="c"> ignore it.</span> +<span class="c">*</span><span class="cp">#</span><span class="x"></span> -Here is text outside the multi-line comment; it is visible. +<span class="x">Here is text outside the multi-line comment; it is visible.</span> </pre></div> <p>Here are a few examples to clarify how single line and multi-line comments work:</p> -<div class="codehilite"><pre>This text is visible. ## This text is not. -This text is visible. -This text is visible. #* This text, as part of a multi-line -comment, is not visible. This text is not visible; it is also -part of the multi-line comment. This text still not -visible. *# This text is outside the comment, so it is visible. -## This text is not visible. +<div class="codehilite"><pre><span class="x">This text is visible. </span><span class="cp">##</span><span class="c"> This text is not.</span><span class="x"></span> +<span class="x">This text is visible.</span> +<span class="x">This text is visible. </span><span class="cp">#</span><span class="c">* This text, as part of a multi-line</span> +<span class="c">comment, is not visible. This text is not visible; it is also</span> +<span class="c">part of the multi-line comment. This text still not</span> +<span class="c">visible. *</span><span class="cp">#</span><span class="x"> This text is outside the comment, so it is visible.</span> +<span class="cp">##</span><span class="c"> This text is not visible.</span><span class="x"></span> </pre></div> <p>There is a third type of comment, the VTL comment block, which may be used to store any sort of extra information you want to track in the template (e.g. javadoc-style author and versioning information):</p> -<div class="codehilite"><pre>#** - This is a VTL comment block and - may be used to store such information - as the document author and versioning - information: - @author John Doe - @version 5 -*# +<div class="codehilite"><pre><span class="cp">#</span><span class="c">**</span> +<span class="c"> This is a VTL comment block and</span> +<span class="c"> may be used to store such information</span> +<span class="c"> as the document author and versioning</span> +<span class="c"> information:</span> +<span class="c"> @author John Doe</span> +<span class="c"> @version 5</span> +<span class="c">*</span><span class="cp">#</span><span class="x"></span> </pre></div> @@ -411,76 +411,71 @@ visible. *# This text is outside the com <li>underscore ("_")</li> </ul> <p>Here are some examples of valid variable references in the VTL:</p> -<div class="codehilite"><pre>$foo -$mudSlinger -$mud-slinger -$mud_slinger -$mudSlinger1 +<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> <p>When VTL references a variable, such as <em>$foo</em>, the variable can get its value from either a <em>set</em> directive in the template, or from the Java code. For example, if the Java variable <em>$foo</em> has the value <em>bar</em> at the time the template is requested, <em>bar</em> replaces all instances of <em>$foo</em> on the web page. Alternatively, if I include the statement</p> -<div class="codehilite"><pre>#set( $foo = "bar" ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"bar"</span> <span class="p">)</span><span class="x"></span> </pre></div> <p>The output will be the same for all instances of <em>$foo</em> that follow this directive.</p> <h3 id="properties">Properties<a class="headerlink" href="#properties" title="Permanent link">¶</a></h3> <p>The second flavor of VTL references are properties, and properties have a distinctive format. The shorthand notation consists of a leading <em>$</em> character followed a VTL Identifier, followed by a dot character (".") and another VTL Identifier. These are examples of valid property references in the VTL:</p> -<div class="codehilite"><pre>$customer.Address -$purchase.Total +<div class="codehilite"><pre><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Address</span><span class="x"></span> +<span class="p">$</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">Total</span><span class="x"></span> </pre></div> <p>Take the first example, <em>$customer.Address</em>. It can have two meanings. It can mean, Look in the hashtable identified as <em>customer</em> and return the value associated with the key <em>Address</em>. But <em>$customer.Address</em> can also be referring to a method (references that refer to methods will be discussed in the next section); <em>$customer.Address</em> could be an abbreviated way of writing <em>$customer.getAddress()</em>. When your page is requested, Velocity will determine which of these two possibilities makes sense, and then return the appropriate value.</p> <h3 id="methods">Methods<a class="headerlink" href="#methods" title="Permanent link">¶</a></h3> <p>A method is defined in the Java code and is capable of doing something useful, like running a calculation or arriving at a decision. Methods are references that consist of a leading "$" character followed a VTL Identifier, followed by a VTL <em>Method Body</em>. A VTL Method Body consists of a VTL Identifier followed by an left parenthesis character ("("), followed by an optional parameter list, followed by right parenthesis character (")"). These are examples of valid method references in the VTL:</p> -<div class="codehilite"><pre>$customer.getAddress() -$purchase.getTotal() -$page.setTitle( "My Home Page" ) -$person.setAttributes( ["Strange", "Weird", "Excited"] ) +<div class="codehilite"><pre><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">getAddress</span><span class="p">()</span><span class="x"></span> +<span class="p">$</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">getTotal</span><span class="p">()</span><span class="x"></span> +<span class="p">$</span><span class="nv">page</span><span class="p">.</span><span class="nv">setTitle</span><span class="p">(</span> <span class="s2">"My Home Page"</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">person</span><span class="p">.</span><span class="nv">setAttributes</span><span class="p">(</span> <span class="p">[</span><span class="s2">"Strange"</span><span class="p">,</span> <span class="s2">"Weird"</span><span class="p">,</span> <span class="s2">"Excited"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> </pre></div> <p>The first two examples -- <em>$customer.getAddress()</em> and <em>$purchase.getTotal()</em> -- may look similar to those used in the Properties section above, <em>$customer.Address</em> and <em>$purchase.Total</em>. If you guessed that these examples must be related some in some fashion, you are correct!</p> <p>VTL Properties can be used as a shorthand notation for VTL Methods. The Property <em>$customer.Address</em> has the exact same effect as using the Method <em>$customer.getAddress()</em>. It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.</p> <p>The shorthand notation can be used for the following Methods</p> -<div class="codehilite"><pre>$sun.getPlanets() -$annelid.getDirt() -$album.getPhoto() +<div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">getPlanets</span><span class="p">()</span><span class="x"></span> +<span class="p">$</span><span class="nv">annelid</span><span class="p">.</span><span class="nv">getDirt</span><span class="p">()</span><span class="x"></span> +<span class="p">$</span><span class="nv">album</span><span class="p">.</span><span class="nv">getPhoto</span><span class="p">()</span><span class="x"></span> </pre></div> <p>We might expect these methods to return the names of planets belonging to the sun, feed our earthworm, or get a photograph from an album. Only the long notation works for the following Methods.</p> -<div class="codehilite"><pre>$sun.getPlanet( ["Earth", "Mars", "Neptune"] ) -## Can't pass a parameter list with $sun.Planets +<div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">getPlanet</span><span class="p">(</span> <span class="p">[</span><span class="s2">"Earth"</span><span class="p">,</span> <span class="s2">"Mars"</span><span class="p">,</span> <span class="s2">"Neptune"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> +<span class="cp">##</span><span class="c"> Can't pass a parameter list with $sun.Planets</span><span class="x"></span> -$sisyphus.pushRock() -## Velocity assumes I mean $sisyphus.getRock() +<span class="p">$</span><span class="nv">sisyphus</span><span class="p">.</span><span class="nv">pushRock</span><span class="p">()</span><span class="x"></span> +<span class="cp">##</span><span class="c"> Velocity assumes I mean $sisyphus.getRock()</span><span class="x"></span> -$book.setTitle( "Homage to Catalonia" ) -## Can't pass a parameter +<span class="p">$</span><span class="nv">book</span><span class="p">.</span><span class="nv">setTitle</span><span class="p">(</span> <span class="s2">"Homage to Catalonia"</span> <span class="p">)</span><span class="x"></span> +<span class="cp">##</span><span class="c"> Can't pass a parameter</span><span class="x"></span> </pre></div> <p>All array references are treated as if they are fixed-length lists. This means that you can call java.util.List methods and properties on array references. So, if you have a reference to an array (let's say this one is a String[] with three values), you can do:</p> -<div class="codehilite"><pre>$myarray.isEmpty() or $myarray.empty - -$myarray.size() - -$myarray.get(2) - -$myarray.set(1, 'test') +<div class="codehilite"><pre><span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">isEmpty</span><span class="p">()</span><span class="x"> or </span><span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">empty</span><span class="x"></span> +<span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">size</span><span class="p">()</span><span class="x"></span> +<span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">get</span><span class="p">(</span><span class="m">2</span><span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">set</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="s1">'test'</span><span class="p">)</span><span class="x"></span> </pre></div> <p>Velocity also supports vararg methods. A method like <code>azpublic void setPlanets(String... planets)</code> or even just <code>public void setPlanets(String[] planets)</code> can now accept any number of arguments when called in a template.</p> -<div class="codehilite"><pre>$sun.setPlanets('Earth', 'Mars', 'Neptune') - -$sun.setPlanets('Mercury') - -$sun.setPlanets() -## Will just pass in an empty, zero-length array +<div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Earth'</span><span class="p">,</span> <span class="s1">'Mars'</span><span class="p">,</span> <span class="s1">'Neptune'</span><span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Mercury'</span><span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">()</span><span class="x"></span> +<span class="cp">##</span><span class="c"> Will just pass in an empty, zero-length array</span><span class="x"></span> </pre></div> @@ -504,62 +499,62 @@ $sun.setPlanets() <p>The final value resulting from each and every reference (whether variable, property, or method) is converted to a String object when it is rendered into the final output. If there is an object that represents <em>$foo</em> (such as an Integer object), then Velocity will call its <code>.toString()</code> method to resolve the object into a String.</p> <h3 id="index-notation">Index Notation<a class="headerlink" href="#index-notation" title="Permanent link">¶</a></h3> <p>Using the notation of the form <code>$foo[0]</code> can be used to access a given index of an object. This form is synonymous with calling the get(Object) method on a given object i.e, <code>$foo.get(0)</code>, and provides essentially a syntactic shorthand for such operations. Since this simply calls the get method all of the following are valid uses:</p> -<div class="codehilite"><pre>$foo[0] ## $foo takes in an Integer look up -$foo[$i] ## Using another reference as the index -$foo["bar"] ## Passing a string where $foo may be a Map +<div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x">[0] </span><span class="cp">##</span><span class="c"> $foo takes in an Integer look up</span><span class="x"></span> +<span class="p">$</span><span class="nv">foo</span><span class="x">[</span><span class="p">$</span><span class="nv">i</span><span class="x">] </span><span class="cp">##</span><span class="c"> Using another reference as the index </span><span class="x"></span> +<span class="p">$</span><span class="nv">foo</span><span class="x">["bar"] </span><span class="cp">##</span><span class="c"> Passing a string where $foo may be a Map</span><span class="x"></span> </pre></div> <p>The bracketed syntax also works with Java arrays since Velocity wraps arrays in an access object that provides a <code>get(Integer)</code> method which returns the specified element.</p> <p>The bracketed syntax is valid anywhere <code>.get</code> is valid, for example:</p> -<div class="codehilite"><pre>$foo.bar[1].junk -$foo.callMethod()[1] -$foo["apple"][4] +<div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="x">[1].junk</span> +<span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">callMethod</span><span class="p">()</span><span class="x">[1]</span> +<span class="p">$</span><span class="nv">foo</span><span class="x">["apple"][4]</span> </pre></div> <p>A reference can also be set using index notation, for example:</p> -<div class="codehilite"><pre>#set($foo[0] = 1) -#set($foo.bar[1] = 3) -#set($map["apple"] = "orange") +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span><span class="o">[</span><span class="m">0</span><span class="p">]</span> <span class="o">=</span> <span class="m">1</span><span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="o">[</span><span class="m">1</span><span class="p">]</span> <span class="o">=</span> <span class="m">3</span><span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">map</span><span class="o">[</span><span class="s2">"apple"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"orange"</span><span class="p">)</span><span class="x"></span> </pre></div> <p>The specified element is set with the given value. Velocity tries first the 'set' method on the element, then 'put' to make the assignment.</p> <h2 id="formal-reference-notation">Formal Reference Notation<a class="headerlink" href="#formal-reference-notation" title="Permanent link">¶</a></h2> <p>Shorthand notation for references was used for the examples listed above, but there is also a formal notation for references, which is demonstrated below:</p> -<div class="codehilite"><pre><span class="cp">${</span><span class="n">mudSlinger</span><span class="cp">}</span> -<span class="cp">${</span><span class="n">customer</span><span class="o">.</span><span class="n">Address</span><span class="cp">}</span> -<span class="cp">${</span><span class="n">purchase</span><span class="o">.</span><span class="n">getTotal</span><span class="p">()</span><span class="cp">}</span> +<div class="codehilite"><pre><span class="p">${</span><span class="nv">mudSlinger</span><span class="p">}</span><span class="x"></span> +<span class="p">${</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Address</span><span class="p">}</span><span class="x"></span> +<span class="p">${</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">getTotal</span><span class="p">()}</span><span class="x"></span> </pre></div> <p>In almost all cases you will use the shorthand notation for references, but in some cases the formal notation is required for correct processing.</p> <p>Suppose you were constructing a sentence on the fly where <em>$vice</em> was to be used as the base word in the noun of a sentence. The goal is to allow someone to choose the base word and produce one of the two following results: "Jack is a pyromaniac." or "Jack is a kleptomaniac.". Using the shorthand notation would be inadequate for this task. Consider the following example:</p> -<div class="codehilite"><pre>Jack is a $vicemaniac. +<div class="codehilite"><pre><span class="x">Jack is a </span><span class="p">$</span><span class="nv">vicemaniac</span><span class="x">.</span> </pre></div> <p>There is ambiguity here, and Velocity assumes that <em>$vicemaniac</em>, not <em>$vice</em>, is the Identifier that you mean to use. Finding no value for <em>$vicemaniac</em>, it will return <em>$vicemaniac</em>. Using formal notation can resolve this problem.</p> -<div class="codehilite"><pre>Jack is a <span class="cp">${</span><span class="n">vice</span><span class="cp">}</span>maniac. +<div class="codehilite"><pre><span class="x">Jack is a </span><span class="p">${</span><span class="nv">vice</span><span class="p">}</span><span class="x">maniac.</span> </pre></div> <p>Now Velocity knows that <em>$vice</em>, not <em>$vicemaniac</em>, is the reference. Formal notation is often useful when references are directly adjacent to text in a template.</p> <h2 id="quiet-reference-notation">Quiet Reference Notation<a class="headerlink" href="#quiet-reference-notation" title="Permanent link">¶</a></h2> <p>When Velocity encounters an undefined reference, its normal behavior is to output the image of the reference. For example, suppose the following reference appears as part of a VTL template.</p> -<div class="codehilite"><pre><input type="text" name="email" value="$email"/> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="nv">email</span><span class="s">"</span><span class="p">/></span> </pre></div> <p>When the form initially loads, the variable reference <em>$email</em> has no value, but you prefer a blank text field to one with a value of "$email". Using the quiet reference notation circumvents Velocity's normal behavior; instead of using <em>$email</em> in the VTL you would use <em>$!email</em>. So the above example would look like the following:</p> -<div class="codehilite"><pre><input type="text" name="email" value="$!email"/> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$!</span><span class="nv">email</span><span class="s">"</span><span class="p">/></span> </pre></div> <p>Now when the form is initially loaded and <em>$email</em> still has no value, an empty string will be output instead of "$email".</p> <p>Formal and quiet reference notation can be used together, as demonstrated below.</p> -<div class="codehilite"><pre><input type="text" name="email" value="$!{email}"/> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$!{</span><span class="nv">email</span><span class="p">}</span><span class="s">"</span><span class="p">/></span> </pre></div> @@ -575,46 +570,46 @@ $foo["apple"][4] <p>Also, The following statements show examples in which Velocity will throw an exception when attempting to call methods or properties that do not exist. In these examples $bar contains an object that defines a property 'foo' which returns a string, and 'retnull' which returns null.</p> -<div class="codehilite"><pre>$bar.bogus ## $bar does not provide property bogus, Exception -$bar.foo.bogus ## $bar.foo does not provide property bogus, Exception -$bar.retnull.bogus ## cannot call a property on null, Exception</pre> +<div class="codehilite"><pre><span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> $bar does not provide property bogus, Exception</span><span class="x"></span> +<span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> $bar.foo does not provide property bogus, Exception</span><span class="x"></span> +<span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">retnull</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> cannot call a property on null, Exception</pre></span><span class="x"></span> </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> -<div class="codehilite"><pre>#if ($foo)#end ## False -#if ( ! $foo)#end ## True -#if ($foo && $foo.bar)#end ## False and $foo.bar will not be evaluated -#if ($foo && $foo == "bar")#end ## False and $foo == "bar" wil not be evaluated -#if ($foo1 || $foo2)#end ## False $foo1 and $foo2 are not defined +<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> +<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="o">==</span> <span class="s2">"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" wil not be evaluated</span><span class="x"></span> +<span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo1</span> <span class="o">||</span> <span class="p">$</span><span class="nv">foo2</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 $foo1 and $foo2 are not defined</span><span class="x"></span> </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>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>this is $foo ## throws an exception because $foo is null -this is $!foo ## renders to "this is " without an exception -this is $!bogus ## bogus is not in the context so throws an exception +<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> +<span class="x">this is </span><span class="p">$!</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> bogus is not in the context so throws an exception</span><span class="x"></span> </pre></div> <h2 id="case-substitution">Case Substitution<a class="headerlink" href="#case-substitution" title="Permanent link">¶</a></h2> <p>Now that you are familiar with references, you can begin to apply them effectively in your templates. Velocity references take advantage of some Java principles that template designers will find easy to use. For example:</p> -<div class="codehilite"><pre><span class="nv">$foo</span> +<div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"></span> -<span class="nv">$foo.getBar</span>() -## is the same as -<span class="nv">$foo.Bar</span> - -<span class="nv">$data.setUser</span>("jon") -## is the same as -#set( <span class="nv">$data.User</span> = "jon" ) - -<span class="nv">$data.getRequest</span>().getServerName() -## is the same as -<span class="nv">$data.Request.ServerName</span> -## is the same as -<span class="cp">${</span><span class="n">data</span><span class="o">.</span><span class="n">Request</span><span class="o">.</span><span class="n">ServerName</span><span class="cp">}</span> +<span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">getBar</span><span class="p">()</span><span class="x"></span> +<span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> +<span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">Bar</span><span class="x"></span> + +<span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">setUser</span><span class="p">(</span><span class="s2">"jon"</span><span class="p">)</span><span class="x"></span> +<span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">User</span> <span class="o">=</span> <span class="s2">"jon"</span> <span class="p">)</span><span class="x"></span> + +<span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">getRequest</span><span class="p">().</span><span class="nv">getServerName</span><span class="p">()</span><span class="x"></span> +<span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> +<span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">Request</span><span class="p">.</span><span class="nv">ServerName</span><span class="x"></span> +<span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> +<span class="p">${</span><span class="nv">data</span><span class="p">.</span><span class="nv">Request</span><span class="p">.</span><span class="nv">ServerName</span><span class="p">}</span><span class="x"></span> </pre></div> @@ -635,8 +630,8 @@ this is $!bogus ## bogus is not in the c <h3 id="set">Set<a class="headerlink" href="#set" title="Permanent link">¶</a></h3> <p>The <em>#set</em> directive is used for setting the value of a reference. A value can be assigned to either a variable reference or a property reference, and this occurs in brackets, as demonstrated:</p> -<div class="codehilite"><pre>#set( $primate = "monkey" ) -#set( $customer.Behavior = $primate ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">primate</span> <span class="o">=</span> <span class="s2">"monkey"</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Behavior</span> <span class="o">=</span> <span class="p">$</span><span class="nv">primate</span> <span class="p">)</span><span class="x"></span> </pre></div> @@ -651,32 +646,32 @@ this is $!bogus ## bogus is not in the c <li>Map</li> </ul> <p>These examples demonstrate each of the aforementioned types:</p> -<div class="codehilite"><pre>#set( $monkey = $bill ) ## variable reference -#set( $monkey.Friend = "monica" ) ## string literal -#set( $monkey.Blame = $whitehouse.Leak ) ## property reference -#set( $monkey.Plan = $spindoctor.weave($web) ) ## method reference -#set( $monkey.Number = 123 ) ##number literal -#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList -#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## Map +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bill</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> variable reference</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Friend</span> <span class="o">=</span> <span class="s2">"monica"</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> string literal</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Blame</span> <span class="o">=</span> <span class="p">$</span><span class="nv">whitehouse</span><span class="p">.</span><span class="nv">Leak</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> property reference</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Plan</span> <span class="o">=</span> <span class="p">$</span><span class="nv">spindoctor</span><span class="p">.</span><span class="nv">weave</span><span class="p">($</span><span class="nv">web</span><span class="p">)</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> method reference</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Number</span> <span class="o">=</span> <span class="m">123</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c">number literal</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Say</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"Not"</span><span class="p">,</span> <span class="p">$</span><span class="nv">my</span><span class="p">,</span> <span class="s2">"fault"</span><span class="p">]</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> ArrayList</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Map</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"banana"</span> <span class="p">:</span> <span class="s2">"good"</span><span class="p">,</span> <span class="s2">"roast beef"</span> <span class="p">:</span> <span class="s2">"bad"</span><span class="p">})</span><span class="x"> </span><span class="cp">##</span><span class="c"> Map</span><span class="x"></span> </pre></div> <p>NOTE: For the ArrayList example the elements defined with the [..] operator are accessible using the methods defined in the ArrayList class. So, for example, you could access the first element above using $monkey.Say.get(0).</p> <p>Similarly, for the Map example, the elements defined within the { } operator are accessible using the methods defined in the Map class. So, for example, you could access the first element above using $monkey.Map.get("banana") to return a String 'good', or even $monkey.Map.banana to return the same value.</p> <p>The RHS can also be a simple arithmetic expression:</p> -<div class="codehilite"><pre>#set( $value = $foo + 1 ) -#set( $value = $bar - 1 ) -#set( $value = $foo * $bar ) -#set( $value = $foo / $bar ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">+</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">-</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">*</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">/</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> </pre></div> <p>If the RHS is a property or method reference that evaluates to <em>null</em>, it will <b>not</b> be assigned to the LHS. Depending on how Velocity is configured, it is usually not possible to remove an existing reference from the context via this mechanism. (Note that this can be permitted by changing one of the Velocity configuration properties). This can be confusing for newcomers to Velocity. For example:</p> -<div class="codehilite"><pre>#set( $result = $query.criteria("name") ) -The result of the first query is $result +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span class="nv">query</span><span class="p">.</span><span class="nv">criteria</span><span class="p">(</span><span class="s2">"name"</span><span class="p">)</span> <span class="p">)</span><span class="x"></span> +<span class="x">The result of the first query is </span><span class="p">$</span><span class="nv">result</span><span class="x"></span> -#set( $result = $query.criteria("address") ) -The result of the second query is $result +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span class="nv">query</span><span class="p">.</span><span class="nv">criteria</span><span class="p">(</span><span class="s2">"address"</span><span class="p">)</span> <span class="p">)</span><span class="x"></span> +<span class="x">The result of the second query is </span><span class="p">$</span><span class="nv">result</span><span class="x"></span> </pre></div> @@ -688,44 +683,44 @@ The result of the second query is bill <p>This tends to confuse newcomers who construct <em>#foreach</em> loops that attempt to <em>#set</em> a reference via a property or method reference, then immediately test that reference with an <em>#if</em> directive. For example:</p> -<div class="codehilite"><pre>#set( $criteria = ["name", "address"] ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">criteria</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"address"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> -#foreach( $criterion in $criteria ) +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">criterion</span> <span class="o">in</span> <span class="p">$</span><span class="nv">criteria</span> <span class="p">)</span><span class="x"></span> - #set( $result = $query.criteria($criterion) ) +<span class="x"> </span><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span class="nv">query</span><span class="p">.</span><span class="nv">criteria</span><span class="p">($</span><span class="nv">criterion</span><span class="p">)</span> <span class="p">)</span><span class="x"></span> - #if( $result ) - Query was successful - #end +<span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="p">)</span><span class="x"></span> +<span class="x"> Query was successful</span> +<span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> -#end +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>In the above example, it would not be wise to rely on the evaluation of <em>$result</em> to determine if a query was successful. After <em>$result</em> has been <em>#set</em> (added to the context), it cannot be set back to <em>null</em> (removed from the context). The details of the <em>#if</em> and <em>#foreach</em> directives are covered later in this document.</p> <p>One solution to this would be to pre-set <em>$result</em> to <em>false</em>. Then if the <em>$query.criteria()</em> call fails, you can check.</p> -<div class="codehilite"><pre>#set( $criteria = ["name", "address"] ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">criteria</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"address"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> -#foreach( $criterion in $criteria ) +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">criterion</span> <span class="o">in</span> <span class="p">$</span><span class="nv">criteria</span> <span class="p">)</span><span class="x"></span> - #set( $result = false ) - #set( $result = $query.criteria($criterion) ) +<span class="x"> </span><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="o">=</span> <span class="nf">false</span> <span class="p">)</span><span class="x"></span> +<span class="x"> </span><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="o">=</span> <span class="p">$</span><span class="nv">query</span><span class="p">.</span><span class="nv">criteria</span><span class="p">($</span><span class="nv">criterion</span><span class="p">)</span> <span class="p">)</span><span class="x"></span> - #if( $result ) - Query was successful - #end +<span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">result</span> <span class="p">)</span><span class="x"></span> +<span class="x"> Query was successful</span> +<span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> -#end +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>Unlike some of the other Velocity directives, the <em>#set</em> directive does not have an <em>#end</em> statement.</p> <h4 id="literals">Literals<a class="headerlink" href="#literals" title="Permanent link">¶</a></h4> <p>When using the <em>#set</em> directive, string literals that are enclosed in double quote characters will be parsed and rendered, as shown:</p> -<div class="codehilite"><pre>#set( $directoryRoot = "www" ) -#set( $templateName = "index.vm" ) -#set( $template = "$directoryRoot/$templateName" ) -$template +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">directoryRoot</span> <span class="o">=</span> <span class="s2">"www"</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">templateName</span> <span class="o">=</span> <span class="s2">"index.vm"</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">template</span> <span class="o">=</span> <span class="s2">"$directoryRoot/$templateName"</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">template</span><span class="x"></span> </pre></div> @@ -735,10 +730,10 @@ $template <p>However, when the string literal is enclosed in single quote characters, it will not be parsed:</p> -<div class="codehilite"><pre>#set( $foo = "bar" ) -$foo -#set( $blargh = '$foo' ) -$blargh +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"bar"</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">foo</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">blargh</span> <span class="o">=</span> <span class="s1">'$foo'</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">blargh</span><span class="x"></span> </pre></div> @@ -750,11 +745,11 @@ $foo <p>By default, this feature of using single quotes to render unparsed text is available in Velocity. This default can be changed by editing <code>velocity.properties</code> such that <code>stringliterals.interpolate=false</code>.</p> <p>Alternately, the <em>#[[</em>don't parse me!<em>]]#</em> syntax allows the template designer to easily use large chunks of uninterpreted and unparsed content in VTL code. This can be especially useful in place of <a href="#EscapingVTLDirectives">escaping</a> multiple directives or escaping sections which have content that would otherwise be invalid (and thus unparseable) VTL.</p> -<div class="codehilite"><pre>#[[ -#foreach ($woogie in $boogie) - nothing will happen to $woogie -#end -]]# +<div class="codehilite"><pre><span class="err">#</span><span class="x">[[</span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p"> ($</span><span class="nv">woogie</span> <span class="o">in</span> <span class="p">$</span><span class="nv">boogie</span><span class="p">)</span><span class="x"></span> +<span class="x"> nothing will happen to </span><span class="p">$</span><span class="nv">woogie</span><span class="x"></span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> +<span class="x">]]</span><span class="err">#</span><span class="x"></span> </pre></div> @@ -768,9 +763,9 @@ $foo <h3 id="conditionals">Conditionals<a class="headerlink" href="#conditionals" title="Permanent link">¶</a></h3> <h4 id="if-elseif-else">If / ElseIf / Else<a class="headerlink" href="#if-elseif-else" title="Permanent link">¶</a></h4> <p>The <em>#if</em> directive in Velocity allows for text to be included when the web page is generated, on the conditional that the if statement is true. For example:</p> -<div class="codehilite"><pre>#if( $foo ) - <span class="nt"><strong></span>Velocity!<span class="nt"></strong></span> -#end +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> +<span class="x"> <strong>Velocity!</strong></span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> @@ -785,59 +780,59 @@ $foo <p>Remember that the Velocity context only contains Objects, so when we say 'boolean', it will be represented as a Boolean (the class). This is true even for methods that return <code>boolean</code> - the introspection infrastructure will return a <code>Boolean</code> of the same logical value.</p> <p>The content between the <em>#if</em> and the <em>#end</em> statements become the output if the evaluation is true. In this case, if <em>$foo</em> is true, the output will be: "Velocity!". Conversely, if <em>$foo</em> has a null value, or if it is a boolean false, the statement evaluates as false, and there is no output.</p> <p>An <em>#elseif</em> or <em>#else</em> element can be used with an <em>#if</em> element. Note that the Velocity Templating Engine will stop at the first expression that is found to be true. In the following example, suppose that <em>$foo</em> has a value of 15 and <em>$bar</em> has a value of 6.</p> -<div class="codehilite"><pre>#if( $foo < 10 ) - **Go North** -#elseif( $foo == 10 ) - **Go East** -#elseif( $bar == 6 ) - **Go South** -#else - **Go West** -#end +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o"><</span> <span class="m">10</span> <span class="p">)</span><span class="x"></span> +<span class="x"> **Go North**</span> +<span class="cp">#</span><span class="nf">elseif</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">==</span> <span class="m">10</span> <span class="p">)</span><span class="x"></span> +<span class="x"> **Go East**</span> +<span class="cp">#</span><span class="nf">elseif</span><span class="p">(</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">==</span> <span class="m">6</span> <span class="p">)</span><span class="x"></span> +<span class="x"> **Go South**</span> +<span class="cp">#</span><span class="nf">else</span><span class="x"></span> +<span class="x"> **Go West**</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>In this example, <em>$foo</em> is greater than 10, so the first two comparisons fail. Next <em>$bar</em> is compared to 6, which is true, so the output is <strong>Go South</strong>.</p> <h4 id="relational-and-logical-operators">Relational and Logical Operators<a class="headerlink" href="#relational-and-logical-operators" title="Permanent link">¶</a></h4> <p>Velocity uses the equivalent operator to determine the relationships between variables. Here is a simple example to illustrate how the equivalent operator is used.</p> -<div class="codehilite"><pre>#set ($foo = "deoxyribonucleic acid") -#set ($bar = "ribonucleic acid") +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"deoxyribonucleic acid"</span><span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p"> ($</span><span class="nv">bar</span> <span class="o">=</span> <span class="s2">"ribonucleic acid"</span><span class="p">)</span><span class="x"></span> -#if ($foo == $bar) - In this case it's clear they aren't equivalent. So... -#else - They are not equivalent and this will be the output. -#end +<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">bar</span><span class="p">)</span><span class="x"></span> +<span class="x"> In this case it's clear they aren't equivalent. So...</span> +<span class="cp">#</span><span class="nf">else</span><span class="x"></span> +<span class="x"> They are not equivalent and this will be the output.</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>Note that the semantics of <em>==</em> are slightly different than Java where <em>==</em> can only be used to test object equality. In Velocity the equivalent operator can be used to directly compare numbers, strings, or objects. When the objects are of different classes, the string representations are obtained by calling <code>toString()</code> for each object and then compared.</p> <p>Velocity has logical AND, OR and NOT operators as well. Below are examples demonstrating the use of the logical AND, OR and NOT operators.</p> -<div class="codehilite"><pre>## logical AND +<div class="codehilite"><pre><span class="cp">##</span><span class="c"> logical AND</span><span class="x"></span> -#if( $foo && $bar ) - ** This AND that** -#end +<span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">&&</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> +<span class="x"> ** This AND that**</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>The <em>#if()</em> directive will only evaluate to true if both <em>$foo</em> and <em>$bar</em> are true. If <em>$foo</em> is false, the expression will evaluate to false; <em>$bar</em> will not be evaluated. If <em>$foo</em> is true, the Velocity Templating Engine will then check the value of <em>$bar</em>; if <em>$bar</em> is true, then the entire expression is true and <strong>This AND that</strong> becomes the output. If <em>$bar</em> is false, then there will be no output as the entire expression is false.</p> <p>Logical OR operators work the same way, except only one of the references need evaluate to true in order for the entire expression to be considered true. Consider the following example.</p> -<div class="codehilite"><pre>## logical OR +<div class="codehilite"><pre><span class="cp">##</span><span class="c"> logical OR</span><span class="x"></span> -#if( $foo || $bar ) - **This OR That** -#end +<span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">||</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> +<span class="x"> **This OR That**</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>If <em>$foo</em> is true, the Velocity Templating Engine has no need to look at <em>$bar</em>; whether <em>$bar</em> is true or false, the expression will be true, and <strong>This OR That</strong> will be output. If <em>$foo</em> is false, however, <em>$bar</em> must be checked. In this case, if <em>$bar</em> is also false, the expression evaluates to false and there is no output. On the other hand, if <em>$bar</em> is true, then the entire expression is true, and the output is <strong>This OR That</strong></p> <p>With logical NOT operators, there is only one argument :</p> -<div class="codehilite"><pre>##logical NOT +<div class="codehilite"><pre><span class="cp">##</span><span class="c">logical NOT</span><span class="x"></span> -#if( !$foo ) - **NOT that** -#end +<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="x"></span> +<span class="x"> **NOT that**</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> @@ -851,31 +846,31 @@ $foo <h3 id="loops">Loops<a class="headerlink" href="#loops" title="Permanent link">¶</a></h3> <h4 id="foreach-loop">Foreach Loop<a class="headerlink" href="#foreach-loop" title="Permanent link">¶</a></h4> <p>The <em>#foreach</em> element allows for looping. For example:</p> -<div class="codehilite"><pre><span class="nt"><ul></span> -#foreach( $product in $allProducts ) - <span class="nt"><li></span>$product<span class="nt"></li></span> -#end -<span class="nt"></ul></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">ul</span><span class="p">></span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">product</span> <span class="o">in</span> <span class="p">$</span><span class="nv">allProducts</span> <span class="p">)</span> + <span class="p"><</span><span class="nt">li</span><span class="p">>$</span><span class="nv">product</span><span class="p"></</span><span class="nt">li</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> +<span class="p"></</span><span class="nt">ul</span><span class="p">></span> </pre></div> <p>This <em>#foreach</em> loop causes the <em>$allProducts</em> list (the object) to be looped over for all of the products (targets) in the list. Each time through the loop, the value from <em>$allProducts</em> is placed into the <em>$product</em> variable.</p> <p>The contents of the <em>$allProducts</em> variable is a Vector, a Hashtable or an Array. The value assigned to the <em>$product</em> variable is a Java Object and can be referenced from a variable as such. For example, if <em>$product</em> was really a Product class in Java, its name could be retrieved by referencing the <em>$product.Name</em> method (ie: <em>$Product.getName()</em>).</p> <p>Lets say that <em>$allProducts</em> is a Hashtable. If you wanted to retrieve the key values for the Hashtable as well as the objects within the Hashtable, you can use code like this:</p> -<div class="codehilite"><pre><span class="nt"><ul></span> -#foreach( $key in $allProducts.keySet() ) - <span class="nt"><li></span>Key: $key -> Value: $allProducts.get($key)<span class="nt"></li></span> -#end -<span class="nt"></ul></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">ul</span><span class="p">></span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">key</span> <span class="o">in</span> <span class="p">$</span><span class="nv">allProducts</span><span class="p">.</span><span class="nv">keySet</span><span class="p">()</span> <span class="p">)</span> + <span class="p"><</span><span class="nt">li</span><span class="p">></span>Key: <span class="p">$</span><span class="nv">key</span> -> Value: <span class="p">$</span><span class="nv">allProducts</span><span class="p">.</span><span class="nv">get</span><span class="p">($</span><span class="nv">key</span><span class="p">)</</span><span class="nt">li</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> +<span class="p"></</span><span class="nt">ul</span><span class="p">></span> </pre></div> <p>Velocity provides an easy way to get the loop counter so that you can do something like the following:</p> -<div class="codehilite"><pre><span class="nt"><table></span> -#foreach( $customer in $customerList ) - <span class="nt"><tr><td></span>$foreach.count<span class="nt"></td><td></span>$customer.Name<span class="nt"></td></tr></span> -#end -<span class="nt"></table></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">table</span><span class="p">></span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span> <span class="o">in</span> <span class="p">$</span><span class="nv">customerList</span> <span class="p">)</span> + <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">>$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">count</span><span class="p"></</span><span class="nt">td</span><span class="p">><</span><span class="nt">td</span><span class="p">>$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span><span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> +<span class="p"></</span><span class="nt">table</span><span class="p">></span> </pre></div> @@ -888,30 +883,30 @@ $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># The maximum allowed number of loops. -directive.foreach.maxloops = -1 +<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> </pre></div> <p>If you want to stop looping in a foreach from within your template, you can now use the #break directive to stop looping at any time:</p> -<div class="codehilite"><pre>## list first 5 customers only -#foreach( $customer in $customerList ) - #if( $foreach.count > 5 ) - #break - #end - $customer.Name -#end +<div class="codehilite"><pre><span class="cp">##</span><span class="c"> list first 5 customers only</span><span class="x"></span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span> <span class="o">in</span> <span class="p">$</span><span class="nv">customerList</span> <span class="p">)</span><span class="x"></span> +<span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">count</span> <span class="o">></span> <span class="m">5</span> <span class="p">)</span><span class="x"></span> +<span class="x"> </span><span class="cp">#</span><span class="nf">break</span><span class="x"></span> +<span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> +<span class="x"> </span><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span><span class="x"></span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <h3 id="include">Include<a class="headerlink" href="#include" title="Permanent link">¶</a></h3> <p>The <em>#include</em> script element allows the template designer to import a local file, which is then inserted into the location where the <em>#include</em> directive is defined. The contents of the file are not rendered through the template engine. For security reasons, the file to be included may only be under TEMPLATE_ROOT.</p> -<div class="codehilite"><pre>#include( "one.txt" ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"one.txt"</span> <span class="p">)</span><span class="x"></span> </pre></div> <p>The file to which the <em>#include</em> directive refers is enclosed in quotes. If more than one file will be included, they should be separated by commas.</p> -<div class="codehilite"><pre>#include( "one.gif","two.txt","three.htm" ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"one.gif"</span><span class="p">,</span><span class="s2">"two.txt"</span><span class="p">,</span><span class="s2">"three.htm"</span> <span class="p">)</span><span class="x"></span> </pre></div> @@ -922,27 +917,27 @@ directive.foreach.maxloops = -1 <h3 id="parse">Parse<a class="headerlink" href="#parse" title="Permanent link">¶</a></h3> <p>The <em>#parse</em> script element allows the template designer to import a local file that contains VTL. Velocity will parse the VTL and render the template specified.</p> -<div class="codehilite"><pre>#parse( "me.vm" ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">parse</span><span class="p">(</span> <span class="s2">"me.vm"</span> <span class="p">)</span><span class="x"></span> </pre></div> <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> -<div class="codehilite"><pre>Count down. -#set( $count = 8 ) -#parse( "parsefoo.vm" ) -All done with dofoo.vm! +<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> +<span class="x">All done with dofoo.vm!</span> </pre></div> <p>It would reference the template <code>parsefoo.vm</code>, which might contain the following VTL:</p> -<div class="codehilite"><pre>$count -#set( $count = $count - 1 ) -#if( $count > 0 ) - #parse( "parsefoo.vm" ) -#else - All done with parsefoo.vm! -#end +<div class="codehilite"><pre><span class="p">$</span><span class="nv">count</span><span class="x"></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="p">$</span><span class="nv">count</span> <span class="o">-</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">count</span> <span class="o">></span> <span class="m">0</span> <span class="p">)</span><span class="x"></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> +<span class="cp">#</span><span class="nf">else</span><span class="x"></span> +<span class="x"> All done with parsefoo.vm!</span> +<span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> @@ -955,86 +950,86 @@ All done with dofoo.vm! <h3 id="evaluate">Evaluate<a class="headerlink" href="#evaluate" title="Permanent link">¶</a></h3> <p>The <em>#evaluate</em> directive can be used to dynamically evaluate VTL. This allows the template to evaluate a string that is created at render time. Such a string might be used to internationalize the template or to include parts of a template from a database.</p> <p>The example below will display <code>abc</code>.</p> -<div class="codehilite"><pre>#set($source1 = "abc") -#set($select = "1") -#set($dynamicsource = "$source$select") -## $dynamicsource is now the string '$source1' -#evaluate($dynamicsource) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">source1</span> <span class="o">=</span> <span class="s2">"abc"</span><span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">select</span> <span class="o">=</span> <span class="s2">"1"</span><span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">dynamicsource</span> <span class="o">=</span> <span class="s2">"$source$select"</span><span class="p">)</span><span class="x"></span> +<span class="cp">##</span><span class="c"> $dynamicsource is now the string '$source1'</span><span class="x"></span> +<span class="cp">#</span><span class="nf">evaluate</span><span class="p">($</span><span class="nv">dynamicsource</span><span class="p">)</span><span class="x"></span> </pre></div> <h3 id="define">Define<a class="headerlink" href="#define" title="Permanent link">¶</a></h3> <p>The <em>#define</em> directive lets one assign a block of VTL to a reference.</p> <p>The example below will display <code>Hello World!</code>.</p> -<div class="codehilite"><pre>#define( $block )Hello $who#end -#set( $who = 'World!' ) -$block +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">define</span><span class="p">(</span> <span class="p">$</span><span class="nv">block</span> <span class="p">)</span><span class="x">Hello </span><span class="p">$</span><span class="nv">who</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">who</span> <span class="o">=</span> <span class="s1">'World!'</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">block</span><span class="x"></span> </pre></div> <h3 id="velocimacros">Velocimacros<a class="headerlink" href="#velocimacros" title="Permanent link">¶</a></h3> <p>The <em>#macro</em> script element allows template designers to define a repeated segment of a VTL template. Velocimacros are very useful in a wide range of scenarios both simple and complex. This Velocimacro, created for the sole purpose of saving keystrokes and minimizing typographic errors, provides an introduction to the concept of Velocimacros.</p> -<div class="codehilite"><pre>#macro( d ) -<span class="nt"><tr><td></td></tr></span> -#end +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">d</span> <span class="p">)</span> +<span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> </pre></div> <p>The Velocimacro being defined in this example is <em>d</em>, and it can be called in a manner analogous to any other VTL directive:</p> -<div class="codehilite"><pre>#d() +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">d</span><span class="p">()</span><span class="x"></span> </pre></div> <p>When this template is called, Velocity would replace <em>#d()</em> with a row containing a single, empty data cell. If we want to put something in that cell, we can alter the macro to allow for a body:</p> -<div class="codehilite"><pre>#macro( d ) -<span class="nt"><tr><td></span>$!bodyContent<span class="nt"></td></tr></span> -#end +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">d</span> <span class="p">)</span> +<span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">>$!</span><span class="nv">bodyContent</span><span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> </pre></div> <p>Now, if we call the macro just a bit differently, using #@ before the name and providing a body and #end to the call, then Velocity will render the body when it gets to the $!bodyContent:</p> -<div class="codehilite"><pre>#@d()Hello!#end +<div class="codehilite"><pre><span class="err">#</span><span class="x">@d()Hello!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> </pre></div> <p>You can still call the macro as you did before, and since we used the silent reference notation for the body reference ($!bodyContent instead of $bodyContent), it will still render a row with a single, empty data cell.</p> <p>A Velocimacro can also take any number of arguments -- even zero arguments, as demonstrated in the first example, is an option -- but when the Velocimacro is invoked, it must be called with the same number of arguments with which it was defined. Many Velocimacros are more involved than the one defined above. Here is a Velocimacro that takes two arguments, a color and an array.</p> -<div class="codehilite"><pre>#macro( tablerows $color $somelist ) -#foreach( $something in $somelist ) - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">$color</span><span class="nt">></span>$something<span class="nt"></td></tr></span> -#end -#end +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">tablerows</span> <span class="p">$</span><span class="nv">color</span> <span class="p">$</span><span class="nv">somelist</span> <span class="p">)</span> +<span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">something</span> <span class="o">in</span> <span class="p">$</span><span class="nv">somelist</span> <span class="p">)</span> + <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="p">$</span><span class="nv">color</span><span class="err">></span><span class="p">$</span><span class="nv">something</span><span class="s"></td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> +<span class="cp">#</span><span class="nf">end</span> +<span class="cp">#</span><span class="nf">end</span> </pre></div> <p>The Velocimacro being defined in this example, <em>tablerows</em>, takes two arguments. The first argument takes the place of <em>$color</em>, and the second argument takes the place of <em>$somelist</em>.</p> <p>Anything that can be put into a VTL template can go into the body of a Velocimacro. The <em>tablerows</em> Velocimacro is a <em>foreach</em> statement. There are two <em>#end</em> statements in the definition of the <em>#tablerows</em> Velocimacro; the first belongs to the <em>#foreach</em>, the second ends the Velocimacro definition.</p> -<div class="codehilite"><pre>#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] ) -#set( $color = "blue" ) -<span class="nt"><table></span> - #tablerows( $color $greatlakes ) -<span class="nt"></table></span> +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">greatlakes</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"Superior"</span><span class="p">,</span><span class="s2">"Michigan"</span><span class="p">,</span><span class="s2">"Huron"</span><span class="p">,</span><span class="s2">"Erie"</span><span class="p">,</span><span class="s2">"Ontario"</span><span class="p">]</span> <span class="p">)</span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">color</span> <span class="o">=</span> <span class="s2">"blue"</span> <span class="p">)</span> +<span class="p"><</span><span class="nt">table</span><span class="p">></span> + <span class="cp">#</span><span class="nf">tablerows</span><span class="p">(</span> <span class="p">$</span><span class="nv">color</span> <span class="p">$</span><span class="nv">greatlakes</span> <span class="p">)</span> +<span class="p"></</span><span class="nt">table</span><span class="p">></span> </pre></div> <p>Notice that <em>$greatlakes</em> takes the place of <em>$somelist</em>. When the <em>#tablerows</em> Velocimacro is called in this situation, the following output is generated:</p> -<div class="codehilite"><pre><span class="nt"><table></span> - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"blue"</span><span class="nt">></span>Superior<span class="nt"></td></tr></span> - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"blue"</span><span class="nt">></span>Michigan<span class="nt"></td></tr></span> - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"blue"</span><span class="nt">></span>Huron<span class="nt"></td></tr></span> - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"blue"</span><span class="nt">></span>Erie<span class="nt"></td></tr></span> - <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"blue"</span><span class="nt">></span>Ontario<span class="nt"></td></tr></span> -<span class="nt"></table></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">table</span><span class="p">></span>
[... 458 lines stripped ...]
