geirm 01/10/19 04:14:35
Modified: xdocs Tag: VEL_1_2_BRANCH developer-guide.xml
user-guide.xml
docs Tag: VEL_1_2_BRANCH developer-guide.html
user-guide.html
Log:
updated users guide to be current with head, and added the
VM autoload info to users and dev
Revision Changes Path
No revision
No revision
1.57.2.1 +12 -0 jakarta-velocity/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
retrieving revision 1.57
retrieving revision 1.57.2.1
diff -u -r1.57 -r1.57.2.1
--- developer-guide.xml 2001/09/26 11:45:00 1.57
+++ developer-guide.xml 2001/10/19 11:14:34 1.57.2.1
@@ -1902,6 +1902,18 @@
</p>
<p>
+<code>velocimacro.library.autoreload = false</code><br/>
+Controls Velocimacro library autoloading. 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>
<strong>String Interpolation</strong>
</p>
1.47.2.1 +216 -14 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.47
retrieving revision 1.47.2.1
diff -u -r1.47 -r1.47.2.1
--- user-guide.xml 2001/07/24 10:27:07 1.47
+++ user-guide.xml 2001/10/19 11:14:34 1.47.2.1
@@ -65,6 +65,7 @@
<li><a href="#Range Operator">Range Operator</a></li>
<li><a href="#Advanced Issues: Escaping and !">Advanced Issues: Escaping
and
!</a></li>
+ <li><a href="#Velocimacro Miscellany">Velocimacro Miscellany</a></li>
</ol>
</li>
<li><a href="#Feedback">Feedback</a></li>
@@ -858,9 +859,7 @@
<p>
Unlike some of the other Velocity directives, the <em>#set</em>
- directive does not have an <em>#end</em> statement. Instead, the
- left bracket marks the beginning and the right bracket marks the end
- of an assignment.
+ directive does not have an <em>#end</em> statement.
</p>
<a name="String Literals"><strong>String Literals</strong></a>
@@ -994,8 +993,7 @@
]]></source>
<p>
- Two kinds of logical operators, logical AND and logical OR, are
- expected to be added to Velocity soon. Below is an example of an
+ Velocity has logical AND and OR operators as well. Below is an example of an
if statement using logical AND.
</p>
@@ -1013,7 +1011,7 @@
Engine will then check the value of <em>$bar</em>; if
<em>$bar</em> is true, then the entire expression is true and
<strong>Velocity Rocks!</strong> becomes the output. If
- <em>$bar</em> is false, then there will be no output; the entire
+ <em>$bar</em> is false, then there will be no output as the entire
expression is false.
</p>
@@ -1550,8 +1548,14 @@
]]></source>
<p>
- If <em>$jazz</em> is true, the output is <em>Vyacheslav Ganelin</em>; if
- <em>$jazz</em> is false, there is no output. Escaping script elements
+ If <em>$jazz</em> is true, the output is
+ </p>
+<source><![CDATA[
+Vyacheslav Ganelin
+]]></source>
+
+ <p>
+ If <em>$jazz</em> is false, there is no output. Escaping script elements
alters the output. Consider the following case:
</p>
@@ -1562,9 +1566,19 @@
]]></source>
<p>
- Whether <em>$jazz</em> is true or false, the output will be "#if(
- $jazz ) Vyacheslav Ganelin #end"; in fact, because all script elements
- are escaped the truth of <em>$jazz</em> is never checked. Suppose
+ Whether <em>$jazz</em> is true or false, the output will be
+ </p>
+
+ <source><![CDATA[
+ #if($ jazz )
+ Vyacheslav Ganelin
+ #end
+ ]]></source>
+
+ <p>
+ In fact, because all script elements
+ are escaped, <em>$jazz</em> is never evaluated for it's boolean value.
+ Suppose
backslashes precede script elements that are legitimately escaped:
</p>
@@ -1575,8 +1589,28 @@
]]></source>
<p>
- In this case, if <em>$jazz</em> is true, the output is <em>\ Vyacheslav
- Ganelin \</em>. If <em>$jazz</em> is false, there is no output. Note that
+ In this case, if <em>$jazz</em> is true, the output is
+ </p>
+
+<source><![CDATA[
+\ Vyacheslav Ganelin
+\
+]]></source>
+
+ <p>
+ To understand this, note that the <code>#if( arg ) </code> when
+ ended by a newline (return) will omit the newline from the output.
+ Therefore, the body of the <code>#if()</code>
+ block follows the first '\', rendered
+ from the '\\' preceeding the <code>#if()</code>.
+ The last \ is on a different
+ line than the text beacsue there is a newline after 'Ganelin', so
+ the final \\, preceeding the <code>#end</code> is part of the
+ body of the block.
+ </p>
+
+ <p>
+ If <em>$jazz</em> is false, there is no output. Note that
things start to break if script elements are not properly escaped.
</p>
@@ -1848,6 +1882,173 @@
</subsection>
+<subsection name="Velocimacro Miscellany">
+
+<p>
+This section is a mini-FAQ on topics relating to Velocimacros. This
+section will change over time, so it's worth checking for new information
+from time to time.
+</p>
+
+<p>
+Note : Throughout this section, 'Velocimacro' will commonly be abbreviated
+as 'VM'.
+</p>
+
+<strong>Can I use a directive or another VM as an argument to a VM?</strong>
+
+<p>
+Example : <code>#center( #bold("hello") )</code>
+</p>
+
+<p>
+No. A directive isn't a valid argument to a directive, and for most practical
+purposes, a VM is a directive.
+</p>
+
+<p>
+<i>However...</i>, there are things you can do. One easy solution is to take
+advantage of the fact that 'doublequote' (") renders it's contents. So you
+could do something like
+</p>
+
+<source><![CDATA[
+#set($stuff = "#bold('hello')" )
+#center( $stuff )
+]]></source>
+
+<p>
+You can save a step...
+</p>
+
+<source><![CDATA[
+#center( "#bold( 'hello' )" )
+]]></source>
+
+<p>
+Please note that in the latter exmaple the arg
+is evaluated <i>inside</i> the VM, not at the
+calling level. In other words, the argument to
+the VM is passed in in its entirety and evaluated within the VM
+it was passed into. This allows you to do things like :
+</p>
+
+<source><![CDATA[
+
+#macro( inner $foo )
+ inner : $foo
+#end
+
+#macro( outer $foo )
+ #set($bar = "outerlala")
+ outer : $foo
+#end
+
+#set($bar = 'calltimelala')
+#outer( "#inner($bar)" )
+
+]]></source>
+
+<p>
+Where the output is
+</p>
+
+<source><![CDATA[
+Outer : inner : outerlala
+]]></source>
+
+<p>
+because the evaluation of the "#inner($bar)" happens inside #outer(), so the
+$bar value set inside #outer() is the one that's used.
+</p>
+
+<p>
+This is an intentional and jealously guarded feature - args are passed 'by
+name' into VMs, so you can hand VMs things like stateful references such as
+</p>
+
+<source><![CDATA[
+#macro( foo $color )
+ <tr bgcolor=$color><td>Hi</td></tr>
+ <tr bgcolor=$color><td>There</td></tr>
+#end
+
+#foo( $bar.rowColor() )
+]]></source>
+
+<p>
+And have rowColor() called repeatedly, rather than just once. To avoid that,
+invoke the method outside of the VM, and pass the value into the VM.
+</p>
+
+<source><![CDATA[
+#set($color = $bar.rowColor())
+#foo( $color )
+]]></source>
+
+
+<strong>Can I register Velocimacros via #parse() ? </strong>
+
+ <p>
+ Currently, Velocimacros must be defined before they are first
+ used in a template. This means that your #macro() declarations
+ should come before using the Velocimacros.
+ </p>
+
+ <p>
+ This is important to remember if you try to #parse()
+ a template containing inline #macro() directives. Because
+ the #parse() happens at runtime, and the parser decides if
+ a VM-looking element in the template is a VM at parsetime,
+ #parse()-ing a set of VM declarations won't work as expected.
+ To get around this, simply use the <code>velocimacro.library</code>
+ facility to have Velocity load your VMs at startup.
+ </p>
+
+
+<strong>What is Velocimacro Autoreloading?</strong>
+
+ <p>
+ There is a property, meant to be used in <i>development</i>,
+ not production :
+ </p>
+
+ <p>
+ <code>velocimacro.library.autoreload</code>
+ </p>
+
+ <p>
+ which defaults to false. When set to true <em>along with</em>
+ </p>
+
+ <p>
+ <code><type>.resource.loader.cache = false</code>
+ </p>
+
+ <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>
+ Here is what a simple set of configuration properties would look like.
+ </p>
+
+ <source><![CDATA[
+ file.resource.loader.path = templates
+ file.resource.loader.cache = false
+ velocimacro.library.autoreload = true
+ ]]></source>
+
+ <p>
+ Don't keep this on in production.
+ </p>
+
+</subsection>
+
</section>
<section name="Feedback">
@@ -1855,7 +2056,8 @@
<p>
If you encounter any mistakes in this manual or have
other feedback related to the Velocity User Guide, please
- email <a href="mailto:[EMAIL PROTECTED]";>John Castura</a>.
+ email the
+ <a href="mailto:[EMAIL PROTECTED]";>Velocity user list</a>.
Thanks!
</p>
No revision
No revision
1.79.2.1 +11 -0 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.79
retrieving revision 1.79.2.1
diff -u -r1.79 -r1.79.2.1
--- developer-guide.html 2001/09/26 11:45:01 1.79
+++ developer-guide.html 2001/10/19 11:14:34 1.79.2.1
@@ -2301,6 +2301,17 @@
Velocimacro.
</p>
<p>
+<code>velocimacro.library.autoreload = false</code><br />
+Controls Velocimacro library autoloading. 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>
<strong>String Interpolation</strong>
</p>
<p>
1.50.2.1 +366 -14 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.50
retrieving revision 1.50.2.1
diff -u -r1.50 -r1.50.2.1
--- user-guide.html 2001/09/21 10:32:23 1.50
+++ user-guide.html 2001/10/19 11:14:34 1.50.2.1
@@ -174,6 +174,7 @@
<li><a href="#Range Operator">Range Operator</a></li>
<li><a href="#Advanced Issues: Escaping and !">Advanced Issues: Escaping and
!</a></li>
+ <li><a href="#Velocimacro Miscellany">Velocimacro Miscellany</a></li>
</ol>
</li>
<li><a href="#Feedback">Feedback</a></li>
@@ -1485,9 +1486,7 @@
</div>
<p>
Unlike some of the other Velocity directives, the <em>#set</em>
- directive does not have an <em>#end</em> statement. Instead, the
- left bracket marks the beginning and the right bracket marks the end
- of an assignment.
+ directive does not have an <em>#end</em> statement.
</p>
<a name="String
Literals"><strong>String Literals</strong></a>
<p>
@@ -1734,8 +1733,7 @@
</table>
</div>
<p>
- Two kinds of logical operators, logical AND and logical OR, are
- expected to be added to Velocity soon. Below is an example of an
+ Velocity has logical AND and OR operators as well. Below is an example of an
if statement using logical AND.
</p>
<div align="left">
@@ -1769,7 +1767,7 @@
Engine will then check the value of <em>$bar</em>; if
<em>$bar</em> is true, then the entire expression is true and
<strong>Velocity Rocks!</strong> becomes the output. If
- <em>$bar</em> is false, then there will be no output; the entire
+ <em>$bar</em> is false, then there will be no output as the entire
expression is false.
</p>
<p>
@@ -2705,8 +2703,31 @@
</table>
</div>
<p>
- If <em>$jazz</em> is true, the output is <em>Vyacheslav Ganelin</em>; if
- <em>$jazz</em> is false, there is no output. Escaping script elements
+ If <em>$jazz</em> is true, the output is
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+Vyacheslav Ganelin
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ If <em>$jazz</em> is false, there is no output. Escaping script elements
alters the output. Consider the following case:
</p>
<div align="left">
@@ -2732,10 +2753,36 @@
</tr>
</table>
</div>
+ <p>
+ Whether <em>$jazz</em> is true or false, the output will be
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+ #if($ jazz )
+ Vyacheslav Ganelin
+ #end
+ </pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
<p>
- Whether <em>$jazz</em> is true or false, the output will be "#if(
- $jazz ) Vyacheslav Ganelin #end"; in fact, because all script elements
- are escaped the truth of <em>$jazz</em> is never checked. Suppose
+ In fact, because all script elements
+ are escaped, <em>$jazz</em> is never evaluated for it's boolean value.
+ Suppose
backslashes precede script elements that are legitimately escaped:
</p>
<div align="left">
@@ -2762,8 +2809,43 @@
</table>
</div>
<p>
- In this case, if <em>$jazz</em> is true, the output is <em>\ Vyacheslav
- Ganelin \</em>. If <em>$jazz</em> is false, there is no output. Note that
+ In this case, if <em>$jazz</em> is true, the output is
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+\ Vyacheslav Ganelin
+\
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ To understand this, note that the <code>#if( arg ) </code> when
+ ended by a newline (return) will omit the newline from the output.
+ Therefore, the body of the <code>#if()</code>
+ block follows the first '\', rendered
+ from the '\\' preceeding the <code>#if()</code>.
+ The last \ is on a different
+ line than the text beacsue there is a newline after 'Ganelin', so
+ the final \\, preceeding the <code>#end</code> is part of the
+ body of the block.
+ </p>
+ <p>
+ If <em>$jazz</em> is false, there is no output. Note that
things start to break if script elements are not properly escaped.
</p>
<div align="left">
@@ -3343,6 +3425,275 @@
</td></tr>
<tr><td><br/></td></tr>
</table>
+ <table border="0"
cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#828DA6">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Velocimacro Miscellany"><strong>Velocimacro
Miscellany</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+This section is a mini-FAQ on topics relating to Velocimacros. This
+section will change over time, so it's worth checking for new information
+from time to time.
+</p>
+ <p>
+Note : Throughout this section, 'Velocimacro' will commonly be abbreviated
+as 'VM'.
+</p>
+ <strong>Can I use a directive or
another VM as an argument to a VM?</strong>
+ <p>
+Example : <code>#center( #bold("hello") )</code>
+</p>
+ <p>
+No. A directive isn't a valid argument to a directive, and for most practical
+purposes, a VM is a directive.
+</p>
+ <p>
+<i>However...</i>, there are things you can do. One easy solution is to take
+advantage of the fact that 'doublequote' (") renders it's contents. So you
+could do something like
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+#set($stuff = "#bold('hello')" )
+#center( $stuff )
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+You can save a step...
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+#center( "#bold( 'hello' )" )
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+Please note that in the latter exmaple the arg
+is evaluated <i>inside</i> the VM, not at the
+calling level. In other words, the argument to
+the VM is passed in in its entirety and evaluated within the VM
+it was passed into. This allows you to do things like :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+#macro( inner $foo )
+ inner : $foo
+#end
+
+#macro( outer $foo )
+ #set($bar = "outerlala")
+ outer : $foo
+#end
+
+#set($bar = 'calltimelala')
+#outer( "#inner($bar)" )
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+Where the output is
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+Outer : inner : outerlala
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+because the evaluation of the "#inner($bar)" happens inside #outer(), so the
+$bar value set inside #outer() is the one that's used.
+</p>
+ <p>
+This is an intentional and jealously guarded feature - args are passed 'by
+name' into VMs, so you can hand VMs things like stateful references such as
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+#macro( foo $color )
+ <tr bgcolor=$color><td>Hi</td></tr>
+ <tr bgcolor=$color><td>There</td></tr>
+#end
+
+#foo( $bar.rowColor() )
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+And have rowColor() called repeatedly, rather than just once. To avoid that,
+invoke the method outside of the VM, and pass the value into the VM.
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+#set($color = $bar.rowColor())
+#foo( $color )
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <strong>Can I register Velocimacros
via #parse() ? </strong>
+ <p>
+ Currently, Velocimacros must be defined before they are first
+ used in a template. This means that your #macro() declarations
+ should come before using the Velocimacros.
+ </p>
+ <p>
+ This is important to remember if you try to #parse()
+ a template containing inline #macro() directives. Because
+ the #parse() happens at runtime, and the parser decides if
+ a VM-looking element in the template is a VM at parsetime,
+ #parse()-ing a set of VM declarations won't work as expected.
+ To get around this, simply use the <code>velocimacro.library</code>
+ facility to have Velocity load your VMs at startup.
+ </p>
+ <strong>What is Velocimacro
Autoreloading?</strong>
+ <p>
+ There is a property, meant to be used in <i>development</i>,
+ not production :
+ </p>
+ <p>
+ <code>velocimacro.library.autoreload</code>
+ </p>
+ <p>
+ which defaults to false. When set to true <em>along with</em>
+ </p>
+ <p>
+ <code><type>.resource.loader.cache = false</code>
+ </p>
+ <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>
+ Here is what a simple set of configuration properties would look like.
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+ file.resource.loader.path = templates
+ file.resource.loader.cache = false
+ velocimacro.library.autoreload = true
+ </pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ Don't keep this on in production.
+ </p>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
</blockquote>
</p>
</td></tr>
@@ -3359,7 +3710,8 @@
<p>
If you encounter any mistakes in this manual or have
other feedback related to the Velocity User Guide, please
- email <a href="mailto:[EMAIL PROTECTED]";>John Castura</a>.
+ email the
+ <a href="mailto:[EMAIL PROTECTED]";>Velocity user list</a>.
Thanks!
</p>
</blockquote>
