Google Git
Sign in
apache / velocity-site / 128e0a5aa64390606d7026a3ba3f3c3f63c4faee / . / cms / trunk / content / engine / 1.4 / veltag.html
blob: 0742b948c45b8f39622293ab8587be1549e25f19 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Content Stylesheet for Site -->
<!-- start the processing -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author" value="Geir Magnusson Jr.">
<meta name="email" value="geirm@apache.org">
<title>Velocity - The Velocity JSP Tag Library</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td align="left">
<a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a>
</td>
<td align="right">
<a href="http://jakarta.apache.org/velocity/"><img src="./images/logo.gif" alt="Velocity" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td width="20%" valign="top" nowrap="true">
<!-- ============================================================ -->
<p><strong>About</strong></p>
<ul>
<li> <a href="./index.html">Overview</a>
</li>
<li> <a href="./getting-started.html">Getting Started</a>
</li>
<li> <a href="http://jakarta.apache.org/builds/jakarta-velocity/">Download</a>
</li>
<li> <a href="./install.html">Install</a>
</li>
<li> <a href="./design.html">Design</a>
</li>
<li> <a href="./contributors.html">Contributors</a>
</li>
<li> <a href="./changes.html">ChangeLog</a>
</li>
<li> <a href="./code-standards.html">Coding Standards</a>
</li>
<li> <a href="./license.html">License</a>
</li>
<li> <a href="./todo.html">TODO</a>
</li>
<li> <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Velocity">Report Issues</a>
</li>
</ul>
<p><strong>Community</strong></p>
<ul>
<li> <a href="./powered.html">Powered By Velocity</a>
</li>
<li> <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a>
</li>
<li> <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
</li>
<li> <a href="http://jakarta.apache.org/site/cvsindex.html">CVS Repositories</a>
</li>
</ul>
<p><strong>Docs</strong></p>
<ul>
<li> <a href="./user-guide.html">User's Guide (English)</a>
</li>
<li> <a href="./user-guide_fi.html">User's Guide (Finnish)</a>
</li>
<li> <a href="./user-guide_fr.html">User's Guide (French)</a>
</li>
<li> <a href="./user-guide_es.html">User's Guide (Spanish)</a>
</li>
<li> <a href="./developer-guide.html">Developer's Guide</a>
</li>
<li> <a href="./vtl-reference-guide.html">VTL Reference Guide</a>
</li>
<li> <a href="./specification.html">Specification</a>
</li>
<li> <a href="./api/index.html">Javadoc</a>
</li>
</ul>
<p><strong>Tools</strong></p>
<ul>
<li> <a href="./tools/index.html">Velocity Tools</a>
</li>
<li> <a href="./anakia.html">Anakia : XML->doc tool</a>
</li>
<li> <a href="./texen.html">Texen : text generation</a>
</li>
<li> <a href="./dvsl/index.html">DVSL : XML xformation</a>
</li>
<li> <a href="./veltag.html">Veltag : JSP taglib</a>
</li>
<li> <a href="./migration.html">Migration to Velocity</a>
</li>
<li> <a href="./devtools.html">Editors and IDEs</a>
</li>
</ul>
<p><strong>Comparisons</strong></p>
<ul>
<li> <a href="./ymtd/ymtd.html">YMTD</a>
</li>
<li> <a href="./differences.html">VM/WM Differences</a>
</li>
<li> <a href="./casestudy1.html">JSP vs. Velocity</a>
</li>
<li> <a href="./casestudy2.html">XMLC vs. Velocity</a>
</li>
</ul>
<p><strong>Site Translations</strong></p>
<ul>
<li> <a href="http://jakarta.apache.org/velocity/">English</a>
</li>
<li> <a href="http://www.ingrid.org/jajakarta/velocity/velocity-1.2-rc2/docs-ja/index.html">Japanese</a>
</li>
</ul>
</td>
<td width="80%" align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Contents"><strong>Contents</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<ol>
<li>
<a href="#So You Have To Use JSP...">So You Have To Use JSP...</a>
<ul>
<li>
<a href="#What Are The Advantages">What Are The Advantages?</a>
</li>
</ul>
</li>
<li>
<a href="#Using The Velocity Taglib">Using The Velocity Taglib</a>
<ul>
<li>
<a href="#Automatic Scope Access">Automatic Scope Access</a>
</li>
<li>
<a href="#Strict Scope Access">Strict Scope Access</a>
</li>
</ul>
</li>
<li>
<a href="#Building The Velocity Taglib">Building The Velocity Taglib</a>
<ul>
<li>
<a href="#JJAR build">Build Using JJAR</a>
</li>
<li>
<a href="#nonJJAR build">Non-JJAR Traditional Build</a>
</li>
</ul>
</li>
<li>
<a href="#Configuration">Configuration</a>
</li>
</ol>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="So You Have To Use JSP..."><strong>So You Have To Use JSP...</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Sometimes it appears you don't have a choice - technology decisions are
made based on all sorts of factors, ranging from network externalities
("They're using it - I should too...") to legacy considerations
("They used it - I have to...").
</p>
<p>
In the event where the usage of JSP is mandatory, we offer a JSP tag library that lets
you take advantage of the simple control directives and powerful binding to the
Java object model offered by Velocity. Using Velocity in your JSPs is as
simple as :
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
&lt;%@ taglib uri=&quot;/WEB-INF/veltag.tld&quot; prefix=&quot;vel&quot; %&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt; Velocity! &lt;/title&gt;
&lt;/head&gt;
&lt;jsp:useBean id=&quot;mybean&quot; class=&quot;GeirBean&quot; /&gt;
&lt;body&gt;
&lt;vel:velocity strictaccess=&quot;true&quot;&gt;
#set($mybean = $scopetool.getPageScope(&quot;mybean&quot;))
#if(true)
this is true!
#end
&lt;br&gt;
$mybean.string
&lt;br&gt;
#foreach($item in $mybean.array)
$item &lt;br&gt;
#end
&lt;/vel:velocity&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
Not hard at all, is it?
</p>
<a name="What Are The Advantages"><strong>What Are The Advantages?</strong></a>
<p>
The first question asked when confronted with this subject is something
along the lines of "What advantage does this have over 'pure' Velocity?".
Generally, there are few reasons why one would take a Velocity-only
system, and convert it to a JSP system with Velocity embedded in the
JSP pages. The only reason that you might want to do this is to use
an existing JSP taglib that you want to use that you don't have the
source code for, or don't wish to dig out the core functional classes
of a taglib you do have the source for. Otherwise, you could just drop
those core classes in the Context, and access them directly from within
the Velocity template.
</p>
<p>
The advantages, then, are found in a JSP-centric environment, where an
existing application is already written in JSP and you wish to add or
maintain functionality. Some things that Velocity provides :
</p>
<ul>
<li>
Simple access to Java objects, without any need to create a taglib
shell. If it has public methods on a public interface, you can
drop it right into a scope and access directly (or use a tool to
create an instances of the class for you.)
</li>
<li>
Simple access to complicated Java objects. It's not clear how to
access an arbitrary call chain such as $foo.bar( $thing ).getIterator().hasNext()
in JSP.
</li>
<li>
Although this is a matter of personal taste, some people prefer the
control directives of Velocity ( #if(), #else(), #elseif(), #foreach() )
to the various taglibs that offer the same functionality.
<i>De gustibus non est disputandum!</i>.
</li>
<li>
An easy bridge between complicated Java objects and JSP - for example
if you wished to dynamically choose/create an object at runtime, and
then poke into a scope for access in other parts of the JSP, you could
do that.
<pre>
&lt;vel:velocity strictaccess="true"&gt;
#set($reqbean = $scopetool.getRequestScope("beaninrequest"))
#set($newthing = $reqbean.getThing().makeBlue("azure"))
$request.getSession().setAttribute("bluething", $newthing)
&lt;/vel:velocity&gt;
</pre>
Or something like that :)
</li>
<li>
If nothing else, there are always the Velocimacros.
</li>
</ul>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Using The Velocity Taglib"><strong>Using The Velocity Taglib</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
The biggest challenge in bringing together Velocity and JSP is the
'impedance matching' related to scope and bean access. 'Scope',
the fundamental storage mechanism in JSP, is a
concept that comes from the underlying servlet API, where data objects
are stored for later retrieval within the page, request, session or
application. Velocity organizes data in a non-hierachical mechanism
called the 'context', the expectation being that a controller servlet
or other non-view code will manage and organize the data accessable
to the template.
</p>
<p>
So to make data access in JSPs easy using the Velocity taglib, two
separate approaches are offered. These two approaches, automatic
access and strict access, allow two distinct ways of managing and
accessing data. These two ways can also be used together.
</p>
<a name="Automatic Scope Access"><strong>Automatic Scope Access</strong></a>
<p>
The first way, automatic access, is the most convenient. When an
object is referenced (via a VTL 'reference'), the scopes are searched
to find an object with the same id. The scopes are searched in the
order of :
</p>
<ol>
<li> page scope </li>
<li> request scope </li>
<li> session scope </li>
<li> application scope </li>
</ol>
<p>
Automatic scope access is enabled by default. To use
automatic scope access, just access the bean by name. For example :
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
&lt;!-- place a bean in page scope --&gt;
&lt;jsp:useBean id=&quot;mybean&quot; class=&quot;GeirBean&quot; /&gt;
&lt;vel:velocity&gt;
&lt;!-- just access by id - the context --&gt;
&lt;!-- will find it automatically --&gt;
#foreach($item in $mybean.array)
$item &lt;br&gt;
#end
&lt;/vel:velocity&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
While automatic scope access is the easier of the two methods,
integrating with existing applications might require using the
other access mode, strict scope access, or a combination of the
two.
</p>
<a name="Strict Scope Access"><strong>Strict Scope Access</strong></a>
<p>
The alternative (or addition to) Automatic Scope Access is something called
<i>Strict Scope Access</i>. Strict Scope Acccess means that the Velocity
Context won't search the scopes for you - you must retrieve objects directly
using ScopeTool that is provided for your use in the template. This is a
closer model to that of regular JSP, where the designer must be aware of
the scopes that objects are stored in.
</p>
<p>
For example, the following snippet of JSP shows how the scopetool is used to
access an object in the request scope, and add it to the Velocity context.
Note how the <code>strictaccess</code> property is set to true in the
<code>&lt;vel:velocity strictaccess="true"&gt;</code> tag. This tells
the Veltag taglib to not do any automatic scope searching. Note that you can
mix the two modes, leaving off (or setting to false) <code>strictaccess</code>
and also using the scopetool to eliminate any question about the source
of an object.
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
&lt;jsp:useBean id=&quot;beaninrequest&quot; class=&quot;GeirBean&quot; scope=&quot;request&quot; /&gt;
&lt;vel:velocity strictaccess=&quot;true&quot;&gt;
#set($reqbean = $scopetool.getRequestScope(&quot;beaninrequest&quot;))
$reqbean.string
&lt;br&gt;
#foreach($item in $reqbean.array)
$item &lt;br&gt;
#end
&lt;/vel:velocity&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<p>
Again, pretty straightforward.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Building The Velocity Taglib"><strong>Building The Velocity Taglib</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
To use the Velocity taglib, you need to build it, as it is not
yet included in the main Velocity jar. In the Jakarta tradition,
we made it very easy to build. The code for the project is
located in the contrib section of the distribution under
<code>/contrib/temporary/veltag</code>. It is under the
temporary directory as it is hoped this package will
be accepted by the
<a href="http://jakarta.apache.org/taglibs/">Jakarta Taglibs</a>
project.
</p>
<a name="JJAR build"><strong>The Easy, JJAR Way</strong></a>
<p>
The Veltag taglib can be built using a new, <b>experimental</b>
jar management tool called <em>JJAR</em>
(Jakarta Jar Archive &amp; Repository) which makes finding and retrieving the
dependencies to build the taglib simple.
</p>
<p>
<i>Please note that JJAR is
currently a work in progress - while every effort will be made to ensure
that the JJAR-based build works, it may not always be so. In that case,
do it the regular way, listed below.</i>
</p>
<p>
To build with JJAR :
</p>
<ol>
<li>
<a href="http://jakarta.apache.org/ant/">Ant</a>, the fabulous
Jakarta build tool, must be installed.
</li>
<li>
Get the Velocity distribution from CVS or a nightly snapshot.
</li>
<li>
Change directory to the <code>/contrib/temporary/veltag</code>
directory in the Velocity distribution.
</li>
<li>
Type :
<pre>
$ ant getjars
</pre>
This will fetch JJAR and then use JJAR to fetch the dependencies du
jour for Veltag.
</li>
<li>
Type :
<pre>
$ant jar
</pre>
which will build the veltag-XX.jar (XX = current version).
</li>
</ol>
<p>
That's it. Pretty easy.
</p>
<a name="nonJJAR build"><strong>The JJAR-Is-A-Work-In-Progress Way</strong></a>
<p>
In the event the JJAR-based build is broken, or you just enjoy
schlepping around finding jars, do the following to build Veltag.
</p>
<p>
To build, you need the following :
</p>
<ul>
<li>
<a href="http://jakarta.apache.org/ant/">Ant</a>, the fabulous
Jakarta build tool, must be installed.
</li>
<li>
You will need a servlet API jar. We recommend you get it from
<a href="http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.3/bin/">here</a>
for servlet 2.2 and
<a href="http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly/">here</a>
for the unreleased servlet 2.3 API. Note - if you are a JSP user, you will have
one included with your servlet engine.
</li>
<li>
A velocity.jar. This can be found, of course,
<a href="http://jakarta.apache.org/velocity/">here</a>.
</li>
<li>
The build script expects to find the servlet and velocity jars in the
<code>/contrib/temporary/veltag/lib/</code>
directory. Modification
of the build script is easy if they are in another location. Look for
'servlet.home' and 'velocity.home' in the
<code>/contrib/temporary/veltag/build.xml</code> file.
</li>
<li>
Once the above is complete, cd into
<code>/contrib/temporary/veltag</code> in the Velocity
distribution and type 'ant'. The jar should build
for you.
</li>
</ul>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Configuration"><strong>Configuration</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Using the taglib is very straightforward. The following assumes
that you have setup a servlet container with JSP support, such as
<a href="http://jakarta.apache.org/tomcat/">Tomcat</a>, and know
enough to write and view a simple JSP page. Also, all directory
references are relative to the root of the veltag project, not
the Velocity distribution.
</p>
<p>
To test the Velocity Taglib :
</p>
<blockquote>
You need to copy the veltag-XX.jar to the
<code>WEB-INF/lib</code> directory of your webapp. (Where XX
is the current version number.
</blockquote>
<blockquote>
Take the example taglib descriptor,
<code> /examples/veltag.tld</code> and place in WEB-INF of your
webapp.
</blockquote>
<blockquote>
Finally, add
<pre>
&lt;taglib&gt;
&lt;taglib-uri&gt;http://jakarta.apache.org/taglibs/veltag-1.0&lt;/taglib-uri&gt;
&lt;taglib-location&gt;/WEB-INF/veltag.tld&lt;/taglib-location&gt;
&lt;/taglib&gt;
</pre>
to your web.xml file, within the &lt;webapp&gt; section.
</blockquote>
<p>
If you wish to use the included example JSP, you will also need to compile
<code>examples/SimpleBean.java</code> and place the resulting
<code>SimpleBean.class</code> into the <code>WEB-INF/classes</code>
directory in your webapp.
</p>
<p>
After that, try the example JSP found in <code>examples/</code>. Drop it
into the root of your webapp and view it with your browser. Enjoy!
</p>
<p>
Please direct all comments, questions, fixes and contributions to
<a href="mailto:geirm@apache.org?SUBJECT=Veltag">Geir Magnusson Jr.</a> or the
Velocity user list. To subscribe to the Velocity lists, read
<a href="http://jakarta.apache.org/site/mail.html">this</a> and follow the
instructions at the end.
</p>
<p>
Please note that this code is not an official part of the Velocity
distribution.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
</td>
</tr>
<!-- FOOTER -->
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font color="#525D76" size="-1"><em>
Copyright &#169; 1999-2004, The Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->