You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by jo...@locus.apache.org on 2000/08/28 02:10:03 UTC
cvs commit: jakarta-velocity/xdocs script-elements.xml
jon 00/08/27 17:10:02
Modified: xdocs script-elements.xml
Log:
initial checkin of script element documentation.
Revision Changes Path
1.2 +252 -13 jakarta-velocity/xdocs/script-elements.xml
Index: script-elements.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/script-elements.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- script-elements.xml 2000/08/26 19:39:12 1.1
+++ script-elements.xml 2000/08/28 00:10:01 1.2
@@ -17,26 +17,265 @@
There are several different types of Script Elements within Velocity. The
overall purpose of these elements is described in the <link
href="design.html">Design Document</link>. The following elements are currently
- defined within Velocity and also explained in detail below.
- </p>
+ defined within Velocity and also explained in detail below. All of the elements are
+ prefixed with a #. For example, #if, #foreach, #set.
+ </p>
<ul>
- <li>Variables</li>
- <li>Conditionals:
+ <li><strong>Variables</strong></li>
+ <li><strong>Conditionals</strong>:
+ <ul>
+ <li>If / Else</li>
+ </ul>
+ </li>
+ <li><strong>Loops</strong>:
<ul>
- <li>If Statement</li>
- <li>Foreach Statement</li>
- <li>While Statement (Not Yet Implemented)</li>
+ <li>Foreach</li>
+ <li>While <font size="-2">(Not Yet Implemented)</font></li>
</ul>
</li>
- <li>Parse</li>
- <li>Include</li>
- <li>Param</li>
- <li>Set</li>
- <li>Comment</li>
- <li>Stop</li>
+ <li><strong>Parse</strong></li>
+ <li><strong>Include</strong></li>
+ <li><strong>Param</strong></li>
+ <li><strong>Set</strong></li>
+ <li><strong>Comment</strong></li>
+ <li><strong>Stop</strong></li>
</ul>
</s1>
+<s1 title="Variables">
+ <p>
+ Variables are referenced in a similar fashion to the way that they are in
+ Perl (ie: they use a $), but they also take advantage of some Java
+ principles that are easy for template designers to work with. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ $foo
+ $foo.getBar() or $foo.Bar
+ $data.getUser("jon") or $data.User("jon")
+ $data.getRequest().getServerName() or $data.Request.ServerName]]></source>
+ </p>
+
+ <p>
+ As you can see in a couple of the examples above there are alternative uses
+ for the same variables. Velocity takes advantage of Java's introspection and
+ bean features to resolve the variable names to both objects in the Context
+ as well as the objects methods. It is possible to embed the variables almost
+ anywhere in your template and have them be evaluated.
+ </p>
+
+ <p>
+ Everything coming to and from the variables is treated as a String object.
+ If you have an object that is representing $foo such as an Integer object,
+ then Velocity will call its .toString() method in order to resolve the
+ object into a String.
+ </p>
+ </s1>
+
+<s1 title="Conditionals">
+
+ <s1 title="If / Else Conditionals">
+ <p>
+ The #if statement in Velocity allows you to conditionally include the text
+ within the brackets. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo)
+ {
+ <strong>Velocity Rocks!</strong>
+ }]]></source>
+ </p>
+
+ <p>
+ The variable $foo is evaluated to see if it is a boolean or not null and the
+ content within the brackets is what is output if the evaluation is true. As
+ you can see, this has the advantage over other systems because you do not
+ need to wrap your HTML code within an out.println(), therefore enabling you
+ to develop a more MVC solution. Of course there are other solutions to
+ out.println() within JSP, but they are just as ugly as out.println().
+ </p>
+
+ <p>
+ Another example is that you can include #else elements with your #if element.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo)
+ {
+ <strong>Velocity Rocks!</strong>
+ }
+ #else
+ {
+ <strong>Velocity Still Rocks!</strong>
+ }]]></source>
+ </p>
+
+ <p>
+ Note: In the current version of Velocity, it is not possible to do something like what
+ is shown below. We will be adding this functionality quickly though.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #if ($foo && $bar)
+ {
+ <strong>Velocity Rocks!</strong>
+ }]]></source>
+ </p>
+
+ <p>
+ If you would like to emulate the functionality of #elseif, then you can do
+ so by using nested #if statements. As you would expect, nesting elements
+ works for all of the elements to an infinite level of nesting. For example,
+ you can nest a #foreach within a #if. We will be considering in the future
+ of adding a #elseif to simplify things.
+ </p>
+ </s1>
+</s1>
+
+<s1 title="Loops">
+ <s1 title="Foreach Loop">
+ <p>
+ The #foreach element allows you to create loops. For example:
+ </p>
+
+ <p>
+ <source><![CDATA[
+ <ul>
+ #foreach $product in $allProducts
+ {
+ <li>$product</li>
+ }
+ </ul>
+ ]]></source>
+ </p>
+
+ <p>
+ The #foreach loop causes the $allProducts list to be looped over for all
+ of the elements in the list. Each time through the loop, the value from
+ $allProducts is placed into the $product variable.
+ </p>
+
+ <p>
+ The contents of the $allProducts variable is either a Vector, Hashtable or
+ Array. Thus, the value that is assigned to the $product variable is a Java
+ Object and can be referenced from the variable as so. For example, if $product
+ was really a Product class in Java, you could get the name of the Product
+ by referencing the $product.Name method (ie: Product.getName()).
+ </p>
+ </s1>
+</s1>
+
+<s1 title="Parse">
+ <p>
+ The #parse script element allows you to import a local file and have it
+ parsed through the Velocity template engine and inserted into the location
+ where the #parse directive is defined. The current Context is applied to the
+ variables that are embedded within the template.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #parse /path/to/file.vm
+ ]]></source>
+ </p>
+</s1>
+
+<s1 title="Include">
+ <p>
+ The #include script element allows you to import a local file that is
+ inserted into the location where the #include directive is defined. The
+ contents of the file are not rendered through the template engine.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #include /path/to/file.vm
+ ]]></source>
+ </p>
+</s1>
+
+<s1 title="Param">
+ <p>
+ The #param script element allows the template designer to set items
+ in the context that are static and do not change over the life of the
+ template.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #param $date = "May 24, 1973"
+ ]]></source>
+ </p>
+
+ <p>
+ One difference between Velocity and WebMacro is that the left hand side
+ variable must be prefixed with a $. We felt that this is more appropriate
+ for the script element language because you are effectively setting a
+ variable and the references to variables should be consistent.
+ </p>
+</s1>
+
+<s1 title="Set">
+ <p>
+ The #set script element allows the template designer to set variables within
+ the Context.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #set $name = "Fred"
+ ]]></source>
+ </p>
+
+ <p>
+ One difference between Velocity and WebMacro is that the left hand side
+ variable must be prefixed with a $. We felt that this is more appropriate
+ for the script element language because you are effectively setting a
+ variable and the references to variables should be consistent.
+ </p>
+
+ <p>
+ Currently, the above example is the only thing that is supported. We will
+ eventually be suporting the full range of WebMacro functionality here.
+ </p>
+</s1>
+
+<s1 title="Comment">
+ <p>
+ The ## script element allows the template designer to write comments in
+ templates that are not placed into the output of the template engine.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ ## this is a comment
+ ]]></source>
+ </p>
+
+ <p>
+ A current problem with Velocity is that the space that comments occupy
+ is not removed from the template. The newlines should be removed. This
+ will be fixed shortly.
+ </p>
+</s1>
+
+<s1 title="Stop">
+ <p>
+ The #stop script element allows the template designer to stop the execution
+ of the template engine and return. This is useful for debugging purposes.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #stop
+ ]]></source>
+ </p>
+</s1>
</body>
</document>