Author: nbubna
Date: Tue Sep 2 16:11:08 2008
New Revision: 691422
URL: http://svn.apache.org/viewvc?rev=691422&view=rev
Log:
VELOCITY-395 clarify user guide on escaping references
Modified:
velocity/engine/trunk/xdocs/docs/user-guide.xml
Modified: velocity/engine/trunk/xdocs/docs/user-guide.xml
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/xdocs/docs/user-guide.xml?rev=691422&r1=691421&r2=691422&view=diff
==============================================================================
--- 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 @@
<ol>
<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>
</ol>
</li>
<li><a href="#case_substitution">Case Substitution</a></li>
@@ -715,10 +716,12 @@
<p>
<a name="escapingvalidvtlreferences"><strong>Escaping Valid VTL
References</strong></a>
<br/>
- 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>
</p>
<source><![CDATA[
@@ -802,9 +805,42 @@
is output in place of <em>$foo</em>.
</p>
+ <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 this:
+ </p>
+
+<source><![CDATA[
+${my:invalid:non:reference}
+]]></source>
+
+ <p>with something like this</p>
+
+<source><![CDATA[
+#set( $D = '$' )
+${D}{my:invalid:non:reference}
+]]></source>
+
+ <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="http://velocity.apache.org/tools/devel/";>VelocityTools</a>, you
can
+ just use the EscapeTool like this:</p>
+
+<source><![CDATA[
+${esc.d}{my:invalid:non:reference}
+]]></source>
+
<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.
</p>
