You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2001/02/08 06:43:03 UTC
cvs commit: jakarta-velocity/docs developer-guide.html
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.