velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r691422 - /velocity/engine/trunk/xdocs/docs/user-guide.xml
Date Tue, 02 Sep 2008 23:11:08 GMT
Author: nbubna
Date: Tue Sep  2 16:11:08 2008
New Revision: 691422

VELOCITY-395 clarify user guide on escaping references


Modified: velocity/engine/trunk/xdocs/docs/user-guide.xml
--- velocity/engine/trunk/xdocs/docs/user-guide.xml (original)
+++ velocity/engine/trunk/xdocs/docs/user-guide.xml Tue Sep  2 16:11:08 2008
@@ -54,6 +54,7 @@
         <li><a href="#currency">Currency</a></li>
         <li><a href="#escapingvalidvtlreferences">Escaping Valid VTL References</a></li>
+        <li><a href="#escapinginvalidvtlreferences">Escaping Inalid VTL References</a></li>
 <li><a href="#case_substitution">Case Substitution</a></li>
@@ -715,10 +716,12 @@
     <a name="escapingvalidvtlreferences"><strong>Escaping Valid VTL References</strong></a>
-    Cases may arise where there is the potential for Velocity to get
-    confused. <em>Escaping</em> special characters is the best way to
-    handle VTL's special characters in your templates, and this can be
-    done using the backslash ( <em>\</em> ) character.
+    Cases may arise where you do not want to have a reference rendered by Velocity.
+    <em>Escaping</em> special characters is the best way to output
+    VTL's special characters in these situations, and this can be
+    done using the backslash ( <em>\</em> ) character <i>when those special
+    characters are part of a valid VTL reference</i>.
+    <a href="#escapinginvalidvtlreferences" style="text-decoration: none"><sup>*</sup></a>
@@ -802,9 +805,42 @@
     is output in place of <em>$foo</em>.
+  <p>
+    <a name="escapinginvalidvtlreferences"><strong>Escaping Invalid VTL References</strong></a>
+    <br/>
+    Sometimes Velocity has trouble parsing your template when it encounters
+    an "invalid reference" that you never intended to be a reference at all.
+    <em>Escaping</em> special characters is, again, the best way to
+    handle these situations, but in these situations, the backslash will
+    likely fail you.  Instead of simply trying to escape the problematic
+    <code>$</code> or <code>#</code>, you should probably just replace
+  </p>
+    <p>with something like this</p>
+#set( $D = '$' )
+    <p>You can, of course, put your <code>$</code> or <code>#</code>
string directly
+    into the context from your java code (e.g. <code>context.put("D","$");</code>)
+    to avoid the extra #set() directive in your template(s).  Or, if you are using
+    <a href="">VelocityTools</a>, you
+    just use the EscapeTool like this:</p>
-     It is also possible to escape VTL directives; this is described in
+     Escaping of both valid and invalid VTL directives is
+     handled in much the same manner; this is described in
      more detail in the Directives section.

View raw message