You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by jc...@locus.apache.org on 2000/12/12 06:08:06 UTC
cvs commit: jakarta-velocity/xdocs vtl-reference-guide.xml texen.xml install.xml
jcastura 00/12/11 21:08:06
Modified: xdocs vtl-reference-guide.xml texen.xml install.xml
Log:
edits
Revision Changes Path
1.13 +79 -21 jakarta-velocity/xdocs/vtl-reference-guide.xml
Index: vtl-reference-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/vtl-reference-guide.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- vtl-reference-guide.xml 2000/10/27 02:26:34 1.12
+++ vtl-reference-guide.xml 2000/12/12 05:08:06 1.13
@@ -18,6 +18,11 @@
this reference guide and links should be made from
the user's guide to this document
+I now envision the user guide to be a long, pedagogical
+book and the VTL guide to be a distillation of VTL for
+expert users and fast learners. I'd like each directive to
+have an identical format.
+
-->
<s1 title="About this Guide">
@@ -207,25 +212,24 @@
<p>
<strong>#set</strong>
<br/>
- The #set directive is used for setting the value of
- a reference. A value can be assigned to either a variable
- reference or a property reference:
+ The <vtldirective>#set</vtldirective> directive is used to
+ set the value of a reference.
</p>
<p>
<source><![CDATA[
- #set $primate = "monkey"
- #set $customer.Behavior = $primate
+ #set ($ref = arg)
]]></source>
</p>
<p>
- The left hand side (LHS) of the assigment must be
- a variable reference or a property reference. The
- right hand side (RHS) can be one of the following:
+ <vtl>$ref</vtl> - The LHS of the assigment must be
+ a variable reference or a property reference.
</p>
<p>
+ <vtl>$arg</vtl> - The RHS is limited to the following
+ types:
<ul>
<li>Variable reference</li>
<li>String literal</li>
@@ -239,16 +243,16 @@
<p>
Here are examples demonstrating the
aforementioned types:
-</p>
+</p>
<p>
<source><![CDATA[
- #set $monkey = $bill
- #set $monkey.Friend = "monica"
- #set $monkey.Blame = $whitehouse.Leak
- #set $monkey.Plan = $spindoctor.weave($web)
- #set $monkey.Number = 123
- #set $monkey.Say = ["Not", $my, "fault"]
+ #set ($monkey = $bill)
+ #set ($monkey.Friend = "monica")
+ #set ($monkey.Blame = $whitehouse.Leak)
+ #set ($monkey.Plan = $spindoctor.weave($web))
+ #set ($monkey.Number = 123)
+ #set ($monkey.Say = ["Not", $my, "fault"])
]]></source>
</p>
@@ -258,18 +262,19 @@
<p>
<source><![CDATA[
- #set $value = $foo + 1
- #set $value = $bar - 1
- #set $value = $foo * $bar
- #set $value = $foo / $bar
+ #set ($value = $foo + 1)
+ #set ($value = $bar - 1)
+ #set ($value = $foo * $bar)
+ #set ($value = $foo / $bar)
]]></source>
</p>
+
<p>
<strong>#foreach</strong>
<br/>
- The #foreach directive provides a simple way of looping
- through a list of objects:
+ The <vtldirective>#foreach</vtldirective> directive
+ provides a simple way of looping through a list of objects.
</p>
<p>
@@ -328,7 +333,60 @@
]]></source>
</p>
+
+ <strong>#macro</strong>
+
+ <p>
+ A Velocimacro is defined with the <vtldirective>#macro</vtldirective>
+ directive.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #macro (vmname arg1 arg2)
+ <VM VTL code>
+ #end
+ ]]></source>
+ </p>
+
+ <p>
+ <vtl>vmname</vtl> - The name that will be used to call the VM (<vtl>#vmname</vtl>)
+ </p>
+
+ <p>
+ <vtl>arg1 arg2</vtl> - Arguments to the VM. A VM can have any number of argumentss,
+ but the number used at invocation must match the number specified in the
+ definition.
+ </p>
+
+ <p>
+ <vtl><VM VTL code></vtl> - Any valid VTL code, anything you can put into a
+ template, can be put into a VM.
+ </p>
+
+ <p>
+ Once defined, the VM is used like any other VTL directive in your template.
+ </p>
+
+ <p>
+ <source><![CDATA[
+ #vmname( arg1 arg2 )
+ ]]></source>
+ </p>
+
+ <p>
+ VMs can be defined in a 'global library', a 'local library', or
+ 'inline' in a template. Both global library and local libraries can be
+ accessed by any template. The global library contains VMs pre-packaged
+ with Velocity; the local library allows end users to supplement the
+ pre-packaged VMs with customized, site-specific VMs. Inline VM
+ definitions are those found in regular 'user' templates, although
+ these can only be used when the <vtl>velocimacro.permissions.allowInline=true</vtl>
+ in the <filename>velocity.properties</filename> file.
+ </p>
+
</s1>
</body>
</document>
+
1.2 +23 -29 jakarta-velocity/xdocs/texen.xml
Index: texen.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/texen.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- texen.xml 2000/11/08 17:30:02 1.1
+++ texen.xml 2000/12/12 05:08:06 1.2
@@ -15,26 +15,24 @@
<s1 title="What is Texen?">
<p>
- Texen is a general purpose text generating utility. You can
- use it to easily produce any sort of text output. Texen uses a
- control template, an optional set of worker templates, and control context
- to govern the generated output. Texen is driven by Ant, and in
- essense Texen is an <link href="http://jakarta.apache.org/ant/">Ant</link>
- Task. You can use the TexenTask directly
- if you wish, but it general you will probably subclass the
- TexenTask in order to initialize your control context before
- generating any output.
+ Texen is a general purpose text generating utility. It is capable of
+ producing almost any sort of text output. Driven by Ant, essentially
+ an <link href="http://jakarta.apache.org/ant/">Ant</link>
+ Task, Texen uses a control template, an optional set of worker templates,
+ and control context to govern the generated output. Although TexenTask
+ can be used directly, it is usually subclassed to initialize your control
+ context before generating any output.
</p>
<p>
- Texen was originally created to deal with the source generating
- requirements of Turbine web application framework. The
+ Texen was created to deal with the source generating
+ requirements of the Turbine web application framework. The
<link href="http://java.apache.org/turbine/torque.html">Torque</link>
utility in <link href="http://java.apache.org/turbine/">Turbine</link>,
which is a subclass of the TexenTask, is responsible
for generating the SQL, and the Object-Relational mapping sources
- for a Turbine project. This is only one example, you can use
- Texen to generate any sort of text output!
+ for a Turbine project. This is only one example; you can use
+ Texen to generate almost any sort of text output!
</p>
</s1>
@@ -42,10 +40,8 @@
<s1 title="The TexenTask">
<p>
- As mentioned previously, Texen is essentially an Ant Task. This
- is a trivial example of how you would use Texen from an Ant build.xml.
- This example is not very useful, but shows how the Texen mechanism
- works.
+ This trivial example, which shows how to use Texen from an Ant build.xml,
+ is intended to illustrate how the Texen mechanism works.
</p>
<p>
@@ -117,9 +113,9 @@
file: HtmlTemplate.vm
-This is worker template, it is called by the
-control template to produce useful output, or
-not so useful in this case :-)
+This is worker template. It is called by the
+control template to produce useful output (or
+not so useful in this case). :-)
*#
@@ -142,20 +138,18 @@
</p>
<p>
- What will be produced are three html pages: Earth.html,
- Mars.html, and Venus.html. This is a contrived example but
- hopefully illustrates how the mechanism works. To do something
- useful you would subclass the TexenTask, place some objects
- in the control context and use the information placed in the
+ Texen produces three html pages: Earth.html,
+ Mars.html, and Venus.html. To do something
+ more useful, you would subclass the TexenTask, place some objects
+ in the control context, and use the information placed in the
control context to generate useful output.
</p>
<p>
- For a full working example of Texen, take a look at the Torque
- utility in Turbine. There is a stand-alone version of Torque
- available <link href="http://java.apache.org/turbine/tdk/">here</link>.
+ See the Torque utility in Turbine for a full working example of Texen.
+ A standalone version of Torque is available
+ <link href="http://java.apache.org/turbine/tdk/">here</link>.
</p>
-
</s1>
1.10 +5 -5 jakarta-velocity/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/install.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- install.xml 2000/11/23 00:35:12 1.9
+++ install.xml 2000/12/12 05:08:06 1.10
@@ -20,9 +20,9 @@
</p>
<p>
- Everything required to build Velocity comes with the distribution, which
- be obtained via <link href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</link>
- or <link href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">downloaded</link>.
+ Everything required to build Velocity comes with the distribution, which can
+ be obtained from <link href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</link>
+ or from the <link href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">nightly builds</link>.
</p>
</s1>
@@ -30,7 +30,7 @@
<s1 title="Compiling">
<p>
- On Unix/Linux, <code>cd</code> to the <filename>velocity/build</filename> directory and execute the following
+ On Unix, <code>cd</code> to the <filename>velocity/build</filename> directory and execute the following
script:
</p>
@@ -50,7 +50,7 @@
Executing this script will create a <filename>bin</filename> directory within the Velocity
distribution directory. The <filename>bin</filename> directory will contain the compiled class
files (inside a <filename>classes</filename> directory) as well as a <filename>velocity.jar</filename> file.
- Be sure to update your classpath to include Velocity's .jar file.
+ Be sure to update your classpath to include Velocity's <filename>.jar</filename> file.
</p>
<p>
Re: cvs commit: jakarta-velocity/xdocs vtl-reference-guide.xml texen.xml
install.xml
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
Christoph Reck wrote:
>
> jcastura@locus.apache.org wrote:
> > I'd like each directive to have an identical format.
>
> Then we should normalize the position of the brakets, e.g.
> we should use:
> #set( $value = $foo + 1 )
> as-well-as:
> #if( condition )...#else...#end
> and:
> #macro( vmname arg1 arg2 )
> to match:
> #vmname( arg1 arg2 )
> Note that I'm recommending to glue the bracket to the directive
> and place spaces after the openingand before the closing bracket.
+1
> This way:
> 1. All directive explanations in the user and reference guides
> follow the same pattern (look and coding-standard of a directive).
> 2. It is clear that the spaces within the brakets are only
> relevant to the directive.
> 3. Within some editors (CDE selects up to a whitespace) it is easyer
> to double click the text or the argument to copy-and-paste...
>
> Thanks for your important and unique contribution to Vel!
>
> :) Christoph
--
Geir Magnusson Jr. geirm@optonline.com
Velocity : it's not just a good idea. It should be the law.
http://jakarta.apache.org/velocity
Re: cvs commit: jakarta-velocity/xdocs vtl-reference-guide.xml texen.xml
install.xml
Posted by Christoph Reck <Ch...@dlr.de>.
jcastura@locus.apache.org wrote:
> I'd like each directive to have an identical format.
Then we should normalize the position of the brakets, e.g.
we should use:
#set( $value = $foo + 1 )
as-well-as:
#if( condition )...#else...#end
and:
#macro( vmname arg1 arg2 )
to match:
#vmname( arg1 arg2 )
Note that I'm recommending to glue the bracket to the directive
and place spaces after the openingand before the closing bracket.
This way:
1. All directive explanations in the user and reference guides
follow the same pattern (look and coding-standard of a directive).
2. It is clear that the spaces within the brakets are only
relevant to the directive.
3. Within some editors (CDE selects up to a whitespace) it is easyer
to double click the text or the argument to copy-and-paste...
Thanks for your important and unique contribution to Vel!
:) Christoph