geirm 01/03/21 18:03:17
Modified: docs user-guide.html
Log:
follows xml
Revision Changes Path
1.31 +104 -2 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- user-guide.html 2001/03/21 20:23:24 1.30
+++ user-guide.html 2001/03/22 02:03:14 1.31
@@ -2110,7 +2110,7 @@
<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>
-#d
+#d()
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
@@ -2122,7 +2122,7 @@
</table>
</div>
<p>
- When this template is called, Velocity would replace <em>#d</em>
+ When this template is called, Velocity would replace <em>#d()</em>
with a row containing a single, empty data cell.
</p>
<p>
@@ -2322,6 +2322,108 @@
<tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>
</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>Velocimacro
Arguments</strong>
+ <p>
+ Velocimacros can take as arguments any of the following
+ VTL elements :
+ </p>
+ <ul>
+ <li>
+ Reference : anything that starts with '$'
+ </li>
+ <li>
+ String literal : something like "$foo" or 'hello'
+ </li>
+ <li>
+ Number literal : 1, 2 etc
+ </li>
+ <li>
+ IntegerRange : [ 1..2] or [$foo .. $bar]
+ </li>
+ <li>
+ ObjectArray : [ "a", "b", "c"]
+ </li>
+ <li>
+ boolean value true
+ </li>
+ <li>
+ boolean value false
+ </li>
+ </ul>
+ <p>
+ When passing references as arguments to Velocimacros,
+ please note that references are passed 'by name'.
+ This means that their value is 'generated' at each
+ use inside the Velocimacro. This feature allows you
+ to pass references with method calls and have the
+ method called at each use. For example, when calling
+ the following Velocimacro as shown
+ </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( callme $a )
+ $a $a $a
+ #end
+
+ #callme( $foo.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>
+ results in the method bar() of the reference $foo
+ being called 3 times.
+ </p>
+ <p>
+ At first glance, this feature appears surprising, but
+ when you take into consideration the original motivation
+ behind Velocimacros -- to eliminate cut'n'paste duplication
+ of commonly used VTL -- it makes sense. It allows you to
+ do things like pass stateful objects, such as an object
+ that generates colors in a repeating sequence for
+ coloring table rows, into the Velocimacro.
+ </p>
+ <p>
+ If you need to circumvent this feature, you can always
+ just get the value from the method as a new reference
+ and pass that :
+ </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( $myval = $foo.bar() )
+ #callme( $myval )
+ </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>
