geirm 01/02/07 21:43:03
Modified: docs developer-guide.html
Log:
rendered developer-guide...
Revision Changes Path
1.8 +259 -2 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- developer-guide.html 2000/11/23 01:29:29 1.7
+++ developer-guide.html 2001/02/08 05:43:02 1.8
@@ -23,14 +23,271 @@
-<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>Developer's
Guide</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0"
width="5"><B>Introduction</B></FONT></TD></TR><TR><TD><IMG border="0" height="5"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE
border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<P align="justify">
+Velocity is a Java-based template engine, a simple and powerful development tool
that allows you to easily create and render
+'documents' that format and present your data.
+In this document, we hope to give an overview of the basics of development using
Velocity, focusing on the two main areas for Velocity usage :
+
+<BLOCKQUOTE><UL>
+<LI> servlet-based WWW development</LI>
+<LI> general application use</LI>
+</UL></BLOCKQUOTE>
+
+You will see that there is no real difference between these, other than we make
servlet development with Velocity very easy
+if you use our provided class VelocityServlet as a base class for your servlet.
+</P>
+</FONT></TD></TR></TABLE></DIV><BR>
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0"
width="5"><B>Resources</B></FONT></TD></TR><TR><TD><IMG border="0" height="5"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE
border="0" cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
<P align="justify">
- This is still in progress. It will be here soon.
+There are quite a few resources and examples available to the programmer, and we
recommend that you look at our examples, documentation and even the source code. They
are found in
+
+<BLOCKQUOTE><UL>
+<LI> source code : /src/java/...</LI>
+<LI> general examples : /examples </LI>
+<LI> Anakia application : example application showing how to use Velocity for
creating stylesheet renderings of xml data
+- /examples/anakia </LI>
+<LI> Forumdemo web app : working example of a simple servlet-based forum
application - /examples/forumdemo</LI>
+<LI> documentation : /docs</LI>
+<LI> templates : for the designer, we have a large collection of template examples
in our testbed directory - /test/templates</LI>
+</UL></BLOCKQUOTE>
+
+All directory references above are relative to the distribution root directory.
</P>
+</FONT></TD></TR></TABLE></DIV><BR>
+
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>The Fundamental Code
Pattern</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<P align="justify">
+When using Velocity in an application program or in a servlet (or anywhere,
actually), you will generally do the following :
+
+<BLOCKQUOTE><OL>
+<LI>Create a Context object (more on what that is later).</LI>
+<LI>Add your data objects to the Context.</LI>
+<LI>Choose a template.</LI>
+<LI>'Merge' the template and your data to produce the ouput.</LI>
+</OL></BLOCKQUOTE>
+In code, this looks like
+
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+import java.io.StringWriter;
+import org.apache.velocity.VelocityContext;
+import org.apache.velocity.runtime.Runtime;
+
+VelocityContext context = new VelocityContext();
+
+context.put( "name", new String("Velocity") );
+
+Template template = null;
+
+try
+{
+ template = Runtime.getTemplate("mytemplate.vm");
+}
+catch( Exception e )
+{}
+
+StringWriter sw = new StringWriter();
+
+template.merge( context, sw );
+
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+</P>
+<P align="justify">
+Thats the basic pattern. It is very simple, isn't it?
+</P>
</FONT></TD></TR></TABLE></DIV><BR>
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>The
Context</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<B>The Basics</B>
+<P align="justify">
+The concept of the 'context' is central to Velocity, and is a common technique for
moving a container of data around between
+parts of a system. The idea is that the context is a 'carrier'
+of data between the Java layer (or you the programmer) and the template layer ( or
the designer ). You as the programmer will
+gather objects of various types, whatever your application calls for, and place
them in the context. To the designer, these
+objects, and their methods and properties, will become accessable via template
elements called
+<A href="vtl-reference-guide.html"> references</A>. Generally, you will work with
the designer to determine the data
+needs for the application, and the 'API' that you are in a way creating as you
produce a data set for the designer to access
+in the template.
+</P>
+
+<P align="justify">
+While Velocity allows you to create your own context classes to support special
needs and techniques (like a context that
+accesses an LDAP server directly, for example), a good basic implementation class
called VelocityContext is provided for you
+as part of the distribution.
+</P>
+<P align="justify">
+VelocityContext is suitable for all general purpose needs, and we strongly
recommended that you use it. Only in exceptional
+and advanced cases will you need to extend or create your own context
implementation.
+</P>
+<P align="justify">
+Using VelocityContext is as simple as using a normal Java Hashtable class. While
the interface contains other useful methods,
+the two main methods you will use are
+
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+ public Object put(String key, Object value);
+ public Object get(String key);
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+Please note that like a Hashtable, the value must be derived from java.lang.Object,
and must not be null.
+Fundamental types like int or float must be wrapped in the appropriate wrapper
classes.
+</P>
+<P align="justify">
+That's really all there is to basic context operations. For more information, see
the API documentation included in the distribution.
+</P>
+
+<B>Context Chaining</B>
+<P align="justify">
+An innovative feature of Velocity's context design is the concept of context
chaining.
+Also sometimes referred to as context wrapping, this advanced feature allows you to
connect separate contexts together in a
+manner that makes it appear as one 'contiguous' context to the template.
+</P>
+<P align="justify">
+This is best illustrated by an example :
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+ VelocityContext context1 = new VelocityContext();
+
+ context1.put("name","Velocity");
+ context1.put("project", "Jakarta");
+ context1.put("duplicate", "I am in context1");
+
+ VelocityContext context2 = new VelocityContext( context1 );
+
+ context2.put("lang", "Java" );
+ context2.put("duplicate", "I am in context2");
+
+ template.merge( context2, writer );
+
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+In the code above, we have set up context2 such that it chains context1. This
means that in the template,
+you can access any of
+the items that were put into either of the two VelocityContext objects, as long as
there is no duplication of the keys
+used to add objects. If that is the case, as it is above for the key 'duplicate',
the object stored in the nearest
+context in the chain will be available. In this example above, the object returned
would be the string "I am in context2".
+</P>
+<P align="justify">
+Note that this duplication, or 'covering', of a context item does not in any way
harm or alter the covered object. So in the example above, the string "I am in
context1" is alive and well, still accessable via
context1.get("duplicate"). But in the example
+above, the value of the reference '$duplicate' in the template would be 'I am in
context2', and the template has no access to
+the covered string 'I am in context1'.
+</P>
+<P align="justify">
+This feature has many uses, the most common so far is providing layered data access
and toolsets.
+</P>
+<P align="justify">
+As mentioned before, the Velocity context mechanism is also extendable, but beyond
the current scope of this document.
+If you are interested, please see the classes in the package
+org.apache.velocity.context to see how the provided contexts are put together.
Futher, there are a few examples in the examples
+directory in the distribution which show alternate implementaions, including [a
goofy] one
+that uses a database as the backing storage.
+Please note that these examples are unsupported and are there for
demonstration/educational purposes only.
+</P>
+
+</FONT></TD></TR></TABLE></DIV><BR>
+
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>Using Velocity In
Servlets</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<B>Programming</B>
+<P align="justify">
+The most common use of Velocity is in the are of Java Servlet programming for the
WWW. There are many reasons why Velocity is
+well suited for this task, the primary one is Velocity's enforcement of the
separation of the presentation (or view) layer from
+the code layer. There are many resources on this subject, including <A
href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">this</A>.
+</P>
+<P align="justify">
+The basic technique of using Velocity in a servlet environment is very simple. In
a nutshell, all you must do is
+extend the provided VelocityServlet base class and implement a single method
handleRequest(). That's really all that is required
+to use Velocity in your servlet development.
+</P>
+<P align="justify">
+The following code is similar to the
+SampleServlet.java class included in the distribution in the examples directory.
+
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+public class SampleServlet extends VelocityServlet
+{
+ public Template handleRequest( Context context )
+ {
+ Template template = null;
+
+ String p1 = "Jakarta";
+ String p2 = "Velocity";
+
+ Vector vec = new Vector();
+ vec.addElement( p1 );
+ vec.addElement( p2 );
+
+ context.put("list", vec );
+
+ try
+ {
+ template = getTemplate("sample.vm");
+ }
+ catch( Exception e )
+ {}
+
+ return template;
+ }
+}
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+</P>
+<P align="justify">
+Look familiar? With the exception of creating the context object, which is done
for you by the VelocityServlet base class,
+ and the merge() step which is also done for you by the VelocityServlet base
class,
+it's identical to the basic code pattern we mentioned at the beginning of this
document.
+We take the context, add our application data, and return a template.
+</P>
+<B>Deployment</B>
+<P align="justify">
+When you deploy your Velocity-based servlets, you will certainly want to ensure
that your properties file is used to configure
+the Velocity runtime. Under Tomcat, one way to accomplish this is by placing your
velocity.properties file into the root
+directory of your web app (webapps/appname ) and then add the following to your
WEB-INF/web.xml file :
+<DIV align="center"><TABLE border="0" cellpadding="0" cellspacing="4"><TR><TD
bgcolor="#023264" height="1" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif" vspace="0"
width="1"></TD><TD bgcolor="#023264" height="1" width="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD
bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#ffffff"><PRE>
+<servlet>
+ <servlet-name>MyServlet</servlet-name>
+ <servlet-class>com.foo.bar.MyServlet</servlet-class>
+ <init-param>
+ <param-name>properties</param-name>
+ <param-value>velocity.properties</param-value>
+ </init-param>
+</servlet>
+</PRE></TD><TD bgcolor="#023264" width="1"><IMG border="0" height="1" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD><TD bgcolor="#023264" height="1"><IMG border="0" height="1"
hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#023264"
height="1" width="1"><IMG border="0" height="1" hspace="0" src="resources/void.gif"
vspace="0" width="1"></TD></TR></TABLE></DIV>
+
+Assuming all is right, this will ensure that when MyServlet is loaded, it will use
the velocity.properties file to initialize itself
+rather than relying on it's internal defaults.
+</P>
+<P align="justify">
+Note that Velocity uses a singleton model for it's central core Runtime class, so
it is a very good idea to put the velocity-XX.jar
+into the WEB-INF/lib directory in all web applications that use Velocity to ensure
that the web app classloader is
+managing your Runtime instance,
+rather than putting it in the CLASSPATH or the top level lib directory of the
servlet runner.
+</P>
+<P align="justify">
+This deployment method will ensure that different web applications will not be
subject to Velocity configuration conflicts.
+</P>
+</FONT></TD></TR></TABLE></DIV><BR>
+
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="5"><B>Velocity
Properties</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+<P align="justify">
+Velocity's runtime configuration is controlled by regular Java properties. There
is a set of default properties, found in
+/src/java/org/apache/velocity/runtime/defaults/velocity.defaults, that Velocity
uses as it's configuration baseline. Any
+properties specified at init() time will replace existing values. This ensures
that Velocity will always have a 'correct' value
+for it's configuration and startup. These may not be the values you want, of
course.
+</P>
+</FONT></TD></TR></TABLE></DIV><BR>
+
+<DIV align="right"><TABLE border="0" cellpadding="0" cellspacing="0"
width="98%"><TR><TD bgcolor="#023264" width="100%"><FONT color="#ffffff"
face="arial,helvetica,sanserif" size="+1"><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0"
width="5"><B>Summary</B></FONT></TD></TR><TR><TD><IMG border="0" height="5" hspace="0"
src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE><TABLE border="0"
cellpadding="0" cellspacing="0" width="98%"><TR><TD><FONT color="#000000"
face="arial,helvetica,sanserif">
+
+<P align="justify">
+We hope this brief document was a helpful introduction to using Velocity in your
Java projects, and thank you for you interest
+in Velocity. We welcome any and all comments
+you may have about this documentation and the Velocity template engine itself.
+</P>
+<P align="justify">
+Please submit all detailed, thoughtful and constructive feedback through our
+<A href="http://jakarta.apache.org/getinvolved/mail.html">mail lists</A>.
+</P>
+</FONT></TD></TR></TABLE></DIV><BR>
</TD></TR></TABLE></TD></TR></TABLE><BR><TABLE border="0" cellpadding="0"
cellspacing="0" width="100%"><TR><TD bgcolor="#023264"><IMG height="1"
src="resources/resources.gif" width="1"></TD></TR><TR><TD align="center"><FONT
color="#023264" face="arial,helvetica,sanserif" size="-1"><I>
Copyright © 2000 The Apache Software Foundation.
