geirm 01/10/06 04:14:22
Modified: xdocs user-guide.xml
docs user-guide.html
Log:
Added VM 'topic' section with answer to the question that was recently
posted to user list.
Revision Changes Path
1.49 +109 -1 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- user-guide.xml 2001/09/28 08:34:24 1.48
+++ user-guide.xml 2001/10/06 11:14:22 1.49
@@ -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>
@@ -1847,6 +1848,112 @@
</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>
+
+</subsection>
+
</section>
<section name="Feedback">
@@ -1854,7 +1961,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>
1.52 +207 -1 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -r1.51 -r1.52
--- user-guide.html 2001/09/28 08:34:25 1.51
+++ user-guide.html 2001/10/06 11:14:22 1.52
@@ -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>
@@ -3342,6 +3343,210 @@
</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>
+ </blockquote>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
</blockquote>
</p>
</td></tr>
@@ -3358,7 +3563,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>
