Author: wglass
Date: Sun Jul 17 15:13:20 2005
New Revision: 219403
URL: http://svn.apache.org/viewcvs?rev=219403&view=rev
Log:
removed all outdated servlet references from dev guide
Modified:
jakarta/velocity/core/trunk/src/java/org/apache/velocity/app/tools/VelocityFormatter.java
jakarta/velocity/core/trunk/xdocs/docs/developer-guide.xml
Modified:
jakarta/velocity/core/trunk/src/java/org/apache/velocity/app/tools/VelocityFormatter.java
URL:
http://svn.apache.org/viewcvs/jakarta/velocity/core/trunk/src/java/org/apache/velocity/app/tools/VelocityFormatter.java?rev=219403&r1=219402&r2=219403&view=diff
==============================================================================
---
jakarta/velocity/core/trunk/src/java/org/apache/velocity/app/tools/VelocityFormatter.java
(original)
+++
jakarta/velocity/core/trunk/src/java/org/apache/velocity/app/tools/VelocityFormatter.java
Sun Jul 17 15:13:20 2005
@@ -36,7 +36,11 @@
* $formatter.formatArray($array)
* $formatter.limitLen(30, $object.Description)
* </pre></code>
- *
+ *
+ * @deprecated This servlet has been replaced by NumberTool and DateTool,
+ * both available from the Velocity-Tools sub-project.
+ * VelocityFormatter will be removed in a future version of Velocity.
+ *
* @author <a href="[EMAIL PROTECTED]">Sean Legassick</a>
* @author <a href="[EMAIL PROTECTED]">Daniel Rall</a>
* @version $Id$
Modified: jakarta/velocity/core/trunk/xdocs/docs/developer-guide.xml
URL:
http://svn.apache.org/viewcvs/jakarta/velocity/core/trunk/xdocs/docs/developer-guide.xml?rev=219403&r1=219402&r2=219403&view=diff
==============================================================================
--- jakarta/velocity/core/trunk/xdocs/docs/developer-guide.xml (original)
+++ jakarta/velocity/core/trunk/xdocs/docs/developer-guide.xml Sun Jul 17
15:13:20 2005
@@ -49,15 +49,7 @@
</li>
<li>
-<a href="developer-guide.html#Using Velocity In Servlets">Using Velocity in
Servlets</a>
-<ul>
-<li><a href="developer-guide.html#Servlet Programming">Servlet
Programming</a></li>
-<li><a href="developer-guide.html#Deployment">Deployment</a></li>
-</ul>
-</li>
-
-<li>
-<a href="developer-guide.html#Using Velocity In General Applications">Using
Velocity in General Applications</a>
+<a href="developer-guide.html#Using Velocity">Using Velocity in General
Applications</a>
<ul>
<li><a href="developer-guide.html#The Velocity Helper Class">The Velocity
Helper Class</a></li>
<li><a href="developer-guide.html#Exceptions">Exceptions</a></li>
@@ -113,33 +105,9 @@
</li>
<li>
-<a href="developer-guide.html#FAQ (Frequently Asked Questions)">FAQ
(Frequently Asked Questions)</a>
-<ul>
- <li><a href="#FAQ1">Why Can't I Access Class Members and Constants from
VTL?</a></li>
- <li><a href="#FAQ2">Where does Velocity look for Templates?</a></li>
- <li><a href="#FAQ3">How to I tell Velocity to use my custom
directive?</a></li>
-</ul>
-</li>
-
-<li>
<a href="developer-guide.html#Summary">Summary</a>
</li>
-<li>
-<a href="developer-guide.html#Appendix 1 : Deploying the Example
Servlet">Appendix 1 : Deploying the Example Servlet</a>
-<ul>
- <li>
- <a href="developer-guide.html#TomcatExample">Jakarta Tomcat</a>
- </li>
- <li>
- <a href="developer-guide.html#ResinExample">Caucho Technology's Resin</a>
- </li>
- <li>
- <a href="developer-guide.html#WebLogic">BEA WebLogic</a>
- </li>
- </ul>
-</li>
-
</ol>
</p>
</section>
@@ -149,164 +117,50 @@
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 guide, we hope to give an overview of the basics of
-development using Velocity, focusing on the two main areas for Velocity usage :
+development using Velocity.
+
+<p>
+<strong>Building Web Applications with Velocity</strong>
+</p>
+Velocity is often used for building web applications
+In order to use Velocity in a web app you'll need a servlet or servlet-based
+framework. The easiest way to get started is with
+<a
href="http://jakarta.apache.org/velocity/tools/view/";>VelocityViewServlet</a>
in the
+<a href="http://jakarta.apache.org/velocity/tools/";>Velocity Tools</a>
+subproject. You can also use any of a number of
+<a href="http://wiki.apache.org/jakarta-velocity/PoweredByVelocity";>third
party frameworks</a>
+or build your own servlet using the techniques described in this document.
</p>
-<ul>
-<li>servlet-based WWW development</li>
-<li>general application use</li>
-</ul>
+<p>
+We suggest you read this article on
+<a href="../webapps.html">getting started with web applications</a> for
+more detail on the various options.
+</p>
<p>
-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, and offer a utility class to
-help with application development.
+<strong>Downloading Velocity</strong>
</p>
<p>
-<strong>Getting Started</strong>
+ You can download the latest release version of
+ <a
href="http://jakarta.apache.org/site/downloads/downloads_velocity-engine.cgi";>Velocity</a>
+ or <a
href="http://jakarta.apache.org/site/downloads/downloads_velocity-tools.cgi";>Velocity
Tools</a>
+ from the main Jakarta download site. For Velocity itself, source is
included with the binary download.
</p>
<p>
-While this information is found elsewhere on the Velocity site and in the
-documentation, it is included here for completeness. Getting Velocity running
on
-your computer is very easy. Note that all directory references are relative
the
-root of the Velocity distribution tree.
-<ol>
- <li>
- Get the Velocity distribution. This is available as a release, nightly
snapshot or
- directly from the Subversion code repository. Any are fine, although for
the latest
- features, the nightly snapshot is most likely the best way. For more
- information, go <a href="index.html">here</a>.
- </li>
- <li>
- If you don't have <a href="http://jakarta.apache.org/ant/";>Jakarta Ant</a>,
- the Java build tool already installed, please do so. It is required for
- building Velocity, although not required for <i>using</i> Velocity.
- </li>
- <li>
- Go to the <code>build</code> directory in the distribution.
- </li>
- <li>
- Type <code>ant <build target></code> where <build target>
- is one of:
- <ul>
- <li>
- <b><code>jar</code></b> builds the complete Velocity jar in the
- <code>bin</code> directory. This jar will be called 'velocity-X.jar',
- where 'X' is the current version number. This jar does not include
- necessary dependencies for Velocity. If you use this
- target, you must get the Collections component jar from Jakarta
Commons and add
- to your CLASSPATH (or WEB-INF/lib).
- If you wish to use the built-in logging or template conversion,
- you must include the appropriate jars in your CLASSPATH or
- webapp's WEB-INF/lib.
- For convenience, you can use the <code>jar-dep</code> target to build
- a jar with ORO, Logkit and Commons Collections included.
- </li>
- <li>
- <b><code>jar-dep</code></b> builds the complete Velocity jar in
- the <code>bin</code> directory, including necessary
- support for logging from the
- <a href="http://jakarta.apache.org/avalon/logkit/index.html";>Jakarta
- Avalon Logkit</a> package, critical configuration support from the
- <a href="http://jakarta.apache.org/commons/";>Jakarta Commons</a>
- and the necesary support for WebMacro
- template conversion using the
- <a href="http://jakarta.apache.org/oro/index.html";>Jakarta ORO</a>
- package.
- </li>
- <li>
- <b><code>jar-core</code></b> builds a slimmer Velocity jar in the
- <code>bin</code> directory, called 'velocity-core-X.jar'. This jar
- contains the core Velocity functionality, and doesn't include example
- and utility things like Anakia, Texen or the VelocityServlet support
- baseclass. It has the same external dependency requirements as the
- regular <code>jar</code> target.
- </li>
- <li>
- <b><code>jar-util</code></b> builds a utility Velocity jar in the
- <code>bin</code> directory, called 'velocity-util-X.jar'. This jar
- contains utility code, specifically Anakia, Texen, and the WebMacro
- template conversion utility. It has the same external dependency
requirements as the
- regular <code>jar</code> target.
- </li>
- <li>
- <b><code>jar-servlet</code></b> builds a utility Velocity jar in the
- <code>bin</code> directory, called 'velocity-servlet-X.jar'. This jar
- contains utility code for servlet programmers. It has the same
external dependency requirements as the
- regular <code>jar</code> target.
- </li>
- <li>
- <b><code>jar-J2EE</code></b> builds a complete jar, like the 'jar'
target,
- that includes any components that require J2EE support. Currently, this
- includes only
org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader.
- As usual, it is placed in the <code>bin</code> directory, called
- 'velocity-j2ee-X.jar'. NOTE : if you wish to use this build target, you
- must place (or link) a copy of j2ee.jar into the build/lib directory.
- We do not provide it as part of the distribution. A good source is
- http://java.sun.com/. It has the same external dependency
requirements as the
- regular <code>jar</code> target.
- </li>
- <li>
- <b><code>jar-J2EE-dep</code></b> build a complete jar with J2EE support
- and includes logging support from the Jakarta Avalon Logkit and
- regexp support fromt the Jakarta ORO package. See the notes on the
- <code>jar-dep</code> target, above.
- </li>
- <li>
- <b><code>examples</code></b> builds the example code in the example
programs
- found in the <code>examples</code> directory. This build target will
- also build the forumdemo example project.
- </li>
- <li>
- <b><code>forumdemo</code></b> builds the example webapplication in the
- <code>examples/forumdemo</code> directory.
- </li>
- <li>
- <b><code>docs</code></b> builds these docs in the <code>docs</code>
directory
- using Velocity's <a href="anakia.html">Anakia</a> XML transformation
tool.
- Allowing you to use
- Velocity templates in place of stylesheets
- - give it a try! <i>Note: This target requires that the jakarta-site2
project
- is located as a peer directory to the jakarta-velocity distribution
directory.
- Please see the note in the build.xml file for this target for further
information.</i>
- </li>
- <li>
- <b><code>jar-src</code></b> bundles all the Velocity source code into
a single
- jar, placed in the <code>bin</code> directory.
- </li>
- <li>
- <b><code>javadocs</code></b> builds the Javadoc class documentation in
the
- <code>docs/api</code> directory
- </li>
- <li>
- <b><code>test</code></b> (after jar) will test Velocity against it's
testbed
- suite of test routines
- </li>
- <li>
- <b><code>help</code></b> lists the build targets that are available.
- </li>
- </ul>
- </li>
- <li>
- While not required, testing the build is a good idea. Use the
- <code>test</code> target mentioned above.
- </li>
- <li>
- That's it! Velocity is ready to be used. Put the jar into your classpath,
or
- into other appropriate places (such as the lib directory of your webapp if
- using with servlets)
- </li>
- <li>
- If you want to play with the examples, which is highly recommended when
- getting started, use build the examples via
- <code>ant examples</code>.
- </li>
-</ol>
+ If you want to download the latest source, you can do so via the
Subversion (svn)
+ source control system, or download a complete
+ <a href="http://cvs.apache.org/snapshots/velocity/";>nightly snapshot.</a>
+</p>
+
+<p>
+ Instructions for building Velocity from source can be found in the
+ <a href="build.html">Build</a> document.
</p>
+
<strong>Dependencies</strong>
<p>
@@ -361,6 +215,16 @@
box to see both our -user and -dev archives.
</li>
<li>
+ Wiki:
+ <a
href="http://wiki.apache.org/jakarta-velocity/";>http://wiki.apache.org/jakarta-velocity/</a>
+ The Velocity wiki contains articles, sample code, and other
community-written content.
+ </li>
+ <li>
+ Frequently Asked Questions (FAQ):
+ <a
href="http://wiki.apache.org/jakarta-velocity/VelocityFAQ";>http://wiki.apache.org/jakarta-velocity/VelocityFAQ</a>
+ please visit this page to read the latest FAQ and to contribute your own
answers.
+ </li>
+ <li>
source code : <code>src/java/...</code> : all the source code to the
Velocity project
</li>
@@ -374,10 +238,6 @@
Velocity application utility class.
</li>
<li>
- servlet example : <code>examples/servlet_example1</code> : a simple example
- showing how to use Velocity in a servlet.
- </li>
- <li>
logger example : <code>examples/logger_example</code> : a simple example
showing how to create a custom logging class and register it with
Velocity to receive all log messages.
@@ -397,10 +257,6 @@
showing how to use Velocity for creating stylesheet renderings of xml data
</li>
<li>
- Forumdemo web app : <code>examples/forumdemo</code> : working example of a
- simple servlet-based forum application
- </li>
- <li>
documentation : <code>docs</code> : all the generated documentation for the
Velocity project in html
</li>
@@ -498,10 +354,7 @@
That's the basic pattern. It is very simple, isn't it? This is generally what
happens when you use Velocity to render a template. You probably won't be
writing code exactly like this - we provide a few tools to help make it even
-easier than this for both servlet and application programmers.
-Later on in this guide, we will talk about using Velocity in both servlets
-as well as general applications, and we discuss the tools we provide to make
-things easier. In each case, though, the above sequence is what is happening
+easier. However, no matter how to use Velocity the above sequence is what is
happening
either explicitly, or behind the scenes.
</p>
@@ -544,7 +397,8 @@
* ourselves as the logger - see logging examples
*/
-Velocity.setProperty( Velocity.RUNTIME_LOG_LOGSYSTEM, this);
+Velocity.setProperty(
+ Velocity.RUNTIME_LOG_LOGSYSTEM, this);
/*
* now initialize the engine
@@ -558,15 +412,6 @@
]]></source>
<p>
-Please note that the Singleton model is used in the
-<code>org.apache.velocity.servlet.VelocityServlet</code> base class,
-a utility class provided with the distribution to make writing servlets
-easier. While extending this class is the most common and convenient
-way to write servlets using Velocity, you are free to not use this
-class if you needs require something different.
-</p>
-
-<p>
<a name="Separate"><strong>Separate Instance</strong></a>
</p>
@@ -599,7 +444,8 @@
* ourselves as a logger (see logging examples..)
*/
-ve.setProperty( VelocityEngine.RUNTIME_LOG_LOGSYSTEM, this);
+ve.setProperty(
+ VelocityEngine.RUNTIME_LOG_LOGSYSTEM, this);
/*
* initialize the engine
@@ -988,260 +834,16 @@
</section>
-<section name="Using Velocity In Servlets">
-
-<a name="Servlet Programming"><strong>Servlet Programming</strong></a>
-
-<p>
-The most common use of Velocity is in the area of Java Servlet programming
-for the WWW. There are many reasons why Velocity is well suited for this
-task, one of the primary ones 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>
-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, <code>handleRequest()</code>. That's really
all that is
-required to use Velocity in your servlet development.
-</p>
-
-<p>
-As of Velocity 1.1, there are two <code>handleRequest()</code> methods :
-
-<br/>
-<br/>
-
-<i><code>public Template handleRequest( Context )</code></i>
-
-<blockquote>
- This is the older of the two methods. This method requires that you
- return a valid Template object. If not valid, or <code>null</code>,
- this is considered an error condition, and will result in the <a
- href="developer-guide.html#error()"><code>error()</code></a> error
- handling method being called. You may override the
- <code>error()</code> if you wish. If returning a <code>null</code> is
- something you expect to do (for example, you will want to redirect
- requests) it is recommended that you use the newer method, listed
- next.
-</blockquote>
- <br/>
-
-<i><code>public Template handleRequest( HttpServletRequest,
HttpServletResponse, Context )</code></i>
-
-<blockquote>
- This is the newer of the two <code>handleRequest()</code> methods,
- implemented in version 1.1. The difference with this method is that
- the <code>HttpServletRequest</code> and
- <code>HttpServletResponse</code> objects are passed to you as
- arguments to the method, as well as in the <code>Context</code>. The
- other difference is that this method can return <code>null</code> to
- indicate that all processing has been handled by the method, and that
- Velocity should do nothing further than call
- <a
href="developer-guide.html#requestCleanup()"><code>requestCleanup()</code></a>.
- This is extremely useful is you wish to redirect the request, for
- example.
-</blockquote>
-
-As always, please refer to the Javadoc API documentation for the definitive and
-latest notes.
-</p>
-
-<p>
-The following code is similar to the SampleServlet.java class included
-in the distribution in the examples directory.
-</p>
-
-<source><![CDATA[
-public class SampleServlet extends VelocityServlet
-{
- public Template handleRequest( HttpServletRequest request,
- HttpServletResponse response,
- Context context )
- {
-
- String p1 = "Jakarta";
- String p2 = "Velocity";
-
- Vector vec = new Vector();
- vec.addElement( p1 );
- vec.addElement( p2 );
-
- context.put("list", vec );
-
- Template template = null;
-
- try
- {
- template = getTemplate("sample.vm");
- }
- catch( ResourceNotFoundException rnfe )
- {
- // couldn't find the template
- }
- catch( ParseErrorException pee )
- {
- // syntax error : problem parsing the template
- }
- catch( Exception e )
- {}
-
- return template;
- }
-}
-]]></source>
-
-<p>
-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 guide.
-We take the context, add our application data, and return a template.
-</p>
-
-<p>
-The default <code>Context</code> object that is passed into the
-<code>handleRequest()</code> methods contains both the current
-<code>HttpServletRequest</code> and <code>HttpServletResponse</code>
-objects. They are placed in the context using the the constants
-<code>VelocityServlet.REQUEST</code> (value = 'req') and
-<code>VelocityServlet.RESPONSE</code> (value = 'res')
-respectively. To access and use these objects in your Java code :
-</p>
-<source><![CDATA[
-public Template handleRequest( Context context )
-{
- HttpServletRequest request = (HttpServletRequest) context.get( REQUEST );
- HttpServletResponse response = (HttpServletResponse) context.get(
RESPONSE );
-
- ...
-]]></source>
-
-<p>
-and in your templates:
-</p>
-
-<source><![CDATA[
-#set($name = $req.getParameter('name') )
-]]></source>
-
-<p>
-For more advanced uses, the VelocityServlet base class allows you to override
-parts of the handling of the request processing. The following methods may
-be overridden :
-<br/>
-<br/>
-
-<i><code> Properties loadConfiguration( ServletConfig )</code></i>
-<blockquote>
- Allows you to override the normal configuration mechanism and add or
- alter the configuation properties. This is useful for overriding or
- augmenting template and log paths, to set the absolute path into the
- webapp root at runtime.
-</blockquote>
-
-<i><a name="createContext()">
-<code>Context createContext(HttpServletRequest, HttpServletResponse
)</code></a></i>
-<blockquote>
- Allows you to create the Context object yourself. This allows more advanced
- techniques, such as chaining or pre-loading with tools or data. The default
- implementation simply returns a VelocityContext object with the request
- and response objects placed inside. The request and response objects are
- wrapped in simple wrapper classes to avoid introspection problems that may
- occurr in some servlet container implementations. You can use the request
- and repsponse objects normally, accessing methods of either from the
- template. Just note that they aren't specifically javax.servlet.XXXX
- classes, if that is important to you.
-</blockquote>
-
-<i><code>void setContentType( HttpServletRequest,HttpServletResponse
)</code></i>
-<blockquote>
- Allows you to examine the request and set the content type yourself,
- depending on the request or client. The default implementation sets
- the content type to be that either specified in the
- velocity.properties, if any, or the default, "text/html" if not
- specified in the properties.
-</blockquote>
-
-<i><code>void mergeTemplate( Template, Context, HttpServletResponse
)</code></i>
-<blockquote>
- Allows you to produce the output stream. The VelocityServlet uses a
- pool of very efficient Writer classes, so this would usually be
- overridden in special situations.
-</blockquote>
-
-<i><a name="requestCleanup()"><code>void requestCleanup( HttpServletRequest,
- HttpServletResponse , Context )</code></a></i>
-<blockquote>
- Allows you to do any cleanup or resource reclamation at the end of the
- request processing. The default does nothing.
-</blockquote>
-
-<i><a name="error()"><code>protected void error( HttpServletRequest,
- HttpServletResponse, Exception )</code></a></i>
-<blockquote>
- Error handler that is called an exception occurrs in request
- processing. Default implementation will send a simple HTML message
- with stacktrace and exception information back to the user. Override
- for custom client messages and more advanced problem handling.
-</blockquote>
-
-For further information, please see the Javadoc
-<a href="api/index.html">API documentation</a>.
-</p>
-
-<a name="Deployment"><strong>Deployment</strong></a>
-
-<p>
-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 :
-</p>
+<section name="Using Velocity">
-<source><![CDATA[
-<servlet>
- <servlet-name>MyServlet</servlet-name>
- <servlet-class>com.foo.bar.MyServlet</servlet-class>
- <init-param>
- <param-name>org.apache.velocity.properties</param-name>
- <param-value>/velocity.properties</param-value>
- </init-param>
-</servlet>
-]]></source>
-
-<p>
-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>
-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>
-This deployment method will ensure that different web applications will
-not be subject to Velocity configuration conflicts.
-</p>
-</section>
-
-<section name="Using Velocity In General Applications">
+<p>If you are using <a
href="http://jakarta.apache.org/velocity/tools/view/";>VelocityViewServlet</a>
+or other web frameworks, you may never call Velocity directly. However, if
you use
+Velocity for non-web purposes, or create your own web framework you will need
+to directly call the Velocity Engine similar to
+<a href="developer-guide.html#The Fundamental Pattern">the fundamental
pattern</a> shown earlier.
+One important additional thing to remember is to initialize the Velocity
Engine before
+using it to merge templates.
-<p>
-As Velocity was designed to be a general-use tool, it is just as useful in
-general application programs as it is servlets. In general, you can use the
-same programming pattern discussed at the beginning of this guide, but there
-are a few utility methods provided for application use, just like we provide
-the VelocityServlet base class for ease of use in servlet programming.
-The only new responsibility you have as the application programmer is to
-initialize the Velocity runtime engine, but that is easy.
</p>
<a name="The Velocity Helper Class"><strong>The Velocity Helper
Class</strong></a>
@@ -1967,7 +1569,7 @@
<p>
<code>resource.loader = <name> (default = file)</code><br/>
-<i>Multi-valued key. Will accept CSV for value.</i> Pulic name of a
+<i>Multi-valued key. Will accept CSV for value.</i> Public name of a
resource loader to be used. This public name will then be used
in the specification of the specific properties for that resource loader.
Note that as a multi-valued key, it's possible to pass
@@ -2421,9 +2023,9 @@
This is the default loader, and is configured, by default to get templates
from the
'current directory'. In the case of using Velocity with servlets, this can
be a problem
as you don't want to have to keep your templates in the directory from which
you start
- your servlet engine. Please see the section on
- <a href="developer-guide.html#Using Velocity In Servlets"> developing
servlets with Velocity</a>
- for more information.
+ your servlet engine. See the documentation for your servlet or web
framework (for example
+ <a
href="http://jakarta.apache.org/velocity/tools/view/";>VelocityViewServlet</a>)
for more
+ info on how to configure the location of the Velocity templates.
</li>
<li>
<b>JarResourceLoader :</b> This loader gets resource from specific jar
files. It is very
@@ -2692,13 +2294,6 @@
</p>
<p>
-<code>org.apache.velocity.servlet.VelocityServlet</code> : <br/>
-<blockquote>
- <i><code> public Template getTemplate( String template, String encoding
)</code></i>
-</blockquote>
-</p>
-
-<p>
<code>org.apache.velocity.app.Velocity</code> : <br/>
<blockquote>
<i><code>public static Template getTemplate(String name, String
encoding)</code></i>
@@ -2747,7 +2342,7 @@
<document>
<properties>
<title>Developer's Guide</title>
- <author email="[EMAIL PROTECTED]">Velocity Documentation Team</author>
+ <author email="[EMAIL PROTECTED]">Velocity Doc Team</author>
</properties>
</document>
]]></source>
@@ -2764,7 +2359,8 @@
try
{
- builder = new SAXBuilder( "org.apache.xerces.parsers.SAXParser" );
+ builder = new SAXBuilder(
+ "org.apache.xerces.parsers.SAXParser" );
root = builder.build("test.xml");
}
catch( Exception ee)
@@ -2820,7 +2416,7 @@
<source><![CDATA[
## first, define the Velocimacro somewhere
-#macro( xenc $sometext )$tools.escapeEntities($sometext)#end
+#macro(xenc $sometext)$tools.escapeEntities($sometext)#end
## and use it as
@@ -2838,7 +2434,9 @@
public String get(String key)
{
Object obj = context.get(key)
- return (obj != null) ? Escape.getText( obj.toString() ) : "";
+ return (obj != null)
+ ? Escape.getText( obj.toString() )
+ : "";
}
]]></source>
@@ -2873,117 +2471,11 @@
<p>
The previous suggestions for dealing with XML entities came from
-Christoph Reck, an active participant in the Velocity community. We are
-very grateful for his [unknowing] contribution to this document, and
-hope his ideas weren't mangled too badly :)
+Christoph Reck, an active participant in the Velocity community.
</p>
</section>
-<section name="FAQ (Frequently Asked Questions)">
-
-<p>
-In no apparent order, here are questions and answers that repeatedly arise
-by developers using Velocity. As we get more, we will move this out to
-a separate document.
-</p>
-
-<a name="FAQ1"><strong>Why Can't I Access Class Members and Constants from
VTL?</strong></a>
-
- <p>
- The short answer is because we don't introspect for fields. We don't do that
- because we wish to promote the idea that you hide your raw data in your
- data objects. There are two solutions to this issue. The first is
- that you should be writing accessors for data elements you wish to be
- publicly exposed. That of course won't work for instances where you don't
- have the source, or simply are too lazy. There is a class for the latter
- group, <code>org.apache.velocity.app.FieldMethodizer</code> which introspects
- your class, and exposes the public static fields in a way that allows easy
- access from a template. Suppose you have a class :
- </p>
-
- <source><![CDATA[
- public class Foo
- {
- public static String PATH_ROOT = "/foo/bar";
-
- ....
- }
- ]]></source>
-
- <p>
- Then, in your code, you would put a <code>Foo</code> into the context like
this
- </p>
-
- <source><![CDATA[
- context.put("myfoo", new FieldMethodizer( new Foo() ) );
- ]]></source>
-
- <p>
- Then to access this field in your template, you would simply access in
- a manner similar to Java :
- </p>
-
- <source><![CDATA[
- $myfoo.PATH_ROOT
- ]]></source>
-
- <p>
- If you have a crushing need to access public non-static members (or even
private
- if you are so driven), then you would have to exend / modify the
- <code>FieldMethodizer</code> yourself. (And we still recommend you
provide accessors....)
- </p>
-
- <a name="FAQ2"><strong>Where does Velocity look for Templates?</strong></a>
-
- <p>
- By default, without any configuration on your part, Velocity will look
- for templates in files, and look for them in the current directory
- (or relative to the current directory, if you prepend a path to your
- template, like 'foo/bar.vm').
- </p>
-
- <p>
- Velocity does this to make it as easy as possible to use out of the box.
- It has been argued that Velocity should do it from the 'root' directory,
but
- it's never clear what that is on filesystems where there are multiple
roots
- (like - "C:\", "D:\", etc).
- </p>
-
- <p>
- For more information, see the section on
- <a href="developer-guide.html#Configuring Resource Loaders">
- resource loaders</a> as well as the section on
- <a href="developer-guide.html#Velocity Configuration Keys and Values">
- configuration keys, values and defaults</a>.
- </p>
-
-
- <a name="FAQ3"><strong>How to I tell Velocity to use my custom
directive?</strong></a>
-
- <p>
- You can extend the functionality of Velocity by writing your own
- custom directives. For example, see the <code>LocalDirective</code>
- in <code>contrib/temporary/LocalDirective</code>. To get Velocity
- to load your directive, all you need to do is include the
- following property in your configuration of the Velocity engine :
- </p>
-
- <source>
- <![CDATA[
- userdirective = LocalDirective
- ]]>
- <source>
-
- <p>
- where you would of course replace <i>LocalDirective</i> above with your
- class name. Then, ensure that your class is in the classpath, and
- all should be well.
- </p>
- </source>
- </source>
-</section>
-
<section name="Summary">
<p>
@@ -2995,144 +2487,6 @@
<p>
Please submit all detailed, thoughtful and constructive feedback through our
<a href="http://jakarta.apache.org/getinvolved/mail.html";>mail lists</a>.
-</p>
-</section>
-
-<section name="Appendix 1 : Deploying the Example Servlet">
-
-<p>
-A continuing source of frustration for beginning servlet users is getting
-all the pieces into place and working. Using a servlet engine like Tomcat or
Resin
-is far from obvious for the first time user (and even for more experienced
users...).
-The following are the basic instructions, to the best of our knowledge, for
getting
-the SampleServlet example working. Note that the sample template
<code>sample.vm</code>
-and the servlet code itself, <code>SampleServlet.java</code> are
- found in the <code>examples/servlet_example</code> directory. Although some
servlet
-engines (Resin, for example) will compile the servlet for you, it would be
best if
-you compiled the examples first. To do this, see the section on building
Velocity, and
-use the <code>examples</code> target.
-</p>
-
-<p>
-<a name="TomcatExample"><strong>Jakarta Tomcat</strong></a>
-</p>
-
-<p>
-Setting up under <a href="http://jakarta.apache.org/tomcat/";>Jakarta
Tomcat</a> is fairly
-straightforward. The 'webapp' directory is where Tomcat automatically
-looks for it's 'web applications', so
-this is where we will set things up.
-</p>
-
-<ol>
-<li> First, make a new 'webapp' by creating a directory called
<i>velexample</i>
- in Tomcat's webapps directory, and make
- a new directory structure as follows :
- <blockquote>
- velexample<br/>
- velexample/WEB-INF<br/>
- velexample/WEB-INF/lib<br/>
- velexample/WEB-INF/classes<br/>
- </blockquote>
-</li>
-<li>
- Put the Velocity jar into the velexample/WEB-INF/lib directory. Note that
with v1.2
- and newer, you either have to either use the jar from the distribution (or
that you
- build yourself) that contains all the dependencies ( ex.
velocity-dep-1.2.jar) or
- you must add the dependency jars yourself to the WEB-INF/lib directory.
Please see
- the section "Getting Started" and "Dependencies", above.
-</li>
-<li>
- Put the SampleServlet.class into the velexample/WEB-INF/classes directory
-</li>
-<li>
- Put the sample.vm template into the velexample directory. The SampleServlet
is
- written to use the root of the webapp as the source of the templates, so
- no configuration is needed.
-</li>
-<li>
- At this point, you should be able to start (or restart) Tomcat and access the
servlet.
-</li>
-<li>
-To access the servlet, point your web browser at :
-
-<blockquote>
-http://localhost:8080/velexample/servlet/SampleServlet
-</blockquote>
-
-or if that doesn't work :
-
-<blockquote>
- http://<your computer's ip
address>:8080/velexample/servlet/SampleServlet
-</blockquote>
-</li>
-<li>
- You should see the sample output.
-</li>
-</ol>
-
-<p>
-<a name="ResinExample"><strong>Caucho Technology's Resin</strong></a>
-</p>
-
-<p>
-Setting up the example servlet under <a href="http://www.caucho.com";>Caucho
Technology's Resin</a>
-servlet engine is also very simple. The following instructions were tested
with the version 1.2.5
-release. The following assume that you have unzip-ed or untar-ed the
distribution, know how to start
-the servlet engine (something like bin/httpd.sh under unix...), and know where
the doc directory is
-(in the root of the distribution).
-</p>
-
-<ol>
-<li>
-Copy the SampleServlet.class file into the doc/WEB-INF/classes directory.
-</li>
-<li>
-Copy the sample.vm template file into the doc/ directory
-</li>
-<li>
-Copy the Velocity jar (and any required dependencies - see note above in
-Tomcat setup section) into the doc/WEB-INF/lib directory.
-</li>
-<li>
-Start resin.
-</li>
-<li>
-To access the servlet, point your web browser at :
-
-<blockquote>
-http://localhost:8080/servlet/SampleServlet
-</blockquote>
-
-or if that doesn't work :
-
-<blockquote>
- http://<your computer's ip address>:8080/servlet/SampleServlet
-</blockquote>
-
-and you should see the output.
-</li>
-</ol>
-
-<p>
-Note that this appeared to be a simpler configuration - with the Tomcat
example,
-you set up a complete, new, separate webapp, whereas the Resin instructions
-don't, although both should provide a sufficient setup to let you play with
-Velocity.
-</p>
-
-<p>Note that while we wish we could, we can't answer questions about the
servlet
-engines. Please use the resources provided by the servlet engine provider.
-</p>
-
-<p>
-<a name="WebLogic"><strong>BEA WebLogic</strong></a>
-</p>
-
-<p>
-Paw Dybdahl <[EMAIL PROTECTED]> contributed <a
href="velocity_and_weblogic.html">this</a>
-description of using Velocity with WebLogic, as well as some good general
suggestions and
-examples for working with servlets.
</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
