jvanzyl 00/10/02 18:10:18
Modified: xdocs code-standards.xml contributors.xml design.xml
index.xml install.xml script-elements.xml
Log:
Edits.
Revision Changes Path
1.4 +11 -10 jakarta-velocity/xdocs/code-standards.xml
Index: code-standards.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/code-standards.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- code-standards.xml 2000/09/30 20:11:47 1.3
+++ code-standards.xml 2000/10/03 01:10:17 1.4
@@ -15,21 +15,22 @@
<s1 title="Coding Standards">
<p>
- Code submissions to the Velocity project must follow the conventions
- listed in this document. Velocity developers
+ Submissions to the Velocity project must follow the coding conventions
+ outlined in this document. Velocity developers
are asked to follow coding conventions already present in the code.
- For example, if the existing code has the bracket on
+ (For example, if the existing code has the bracket on
the same line as the if statement, then all subsequent code
- should also follow that convention. Anything not
- explicitly mentioned in this document should follow the official
+ should also follow that convention.) Anything not
+ explicitly mentioned in this document should adhere to the
+ official
<link href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun
Java Coding Conventions</link>.
</p>
<p>
- <strong>If you are caught commiting code that does not follow
- the existing conventions, you will be responsible for fixing
- it.</strong>
+ <strong>Developers who commit code that does not follow
+ the coding conventions outlined in this document will be
+ responsible for fixing their own code.</strong>
</p>
<p>
@@ -66,7 +67,7 @@
<p>
2. Spaces between parentheses are optional. The preference is to exclude
-extra spaces. For example, both of these conventions are acceptable:
+extra spaces. Both of these conventions are acceptable:
</p>
<p>
@@ -98,7 +99,7 @@
</p>
<p>
-5. Javadoc <strong>MUST</strong> exist on all your methods. Contributing
+5. Javadoc <strong>MUST</strong> exist on all methods. Contributing
a missing javadoc for any method, class, variable, etc., will be greatly
appreciated as this will help to improve the Velocity project.
</p>
1.3 +8 -6 jakarta-velocity/xdocs/contributors.xml
Index: contributors.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/contributors.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- contributors.xml 2000/09/30 17:36:10 1.2
+++ contributors.xml 2000/10/03 01:10:17 1.3
@@ -16,18 +16,20 @@
<p>
The people listed below have made significant contributions to Velocity by
- working long and hard to make quality software for the rest of the world to
use.
+ working long and hard to make quality software for the rest of the world to
+ use.
</p>
<p>
- If you would like to become a contributor, please see the document titled
- todo.html to find areas where you can contribute. If there is nothing in there
- that suits your interest, but you still have ideas, please feel free to suggest
- them on the mailing list.
+ If you would like to contribute to Velocity, please see the
+ <a href="todo.html">to do</a> list to find areas where you can contribute.
+ If there is nothing in there that suits your interest, but you still have
+ ideas, please feel free to suggest them on the mailing list.
</p>
<p>
- We are following a certification scheme like the one that is outlined here:
+ Velocity follows a certification scheme similar to the one that is outlined
+ on
<link
href="http://www.advogato.org/certs.html">http://www.advogato.org/certs.html</link>.
Names on this list are ordered from first contributor at the top to the most
recent contributor
at the bottom.
1.4 +10 -9 jakarta-velocity/xdocs/design.xml
Index: design.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/design.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- design.xml 2000/09/30 20:11:47 1.3
+++ design.xml 2000/10/03 01:10:17 1.4
@@ -20,23 +20,24 @@
or it can be combined with other systems to provide template
services. Velocity will be tightly integrated with the
<link href="http://java.apache.org/turbine">Turbine</link>
- web application framework to provide a template service that will
- enable a true MVC model by which web applications may be developed.
+ web application framework. Together, Velocity and Turbine
+ provide a template service by which web applications may be
+ developed according to a true MVC model.
</p>
<p>
Velocity has a myriad of potential uses--generating SQL from XML schemas,
creating postscript output from XML files, generating Java source
code for Java files--but it is expected to be most widely used
- by web developers looking for a better alternative to
+ by web developers looking for a superior alternative to
<link href="http://www.php.org/">PHP</link> and
<link href="http://java.sun.org/products/jsp/">Java
Server Pages</link> (JSPs).
</p>
<p>
- Velocity allows web page designers to embed simple
- and useful script elements in their web pages. These script elements work
+ Velocity allows web page designers to embed simple yet powerful script
+ elements in their web pages. These script elements work
in conjunction with a Context object, which is defined in Java code.
A context object--essentially a Hashtable that provides get and set
methods for retrieving and setting objects by name within the Context
@@ -68,10 +69,10 @@
</p>
<p>
- The concept for Velocity was borrowed from
- <link href="http://www.webmacro.org/">WebMacro</link>,
- and those involved in the Velocity project acknowledge and appreciate
- the development and design work that went into the WebMacro project.
+ Velocity's concept was borrowed from
+ <link href="http://www.webmacro.org/">WebMacro</link>. Those involved in
+ the Velocity project acknowledge and appreciate the development and design
+ work that went into the WebMacro project.
</p>
</s1>
1.3 +17 -18 jakarta-velocity/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 2000/09/30 17:36:10 1.2
+++ index.xml 2000/10/03 01:10:18 1.3
@@ -20,9 +20,9 @@
or it can be combined with other systems to provide template
services. Velocity will be tightly integrated with the
<link href="http://java.apache.org/turbine/">Turbine</link>
- web application framework to provide a template service that
- will enable a true MVC model by which web applications may be
- developed.
+ web application framework. Together, Velocity and Turbine provide
+ a template service that will allow web applications to be developed
+ according to a true MVC model.
</p>
<p>
@@ -31,13 +31,12 @@
(Java Compiler Compiler) using the JJTree extension to create an
Abstract Syntax Tree (AST). The AST may subsequently be traversed
(repeatedly if desired) by a tree walker, which
- is implemented using the visitor design pattern. This allows
- the parsing logic to be separated from the actions performed
+ is implemented using the visitor design pattern. This allows the
+ parsing logic to be separated from the actions performed
on the resultant AST. Two visitors come with Velocity: the first
- is a simple implementation that produces a visual tree of the
- syntax and nothing more, mostly used for
- debugging; the second visitor actually generates
- output from user-defined values and introspection.
+ visitor is produces a visual tree of the syntax and nothing more,
+ mostly used for debugging, the second actually generates output
+ from user-defined values and introspection.
</p>
</s1>
@@ -57,7 +56,7 @@
<s1 title="Where do I get nightly builds?">
<p>
- You can find nightly builds
+ Nightly builds of Velocity can be found
<link
href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">here</link>.
</p>
@@ -66,23 +65,23 @@
<s1 title="How do I contribute, give feedback, fix bugs and so on?">
<p>
- We really need and appreciate any contributions you can give, including
- documentation help, source code and feedback. Discussion about changes
- should come in the form of source code and/or very detailed and well thought
- out constructive feedback.
+ The Velocity project really needs and appreciates any contributions
+ you can offer, including documentation help, source code and feedback.
+ Discussion about changes should come in the form of source code and/or
+ very detailed and considered constructive feedback.
</p>
<ul>
<li>
- We have a complete list of <link href="contributors.html">Active
Developers</link>.
+ There is a list of <link href="contributors.html">Active Developers</link>.
Submit some code and get your name added!</li>
<li>
- We have a <link
href="http://jakarta.apache.org/getinvolved/mail.html">Velocity mailing
- list</link> for discussion.</li>
+ Discussion occurs on the <link
href="http://jakarta.apache.org/getinvolved/mail.html">Velocity mailing
+ list</link>.</li>
<li>
Access to the CVS "<strong>jakarta-velocity</strong>" repository is
available both
<link
href="http://jakarta.apache.org/cvsweb/index.cgi/jakarta-velocity/">online</link>
- as well as with a <link
href="http://jakarta.apache.org/getinvolved/cvsindex.html">cvs client</link>.</li>
+ and with a <link
href="http://jakarta.apache.org/getinvolved/cvsindex.html">cvs client</link>.</li>
</ul>
</s1>
1.4 +2 -2 jakarta-velocity/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/install.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- install.xml 2000/09/30 20:11:47 1.3
+++ install.xml 2000/10/03 01:10:18 1.4
@@ -52,8 +52,8 @@
<p>
If you get a compiler error related to one or more packages that could not
- be found, ensure the build-velocity script is edited to properly specify
- the paths to each of the packages that could not be found.
+ be found, ensure the build-velocity script you are using is edited to
+ properly specify the paths to each of the packages that could not be found.
</p>
</s1>
1.3 +90 -43 jakarta-velocity/xdocs/script-elements.xml
Index: script-elements.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/script-elements.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- script-elements.xml 2000/09/30 20:11:47 1.2
+++ script-elements.xml 2000/10/03 01:10:18 1.3
@@ -16,10 +16,14 @@
<p>
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. All of the elements
are
- prefixed with a #. For example, #if, #foreach, #set.
+ href="design.html">Design Document</link>.
</p>
+
+ <p>
+ The following elements are currently defined within Velocity and also
+ explained in detail below. Velocity script elements are prefixed with a #.
+ For example, #if, #foreach, #set.
+ </p>
<ul>
<li><strong>Variables</strong></li>
<li><strong>Conditionals</strong>:
@@ -39,6 +43,7 @@
<li><strong>Set</strong></li>
<li><strong>Comment</strong></li>
<li><strong>Stop</strong></li>
+ <li><strong>Macro</strong></li>
</ul>
</s1>
@@ -61,14 +66,14 @@
These examples illustrate 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 that can then be evaluated.
+ as well as the objects methods. It is possible to embed variables almost
+ anywhere in your template. These variables can 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
+ Everything coming to and from a variable is treated as a String object.
+ If there is an object that represents $foo (such as an Integer object),
+ then Velocity will call its .toString() method to resolve the
object into a String.
</p>
</s1>
@@ -77,8 +82,9 @@
<s1 title="If / Else Conditionals">
<p>
- The #if statement in Velocity allows you to conditionally include the text
- within the brackets. For example:
+ The #if statement in Velocity allows for text in the brackets to be
+ included in the text, on the conditional that the if statement
+ is true. For example:
</p>
<p>
@@ -94,12 +100,10 @@
content within the brackets becomes the output if the evaluation is true.
Unlike in JSP, Velocity does not force web developers to wrap HTML code
within an out.println(), or to delve into ugly workarounds to out.println().
- This results in a more MVC solution.
</p>
<p>
- Another example is that you can include #else elements with your #if
- element.
+ An #else element can be used with an #if element.
</p>
<p>
@@ -113,10 +117,16 @@
<strong>Velocity Still Rocks!</strong>
}]]></source>
</p>
+
+ <p>
+ In this example, if $foo is false, then the output will be
+ <strong>Velocity Still Rocks!</strong>
+ </p>
<p>
- Note: Logical operators, illustrated by an example below, are not yet
- available in Velocity. This functionality is expected to be added soon.
+ Note that logical operators are not yet available in Velocity.
+ This functionality is expected to be added soon. An example of
+ a logical operator is shown below.
</p>
<p>
@@ -129,10 +139,9 @@
<p>
Nested #if statements can be used to emulate the functionality of #elseif.
- Nesting elements
- works for all elements to an infinite level of nesting. For example,
- you can nest a #foreach within an #if. We will be considering in the future
- of adding a #elseif to simplify things.
+ Nesting elements work for all elements to an infinite level of nesting;
+ for example, a #foreach can be nested within an #if. An #elseif element
+ may be added in the future to simplify things.
</p>
</s1>
</s1>
@@ -140,13 +149,15 @@
<s1 title="Loops">
<s1 title="Foreach Loop">
<p>
- The #foreach element allows for looping. For example:
+ The #foreach element allows for looping. The #foreach element is followed
+ by a set of brackets that enclose the target and object to be stepped
+ through. For example:
</p>
<p>
<source><![CDATA[
<ul>
- #foreach $product in $allProducts
+ #foreach ($product in $allProducts)
{
<li>$product</li>
}
@@ -155,27 +166,28 @@
</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.
+ This #foreach loop causes the $allProducts list (the object) to be
+ looped over for all of the products (targets) 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. The value assigned to the $product variable is a Java
+ The contents of the $allProducts variable is either a Vector, a Hashtable
+ or an Array. The value assigned to the $product variable is a Java
Object and can be referenced from a variable as such. 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()).
+ $product was really a Product class in Java, its name could be retrieved
+ 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.
+ The #parse script element allows a local files to be imported and parsed
+ through the Velocity template engine, then 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>
@@ -214,9 +226,9 @@
</p>
<p>
- Unlike WebMacro, the variable on the left side of teh #param script element
- must be prefixed with a $. This provides a consistent syntax for
- referencing variables.
+ The variable on the left side of the #param script element must be
+ prefixed with a $. This provides a consistent syntax for referencing
+ variables in Velocity.
</p>
</s1>
@@ -233,15 +245,13 @@
</p>
<p>
- Unlike WebMacro, when using the #set directive, the variable on the
- left side must be prefixed with a $. This provides a consistent
- syntax for referencing variables.
+ When using the #set directive, the variable on the left side must be
+ prefixed with a $. This provides a
+ consistent syntax for referencing variables in Velocity.
</p>
<p>
- Currently, the above examples are the only directives that have been
- implemented. We will eventually support the full range of WebMacro
- functionality.
+ The following script elements have not been implemented.
</p>
</s1>
@@ -259,8 +269,8 @@
<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.
+ is not removed from the template. The newlines created be these comments
+ will soon be removed.
</p>
</s1>
@@ -275,6 +285,43 @@
#stop
]]></source>
</p>
+</s1>
+
+<s1 title="Macro">
+ <p>
+ With the #macro script element, the template designer can define a
+ time-saving macro.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #macro (row $content) <tr><td>$content</td></tr> #end
+ ]]></source>
+ </p>
+
+ <p>
+ This establishes a macro called "row", which uses HTML tags to
+ put content into its own table data cell in an HTML table. Having
+ defined the #row macro, the template designer can now call the #row
+ macro by name.
+ </p>
+
+ <p>
+ <table>
+ #foreach ($element in $list)
+ #row ($element)
+ #end
+ </table>
+ ]]></source>
+ </p>
+
+ <p>
+ Here a newly created #row macro is nested inside a #foreach
+ statement. As the #foreach statement loops through each $element
+ target in the $list object, the #row macro will take the value of
+ $element and put it into its table data cell.
+ </p>
+
</s1>
</body>
