Author: nbubna
Date: Fri Jan 16 15:18:55 2009
New Revision: 735180
URL: http://svn.apache.org/viewvc?rev=735180&view=rev
Log:
VELOCITY-666 some block macro documentation
Modified:
velocity/engine/trunk/src/java/org/apache/velocity/runtime/RuntimeConstants.java
velocity/engine/trunk/xdocs/docs/developer-guide.xml
velocity/engine/trunk/xdocs/docs/user-guide.xml
velocity/engine/trunk/xdocs/docs/vtl-reference-guide.xml
Modified:
velocity/engine/trunk/src/java/org/apache/velocity/runtime/RuntimeConstants.java
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/src/java/org/apache/velocity/runtime/RuntimeConstants.java?rev=735180&r1=735179&r2=735180&view=diff
==============================================================================
---
velocity/engine/trunk/src/java/org/apache/velocity/runtime/RuntimeConstants.java
(original)
+++
velocity/engine/trunk/src/java/org/apache/velocity/runtime/RuntimeConstants.java
Fri Jan 16 15:18:55 2009
@@ -281,7 +281,7 @@
String VM_MAX_DEPTH = "velocimacro.max.depth";
/**
- * Defines name of the reference that can be used to get the AST block
passed to block marco call.
+ * Defines name of the reference that can be used to get the AST block
passed to block macro calls.
* @since 1.7
*/
String VM_BODY_REFERENCE = "velocimacro.body.reference";
Modified: velocity/engine/trunk/xdocs/docs/developer-guide.xml
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/xdocs/docs/developer-guide.xml?rev=735180&r1=735179&r2=735180&view=diff
==============================================================================
--- velocity/engine/trunk/xdocs/docs/developer-guide.xml (original)
+++ velocity/engine/trunk/xdocs/docs/developer-guide.xml Fri Jan 16 15:18:55
2009
@@ -1868,6 +1868,14 @@
</p>
<p>
+<code>velocimacro.body.reference = false</code><br/>
+Defines name of the reference that can be used to get the body content
+(an AST block) given for a block macro call (e.g. #...@mymacro() has a body
#end).
+The default reference name is "bodyContent" (e.g. $bodyContent). This block
+macro feature was introduced in Velocity 1.7.
+</p>
+
+<p>
<strong>Strict Reference Setting</strong>
</p>
Modified: velocity/engine/trunk/xdocs/docs/user-guide.xml
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/xdocs/docs/user-guide.xml?rev=735180&r1=735179&r2=735180&view=diff
==============================================================================
--- velocity/engine/trunk/xdocs/docs/user-guide.xml (original)
+++ velocity/engine/trunk/xdocs/docs/user-guide.xml Fri Jan 16 15:18:55 2009
@@ -1615,11 +1615,35 @@
<p>
When this template is called, Velocity would replace <em>#d()</em>
- with a row containing a single, empty data cell.
+ 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>
+
+<source><![CDATA[
+#macro( d )
+<tr><td>$!bodyContent</td></tr>
+#end
+]]></source>
+
+ <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>
+
+<source><![CDATA[
+...@d()Hello!#end
+]]></source>
+
+ <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 could take any number of arguments -- even zero
+ 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
Modified: velocity/engine/trunk/xdocs/docs/vtl-reference-guide.xml
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/xdocs/docs/vtl-reference-guide.xml?rev=735180&r1=735179&r2=735180&view=diff
==============================================================================
--- velocity/engine/trunk/xdocs/docs/vtl-reference-guide.xml (original)
+++ velocity/engine/trunk/xdocs/docs/vtl-reference-guide.xml Fri Jan 16
15:18:55 2009
@@ -499,7 +499,7 @@
<p>
<strong>#</strong> [ <strong>{</strong> ] <strong>macro</strong> [
<strong>}</strong> ] <strong>(</strong> vmname $arg1 [ $arg2 $arg3 ... $argn ]
- <strong>)</strong> [ VM VTL code... ] <strong>#</strong> [
<strong>{</strong> ] <strong>#end</strong> [ <strong>}</strong> ]
+ <strong>)</strong> [ VM VTL code... ] <strong>#</strong> [
<strong>{</strong> ] <strong>end</strong> [ <strong>}</strong> ]
</p>
<ul>
@@ -522,6 +522,17 @@
]]></source>
<p>
+ <strong>Except</strong>, that when you wish to call a VM with a body, then
+ you must prefix the name of the VM with @. The content of that body
+ may be referenced in the macro definition via $!bodyContent as many or
+ few times as you like.
+ </p>
+
+<source><![CDATA[
+...@vmname( $arg1 $arg2 ) here is the body#end
+]]></source>
+
+ <p>
VMs can be defined in one of two places:
</p>
