You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ma...@apache.org on 2004/01/30 13:08:52 UTC
cvs commit: jakarta-velocity-tools/xdocs/struts userguide.xml
marino 2004/01/30 04:08:52
Modified: xdocs/struts userguide.xml
Log:
added ActionMessagesTool, TilesTool, and ValidatorTool.
Revision Changes Path
1.3 +168 -141 jakarta-velocity-tools/xdocs/struts/userguide.xml
Index: userguide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/xdocs/struts/userguide.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- userguide.xml 5 May 2003 02:14:55 -0000 1.2
+++ userguide.xml 30 Jan 2004 12:08:52 -0000 1.3
@@ -8,28 +8,28 @@
<projectfile>xdocs/struts/menu.xml</projectfile>
</properties>
- <body>
+ <body>
<section name="Velocity for Struts User Guide">
- <p>This guide explains how to setup and configure a VelocityViewServlet
- which can render the views of a Struts-based web application. The servlet
- will create a VelocityEngine to render *.vm (velocity template) files using
+ <p>This guide explains how to setup and configure a VelocityViewServlet
+ which can render the views of a Struts-based web application. The servlet
+ will create a VelocityEngine to render *.vm (velocity template) files using
contextual information provided by a Struts Controller action.</p>
- <p>A set of built-in tools have been created which provide the same
- functions as the Struts JSP Tag libraries for Forms, Links, Messages,
- and entry Errors. At this time, the Validator taglib is not supported,
+ <p>A set of built-in tools have been created which provide the same
+ functions as the Struts JSP Tag libraries for Forms, Links, Messages,
+ and entry Errors. At this time, the Validator taglib is not supported,
but may be in the future.</p>
- <p>The distribution contains examples which demonstrate the use of the
- built-in Struts tools. The examples are packaged into a web archive file
+ <p>The distribution contains examples which demonstrate the use of the
+ built-in Struts tools. The examples are packaged into a web archive file
(velstruts.war). </p>
- <p>
- This document is <strong>not</strong> a general introduction to the Velocity
- template language and its syntax. If you are new to Velocity, please consult
- <a href="http://jakarta.apache.org/velocity/getting-started.html">Getting
+ <p>
+ This document is <strong>not</strong> a general introduction to the Velocity
+ template language and its syntax. If you are new to Velocity, please consult
+ <a href="http://jakarta.apache.org/velocity/getting-started.html">Getting
Started with Velocity</a>.
</p>
@@ -50,100 +50,100 @@
</ol>
</section>
<section name="Background">
- <p>The documentation will explain the steps necessary to
- integrate <a href="http://jakarta.apache.org/velocity/">Velocity</a>
- with <a href="http://jakarta.apache.org/struts/">Struts</a> applications.
- It is expected that the reader already has a basic understanding of those
+ <p>The documentation will explain the steps necessary to
+ integrate <a href="http://jakarta.apache.org/velocity/">Velocity</a>
+ with <a href="http://jakarta.apache.org/struts/">Struts</a> applications.
+ It is expected that the reader already has a basic understanding of those
projects.</p>
-
- <p>To start working with Velocity and Struts we recommend reading the
- user guide, installing and browsing the example applications and reference
- documentation, then installing the VelocityStruts view layer into your own
+
+ <p>To start working with Velocity and Struts we recommend reading the
+ user guide, installing and browsing the example applications and reference
+ documentation, then installing the VelocityStruts view layer into your own
application.</p>
- <p>If this documentation does not answer all your questions, please post
- questions to the
+ <p>If this documentation does not answer all your questions, please post
+ questions to the
<a href="http://jakarta.apache.org/site/mail.html">Velocity-User mailing list</a>
- and we'll be happy to help! (And we'll update this doc!)</p>
+ and we'll be happy to help! (And we'll update this doc!)</p>
</section>
<section name="Model 2 Architecture">
- <p>In the JSP world, the terms <i>Model 1</i> architectures and
- <i>Model 2</i> architectures were coined to refer to particular ways of
- designing and building web applications. It is important that you understand
- the fundamental difference between these two architectural approaches. JSP
- can be used in applications designed after Model 1 architectures as well as
- Model 2 architectures. Velocity cannot. It has been designed very consciouly
+ <p>In the JSP world, the terms <i>Model 1</i> architectures and
+ <i>Model 2</i> architectures were coined to refer to particular ways of
+ designing and building web applications. It is important that you understand
+ the fundamental difference between these two architectural approaches. JSP
+ can be used in applications designed after Model 1 architectures as well as
+ Model 2 architectures. Velocity cannot. It has been designed very consciouly
as a view technology for web application architectures based on Model 2.</p>
- <p><strong>Model 1 Architectures</strong></p>
- <p>In a Model 1 architecture, the JSP page alone is responsible for
- processing the incoming request and replying back to the client. Using
- MVC speak, the controller and the view are implemented within the same
- JSP page. Model 1 architecture are suitable only for very simple application
- scenarios. In medium size to large projects, the lack of a separation between
- business logic and view oftentimes leads to difficulties in separating the
- web designer's works from the server developer's work and causes project
+ <p><strong>Model 1 Architectures</strong></p>
+ <p>In a Model 1 architecture, the JSP page alone is responsible for
+ processing the incoming request and replying back to the client. Using
+ MVC speak, the controller and the view are implemented within the same
+ JSP page. Model 1 architecture are suitable only for very simple application
+ scenarios. In medium size to large projects, the lack of a separation between
+ business logic and view oftentimes leads to difficulties in separating the
+ web designer's works from the server developer's work and causes project
management headaches.</p>
- <p><strong>Model 2 Architectures</strong></p>
- <p>In a Model 2 architecture, the control component, including business logic,
- data access and request handling, are strictly separated from the view component.
- The view does not contain any processing logic. It is simply responsible for
- displaying the data that resulted from processing the request. This may be a
- static page or more often a dynamic page. Such an approach typically facilitates
- are clear delineation of the roles and responsibilities of the developers and
- the web designers. The more complex an application, the greater the benefits of
+ <p><strong>Model 2 Architectures</strong></p>
+ <p>In a Model 2 architecture, the control component, including business logic,
+ data access and request handling, are strictly separated from the view component.
+ The view does not contain any processing logic. It is simply responsible for
+ displaying the data that resulted from processing the request. This may be a
+ static page or more often a dynamic page. Such an approach typically facilitates
+ are clear delineation of the roles and responsibilities of the developers and
+ the web designers. The more complex an application, the greater the benefits of
using a Model 2 architecture will be.</p>
- <p>The paper
+ <p>The paper
<a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">Understanding JavaServer Pages Model 2 Architecture</a>
provides a more in-depth discussion of Model 1 and Model 2 architectures.</p>
- <p><strong>What does this mean?</strong></p>
- <p>The Struts framework can support both architectures, but all the
- facilities it provides are really aimed at making the construction of
- Model 2 applications easy. Velocity on the other hand cannot be used
- to build Model 1 architectures. It lacks the libraries to support such
- a design. I am emphasizing this here because I want to make sure that
- you have all the relevant facts before you decide on Velocity for your
- projects. This is especially important for people considering to port
- existing application built on the Model 1 approach or a mixed Model 1
- / Model 2 approach. The good news is, that today for any serious application
- Model 2 is state of the art and Velocity will support you very well on
- that route.</p>
+ <p><strong>What does this mean?</strong></p>
+ <p>The Struts framework can support both architectures, but all the
+ facilities it provides are really aimed at making the construction of
+ Model 2 applications easy. Velocity on the other hand cannot be used
+ to build Model 1 architectures. It lacks the libraries to support such
+ a design. I am emphasizing this here because I want to make sure that
+ you have all the relevant facts before you decide on Velocity for your
+ projects. This is especially important for people considering to port
+ existing application built on the Model 1 approach or a mixed Model 1
+ / Model 2 approach. The good news is, that today for any serious application
+ Model 2 is state of the art and Velocity will support you very well on
+ that route.</p>
<br clear="all"/>
</section>
-
+
<section name="Installation">
<p>This section explains the basic setup to configure the VelocityViewServlet
to render the web application views in Struts applications.</p>
-
+
<p>Setup is almost identical to the standard
<a href="../view/index.html#Installation">VelocityViewServlet installation</a>,
- please review that for more details. The extended VelocityLayoutServlet, or any
- custom extension, can also be used with Struts. (That particular servlet adds
+ please review that for more details. The extended VelocityLayoutServlet, or any
+ custom extension, can also be used with Struts. (That particular servlet adds
the ability to reuse shared html layout across multiple pages.)</p>
-
+
<p>Steps by step:</p>
<ol>
<li><strong>velocity-tools-x.x.jar</strong> which contains the VelocityStruts
and VelocityView classes must be added to the WEB-INF/lib directory.</li>
- <li>VelocityViewServlet needs to be installed into the servlet container
+ <li>VelocityViewServlet needs to be installed into the servlet container
(web.xml) so it can handle all request for *.vm files.</li>
<li>velocity.properties configuration file must be added </li>
- <li>toolbox.xml file must be added, and mappings must be setup for the
- standard tools which expose the Struts objects to the template. (sample
+ <li>toolbox.xml file must be added, and mappings must be setup for the
+ standard tools which expose the Struts objects to the template. (sample
toolbox.xml file below)</li>
</ol>
<p>And that's all there is to it!</p>
- <p>At this point, it should be possible to change a Struts ActionMapping
- to 'forward' to a *.vm file placed in the webapp root directory and have
+ <p>At this point, it should be possible to change a Struts ActionMapping
+ to 'forward' to a *.vm file placed in the webapp root directory and have
it be displayed!</p>
-
+
<p><b>toolbox.xml</b></p>
<sourcecode>
<?xml version="1.0"?>
@@ -169,6 +169,16 @@
<scope>request</scope>
<class>org.apache.velocity.tools.struts.FormTool</class>
</tool>
+ <tool>
+ <key>tiles</key>
+ <scope>request</scope>
+ <class>org.apache.velocity.tools.struts.TilesTool</class>
+ </tool>
+ <tool>
+ <key>validator</key>
+ <scope>request</scope>
+ <class>org.apache.velocity.tools.struts.ValidatorTool</class>
+ </tool>
</toolbox>
</sourcecode>
@@ -176,27 +186,27 @@
<section name="Rendering the View">
- <p>This section introduces you to the key concepts of rendering
+ <p>This section introduces you to the key concepts of rendering
the view with Velocity in a Struts application.</p>
<subsection name="Velocity Template Language">
- <p>Velocity is a template engine implemented in Java. Velocity
- templates typically are HTML pages with embedded scripts (although
- Velocity has been used for many other application scenarios). Scripts
- are written in the Velocity Template Language (VTL). Following is a
+ <p>Velocity is a template engine implemented in Java. Velocity
+ templates typically are HTML pages with embedded scripts (although
+ Velocity has been used for many other application scenarios). Scripts
+ are written in the Velocity Template Language (VTL). Following is a
simple example of a HTML view with embedded VTL statements:</p>
-
+
<sourcecode>
<HTML>
<BODY>
<h2>Order Confirmation</h2>
-
- <h3>Delivery Adress:</h3><br>
+
+ <h3>Delivery Adress:</h3><br>
Name: $customer.name<br>
Street: $customer.street<br>
City: $customer.zip $customer.city
-
+
<h3>Ordered Items</h3><br>
<table>
#foreach( $item in $order.items )
@@ -207,7 +217,7 @@
#end
</table>
</body>
-</html>
+</html>
</sourcecode>
<p>When processed this will produce output similar to the following.</p>
@@ -216,12 +226,12 @@
<HTML>
<BODY>
<h2>Order Confirmation</h2>
-
- <h3>Delivery Adress:</h3><br>
+
+ <h3>Delivery Adress:</h3><br>
Name: Peter Pan<br>
Street: Crain St. 10<br>
City: 60201 Evanston IL
-
+
<h3>Ordered Items</h3><br>
<table>
<tr>
@@ -234,78 +244,78 @@
</tr>
</table>
</body>
-</html>
+</html>
</sourcecode>
- <p>VTL has been designed from the ground up as a simple template
- language for view designers. With less than ten supported directives
- it is easy to learn. In fact, most people are up and productive within
+ <p>VTL has been designed from the ground up as a simple template
+ language for view designers. With less than ten supported directives
+ it is easy to learn. In fact, most people are up and productive within
less than a day.</p>
-
- <p>Velocity does not allow Java scriptlets, which helps enforce a
+
+ <p>Velocity does not allow Java scriptlets, which helps enforce a
strict MVC separation.</p>
-
- <p>Please consult the following two documents for an in-depth coverage
+
+ <p>Please consult the following two documents for an in-depth coverage
of VTL:</p>
-
+
<ul>
<li><a href="http://jakarta.apache.org/velocity/user-guide.html">Velocity User's Guide</a></li>
<li><a href="http://jakarta.apache.org/velocity/vtl-reference-guide.html">VTL Reference Guide</a></li>
</ul>
-
+
<br clear="all"/>
-
+
</subsection>
<subsection name="Exposing Data">
- <p>The main purpose of Velocity in a web application is typically to
- merge HTML templates with dynamic application data to generate
- dynamic views. An essential aspect of Velocity is therefore the
- mechanism that allows the application controller (in MVC speak) to
- expose data to the template.</p>
-
- <p>It is important to understand the relationship between a
- Struts-based application and the Velocity template servlet. Both
+ <p>The main purpose of Velocity in a web application is typically to
+ merge HTML templates with dynamic application data to generate
+ dynamic views. An essential aspect of Velocity is therefore the
+ mechanism that allows the application controller (in MVC speak) to
+ expose data to the template.</p>
+
+ <p>It is important to understand the relationship between a
+ Struts-based application and the Velocity template servlet. Both
are simply Java Servlets which perform a specific task.</p>
<p> Requests to the Struts application are processed, application data
- is manipulated and eventually all data and control is forwarded to a
+ is manipulated and eventually all data and control is forwarded to a
View layer.</p>
- <p>The Velocity servlet in this case is responsible for merging the
+ <p>The Velocity servlet in this case is responsible for merging the
provided application data with a template to produce HTML output.</p>
- <p>We should note that the Velocity servlet is not exclusively tied
- to the Struts application. It can serve requests from web clients
- directly or any other servlet application as well. Technically, the
- Struts application hands over a request to Velocity through the
+ <p>We should note that the Velocity servlet is not exclusively tied
+ to the Struts application. It can serve requests from web clients
+ directly or any other servlet application as well. Technically, the
+ Struts application hands over a request to Velocity through the
<code>forward</code> method of <code>javax.servlet.RequestDispatcher</code>.
</p>
-
- <p>Application data is passed from the Struts servlet to the Velocity
+
+ <p>Application data is passed from the Struts servlet to the Velocity
servlet as attributes of either the servlet request, session or context.</p>
-
- <p>Therefore a developer simply needs to set an attribute to pass data
+
+ <p>Therefore a developer simply needs to set an attribute to pass data
to the View layer and make that data available for the template. For example:
</p>
<p>
<sourcecode>request.setAttribute("Customer", CustomerObj);</sourcecode>
- Whatever public methods are available on the CustomerObj instance will be
- made available to the template designer. Assuming there is a public
- getName() method, they may for example write: $Customer.name or
+ Whatever public methods are available on the CustomerObj instance will be
+ made available to the template designer. Assuming there is a public
+ getName() method, they may for example write: $Customer.name or
$Customer.getName().
</p>
<p>[TODO: Explain chaining of attributes] </p>
-
+
</subsection>
<subsection name="Access to Servlet Resources">
- <p>VelocityStruts automatically populates the context with the following
+ <p>VelocityStruts automatically populates the context with the following
objects of the Servlet API on each template processing request:</p>
-
+
<table>
<tr>
<th>Context Key</th>
@@ -332,13 +342,13 @@
<td>javax.servlet.http.HttpServletResponse</td>
<td>the current servlet response</td>
</tr>
- </table>
+ </table>
<br clear="all"/>
<p>The following examples illustrates how servlet resources are
accessed from within Velocity template. The example renders
- the list of HTTP header fields of the current servlet request.
+ the list of HTTP header fields of the current servlet request.
In the same way, any public method of the above listed objects can
be called from within templates:</p>
@@ -368,23 +378,23 @@
<p>The Struts framework provides resources that
are useful to template designers. These include logical names for
- physical resources, internationalized messages, error handling,
- form handling, etc. The interesting question is now how template
- designers can gain access these framework resources. In the JSP world, a set
+ physical resources, internationalized messages, error handling,
+ form handling, etc. The interesting question is now how template
+ designers can gain access these framework resources. In the JSP world, a set
of custom tag libraries provide template
designers access to the Struts framework resources. In the Velocity
- world, the equivalent of the JSP custom tag libraries are <b>view
- tools</b>. View tools are a very simple concept. They are Java objects
+ world, the equivalent of the JSP custom tag libraries are <b>view
+ tools</b>. View tools are a very simple concept. They are Java objects
with public methods that are put into the Velocity context. Tools are
accessed by key and allows template designers to call on their public methods.</p>
-
- <p>A set of four view tools is included with VelocityStruts
+
+ <p>A set of seven view tools is included with VelocityStruts
that provide template designers access to Struts framework resources.
- These four view tools essentially achieve the integration between
+ These seven view tools essentially achieve the integration between
Struts and Velocity and they can be considered the core of this
project.</p>
-
- <table>
+
+ <table>
<tr>
<th>Context Key</th>
<th>Class</th>
@@ -401,6 +411,11 @@
<td>Provides methods to check for and output Struts error messages.</td>
</tr>
<tr>
+ <td>$actionmsgs</td>
+ <td><a href="ActionMessagesTool.html">ActionMessagesTool</a></td>
+ <td>Provides methods to work with Struts action messages.</td>
+ </tr>
+ <tr>
<td>$link</td>
<td><a href="StrutsLinkTool.html">StrutsLinkTool</a></td>
<td>Provides methods to work with URIs.</td>
@@ -408,26 +423,38 @@
<tr>
<td>$form</td>
<td><a href="FormTool.html">FormTool</a></td>
- <td>Provides miscellaneous methods to work with forms and form
+ <td>Provides miscellaneous methods to work with forms and form
beans in the context of Struts applications.</td>
</tr>
<tr>
- <td colspan="3">Note: The shown keys are the recommended values.
+ <td>$tiles</td>
+ <td><a href="TilesTool.html">TilesTool</a></td>
+ <td>Provides miscellaneous methods to work with Tiles in the
+ context of Struts applications.</td>
+ </tr>
+ <tr>
+ <td>$validator</td>
+ <td><a href="ValidatorTool.html">ValidatorTool</a></td>
+ <td>Provides methods to dynamically generate javascript validation
+ in the context of Struts applications.</td>
+ </tr>
+ <tr>
+ <td colspan="3">Note: The shown keys are the recommended values.
They can be changed in the configuration.</td>
</tr>
- </table>
-
+ </table>
+
<p>The following example illustrates some of the features of the MessageTool
for working with internationalized messages. For the example we assume that
the Struts message resources contain the following two key=value pairs:</p>
-
+
<sourcecode>
title=Struts Example Application
test=This string has 4 replacement parameters: {1}, {2}, {3}, {4}
-</sourcecode>
+</sourcecode>
<p>Then, the following script...</p>
-
+
<sourcecode>
$msg.get("title")
$msg.get("test", ["bear", "dog", "cat"])
@@ -443,10 +470,10 @@
false
en
</sourcecode>
-
- <p>Please see the <a href="StrutsTools.html">Tool Reference Documentation</a>
- for more details about the view tools. Furthermore, the Velocity/Struts
- <a href="index.html#Download">example application</a> comes with several
+
+ <p>Please see the <a href="StrutsTools.html">Tool Reference Documentation</a>
+ for more details about the view tools. Furthermore, the Velocity/Struts
+ <a href="index.html#Download">example application</a> comes with several
working examples that show how these tools are used.</p>
<br clear="all"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: cvs commit: jakarta-velocity-tools/xdocs/struts userguide.xml
Posted by "Marinó A. Jónsson" <ma...@centrum.is>.
All hail the mighty JBuilder :S
... those damn formatting changes are not my doing.
Marinó
> -----Original Message-----
> From: marino@apache.org [mailto:marino@apache.org]
> Sent: 30. janúar 2004 12:09
> To: jakarta-velocity-tools-cvs@apache.org
> Subject: cvs commit: jakarta-velocity-tools/xdocs/struts userguide.xml
>
>
> marino 2004/01/30 04:08:52
>
> Modified: xdocs/struts userguide.xml
> Log:
> added ActionMessagesTool, TilesTool, and ValidatorTool.
>
> Revision Changes Path
> 1.3 +168 -141
> jakarta-velocity-tools/xdocs/struts/userguide.xml
>
> Index: userguide.xml
> ===================================================================
> RCS file:
> /home/cvs/jakarta-velocity-tools/xdocs/struts/userguide.xml,v
> retrieving revision 1.2
> retrieving revision 1.3
> diff -u -r1.2 -r1.3
> --- userguide.xml 5 May 2003 02:14:55 -0000 1.2
> +++ userguide.xml 30 Jan 2004 12:08:52 -0000 1.3
> @@ -8,28 +8,28 @@
> <projectfile>xdocs/struts/menu.xml</projectfile>
> </properties>
>
> - <body>
> + <body>
>
> <section name="Velocity for Struts User Guide">
>
> - <p>This guide explains how to setup and configure
> a VelocityViewServlet
> - which can render the views of a Struts-based web
> application. The servlet
> - will create a VelocityEngine to render *.vm
> (velocity template) files using
> + <p>This guide explains how to setup and configure
> a VelocityViewServlet
> + which can render the views of a Struts-based web
> application. The servlet
> + will create a VelocityEngine to render *.vm
> (velocity template) files using
> contextual information provided by a Struts
> Controller action.</p>
>
> - <p>A set of built-in tools have been created which
> provide the same
> - functions as the Struts JSP Tag libraries for
> Forms, Links, Messages,
> - and entry Errors. At this time, the Validator
> taglib is not supported,
> + <p>A set of built-in tools have been created which
> provide the same
> + functions as the Struts JSP Tag libraries for
> Forms, Links, Messages,
> + and entry Errors. At this time, the Validator
> taglib is not supported,
> but may be in the future.</p>
>
> - <p>The distribution contains examples which
> demonstrate the use of the
> - built-in Struts tools. The examples are packaged
> into a web archive file
> + <p>The distribution contains examples which
> demonstrate the use of the
> + built-in Struts tools. The examples are packaged
> into a web archive file
> (velstruts.war). </p>
>
> - <p>
> - This document is <strong>not</strong> a general
> introduction to the Velocity
> - template language and its syntax. If you are new
> to Velocity, please consult
> - <a
> href="http://jakarta.apache.org/velocity/getting-started.html"
> >Getting
> + <p>
> + This document is <strong>not</strong> a general
> introduction to the Velocity
> + template language and its syntax. If you are new
> to Velocity, please consult
> + <a
> href="http://jakarta.apache.org/velocity/getting-started.html">Getting
> Started with Velocity</a>.
> </p>
>
> @@ -50,100 +50,100 @@
> </ol>
> </section>
> <section name="Background">
> - <p>The documentation will explain the steps necessary to
> - integrate <a
> href="http://jakarta.apache.org/velocity/">Velocity</a>
> - with <a
> href="http://jakarta.apache.org/struts/">Struts</a> applications.
> - It is expected that the reader already has a basic
> understanding of those
> + <p>The documentation will explain the steps necessary to
> + integrate <a
> href="http://jakarta.apache.org/velocity/">Velocity</a>
> + with <a
> href="http://jakarta.apache.org/struts/">Struts</a> applications.
> + It is expected that the reader already has a basic
> understanding of those
> projects.</p>
> -
> - <p>To start working with Velocity and Struts we
> recommend reading the
> - user guide, installing and browsing the example
> applications and reference
> - documentation, then installing the VelocityStruts
> view layer into your own
> +
> + <p>To start working with Velocity and Struts we
> recommend reading the
> + user guide, installing and browsing the example
> applications and reference
> + documentation, then installing the VelocityStruts
> view layer into your own
> application.</p>
>
> - <p>If this documentation does not answer all your
> questions, please post
> - questions to the
> + <p>If this documentation does not answer all your
> questions, please post
> + questions to the
> <a
> href="http://jakarta.apache.org/site/mail.html">Velocity-User
> mailing list</a>
> - and we'll be happy to help! (And we'll update this
> doc!)</p>
> + and we'll be happy to help! (And we'll update this
> doc!)</p>
> </section>
>
> <section name="Model 2 Architecture">
>
> - <p>In the JSP world, the terms <i>Model 1</i>
> architectures and
> - <i>Model 2</i> architectures were coined to refer
> to particular ways of
> - designing and building web applications. It is
> important that you understand
> - the fundamental difference between these two
> architectural approaches. JSP
> - can be used in applications designed after Model
> 1 architectures as well as
> - Model 2 architectures. Velocity cannot. It has
> been designed very consciouly
> + <p>In the JSP world, the terms <i>Model 1</i>
> architectures and
> + <i>Model 2</i> architectures were coined to refer
> to particular ways of
> + designing and building web applications. It is
> important that you understand
> + the fundamental difference between these two
> architectural approaches. JSP
> + can be used in applications designed after Model
> 1 architectures as well as
> + Model 2 architectures. Velocity cannot. It has
> been designed very consciouly
> as a view technology for web application
> architectures based on Model 2.</p>
>
> - <p><strong>Model 1 Architectures</strong></p>
> - <p>In a Model 1 architecture, the JSP page alone
> is responsible for
> - processing the incoming request and replying back
> to the client. Using
> - MVC speak, the controller and the view are
> implemented within the same
> - JSP page. Model 1 architecture are suitable only
> for very simple application
> - scenarios. In medium size to large projects, the
> lack of a separation between
> - business logic and view oftentimes leads to
> difficulties in separating the
> - web designer's works from the server developer's
> work and causes project
> + <p><strong>Model 1 Architectures</strong></p>
> + <p>In a Model 1 architecture, the JSP page alone
> is responsible for
> + processing the incoming request and replying back
> to the client. Using
> + MVC speak, the controller and the view are
> implemented within the same
> + JSP page. Model 1 architecture are suitable only
> for very simple application
> + scenarios. In medium size to large projects, the
> lack of a separation between
> + business logic and view oftentimes leads to
> difficulties in separating the
> + web designer's works from the server developer's
> work and causes project
> management headaches.</p>
>
> - <p><strong>Model 2 Architectures</strong></p>
> - <p>In a Model 2 architecture, the control
> component, including business logic,
> - data access and request handling, are strictly
> separated from the view component.
> - The view does not contain any processing logic.
> It is simply responsible for
> - displaying the data that resulted from processing
> the request. This may be a
> - static page or more often a dynamic page. Such an
> approach typically facilitates
> - are clear delineation of the roles and
> responsibilities of the developers and
> - the web designers. The more complex an
> application, the greater the benefits of
> + <p><strong>Model 2 Architectures</strong></p>
> + <p>In a Model 2 architecture, the control
> component, including business logic,
> + data access and request handling, are strictly
> separated from the view component.
> + The view does not contain any processing logic.
> It is simply responsible for
> + displaying the data that resulted from processing
> the request. This may be a
> + static page or more often a dynamic page. Such an
> approach typically facilitates
> + are clear delineation of the roles and
> responsibilities of the developers and
> + the web designers. The more complex an
> application, the greater the benefits of
> using a Model 2 architecture will be.</p>
>
> - <p>The paper
> + <p>The paper
> <a
> href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-
> jspmvc.html">Understanding JavaServer Pages Model 2 Architecture</a>
> provides a more in-depth discussion of Model 1
> and Model 2 architectures.</p>
>
> - <p><strong>What does this mean?</strong></p>
> - <p>The Struts framework can support both
> architectures, but all the
> - facilities it provides are really aimed at making
> the construction of
> - Model 2 applications easy. Velocity on the other
> hand cannot be used
> - to build Model 1 architectures. It lacks the
> libraries to support such
> - a design. I am emphasizing this here because I
> want to make sure that
> - you have all the relevant facts before you decide
> on Velocity for your
> - projects. This is especially important for people
> considering to port
> - existing application built on the Model 1
> approach or a mixed Model 1
> - / Model 2 approach. The good news is, that today
> for any serious application
> - Model 2 is state of the art and Velocity will
> support you very well on
> - that route.</p>
> + <p><strong>What does this mean?</strong></p>
> + <p>The Struts framework can support both
> architectures, but all the
> + facilities it provides are really aimed at making
> the construction of
> + Model 2 applications easy. Velocity on the other
> hand cannot be used
> + to build Model 1 architectures. It lacks the
> libraries to support such
> + a design. I am emphasizing this here because I
> want to make sure that
> + you have all the relevant facts before you decide
> on Velocity for your
> + projects. This is especially important for people
> considering to port
> + existing application built on the Model 1
> approach or a mixed Model 1
> + / Model 2 approach. The good news is, that today
> for any serious application
> + Model 2 is state of the art and Velocity will
> support you very well on
> + that route.</p>
>
> <br clear="all"/>
> </section>
> -
> +
> <section name="Installation">
>
> <p>This section explains the basic setup to
> configure the VelocityViewServlet
> to render the web application views in Struts
> applications.</p>
> -
> +
> <p>Setup is almost identical to the standard
> <a
> href="../view/index.html#Installation">VelocityViewServlet
> installation</a>,
> - please review that for more details. The extended
> VelocityLayoutServlet, or any
> - custom extension, can also be used with Struts.
> (That particular servlet adds
> + please review that for more details. The extended
> VelocityLayoutServlet, or any
> + custom extension, can also be used with Struts.
> (That particular servlet adds
> the ability to reuse shared html layout across
> multiple pages.)</p>
> -
> +
> <p>Steps by step:</p>
> <ol>
> <li><strong>velocity-tools-x.x.jar</strong>
> which contains the VelocityStruts
> and VelocityView classes must be added to the
> WEB-INF/lib directory.</li>
> - <li>VelocityViewServlet needs to be installed
> into the servlet container
> + <li>VelocityViewServlet needs to be installed
> into the servlet container
> (web.xml) so it can handle all request for *.vm
> files.</li>
> <li>velocity.properties configuration file must
> be added </li>
> - <li>toolbox.xml file must be added, and mappings
> must be setup for the
> - standard tools which expose the Struts objects
> to the template. (sample
> + <li>toolbox.xml file must be added, and mappings
> must be setup for the
> + standard tools which expose the Struts objects
> to the template. (sample
> toolbox.xml file below)</li>
> </ol>
> <p>And that's all there is to it!</p>
> - <p>At this point, it should be possible to change
> a Struts ActionMapping
> - to 'forward' to a *.vm file placed in the webapp
> root directory and have
> + <p>At this point, it should be possible to change
> a Struts ActionMapping
> + to 'forward' to a *.vm file placed in the webapp
> root directory and have
> it be displayed!</p>
> -
> +
> <p><b>toolbox.xml</b></p>
> <sourcecode>
> <?xml version="1.0"?>
> @@ -169,6 +169,16 @@
> <scope>request</scope>
>
> <class>org.apache.velocity.tools.struts.FormTool</class>
> </tool>
> + <tool>
> + <key>tiles</key>
> + <scope>request</scope>
> +
> <class>org.apache.velocity.tools.struts.TilesTool</class>
> + </tool>
> + <tool>
> + <key>validator</key>
> + <scope>request</scope>
> +
> <class>org.apache.velocity.tools.struts.ValidatorTool<
> ;/class>
> + </tool>
> </toolbox>
> </sourcecode>
>
> @@ -176,27 +186,27 @@
>
> <section name="Rendering the View">
>
> - <p>This section introduces you to the key concepts
> of rendering
> + <p>This section introduces you to the key concepts
> of rendering
> the view with Velocity in a Struts application.</p>
>
> <subsection name="Velocity Template Language">
>
> - <p>Velocity is a template engine implemented
> in Java. Velocity
> - templates typically are HTML pages with
> embedded scripts (although
> - Velocity has been used for many other
> application scenarios). Scripts
> - are written in the Velocity Template Language
> (VTL). Following is a
> + <p>Velocity is a template engine implemented
> in Java. Velocity
> + templates typically are HTML pages with
> embedded scripts (although
> + Velocity has been used for many other
> application scenarios). Scripts
> + are written in the Velocity Template Language
> (VTL). Following is a
> simple example of a HTML view with embedded
> VTL statements:</p>
> -
> +
> <sourcecode>
> <HTML>
> <BODY>
> <h2>Order Confirmation</h2>
> -
> - <h3>Delivery Adress:</h3><br>
> +
> + <h3>Delivery Adress:</h3><br>
> Name: $customer.name<br>
> Street: $customer.street<br>
> City: $customer.zip $customer.city
> -
> +
> <h3>Ordered Items</h3><br>
> <table>
> #foreach( $item in $order.items )
> @@ -207,7 +217,7 @@
> #end
> </table>
> </body>
> -</html>
> +</html>
> </sourcecode>
>
> <p>When processed this will produce output
> similar to the following.</p>
> @@ -216,12 +226,12 @@
> <HTML>
> <BODY>
> <h2>Order Confirmation</h2>
> -
> - <h3>Delivery Adress:</h3><br>
> +
> + <h3>Delivery Adress:</h3><br>
> Name: Peter Pan<br>
> Street: Crain St. 10<br>
> City: 60201 Evanston IL
> -
> +
> <h3>Ordered Items</h3><br>
> <table>
> <tr>
> @@ -234,78 +244,78 @@
> </tr>
> </table>
> </body>
> -</html>
> +</html>
> </sourcecode>
>
> - <p>VTL has been designed from the ground up as
> a simple template
> - language for view designers. With less than
> ten supported directives
> - it is easy to learn. In fact, most people are
> up and productive within
> + <p>VTL has been designed from the ground up as
> a simple template
> + language for view designers. With less than
> ten supported directives
> + it is easy to learn. In fact, most people are
> up and productive within
> less than a day.</p>
> -
> - <p>Velocity does not allow Java scriptlets,
> which helps enforce a
> +
> + <p>Velocity does not allow Java scriptlets,
> which helps enforce a
> strict MVC separation.</p>
> -
> - <p>Please consult the following two documents
> for an in-depth coverage
> +
> + <p>Please consult the following two documents
> for an in-depth coverage
> of VTL:</p>
> -
> +
> <ul>
> <li><a
> href="http://jakarta.apache.org/velocity/user-guide.html">Velo
> city User's Guide</a></li>
> <li><a
> href="http://jakarta.apache.org/velocity/vtl-reference-guide.h
> tml">VTL Reference Guide</a></li>
> </ul>
> -
> +
> <br clear="all"/>
> -
> +
> </subsection>
>
> <subsection name="Exposing Data">
>
> - <p>The main purpose of Velocity in a web
> application is typically to
> - merge HTML templates with dynamic application
> data to generate
> - dynamic views. An essential aspect of Velocity
> is therefore the
> - mechanism that allows the application
> controller (in MVC speak) to
> - expose data to the template.</p>
> -
> - <p>It is important to understand the
> relationship between a
> - Struts-based application and the Velocity
> template servlet. Both
> + <p>The main purpose of Velocity in a web
> application is typically to
> + merge HTML templates with dynamic application
> data to generate
> + dynamic views. An essential aspect of Velocity
> is therefore the
> + mechanism that allows the application
> controller (in MVC speak) to
> + expose data to the template.</p>
> +
> + <p>It is important to understand the
> relationship between a
> + Struts-based application and the Velocity
> template servlet. Both
> are simply Java Servlets which perform a
> specific task.</p>
>
> <p> Requests to the Struts application are
> processed, application data
> - is manipulated and eventually all data and
> control is forwarded to a
> + is manipulated and eventually all data and
> control is forwarded to a
> View layer.</p>
>
> - <p>The Velocity servlet in this case is
> responsible for merging the
> + <p>The Velocity servlet in this case is
> responsible for merging the
> provided application data with a template to
> produce HTML output.</p>
>
> - <p>We should note that the Velocity servlet is
> not exclusively tied
> - to the Struts application. It can serve
> requests from web clients
> - directly or any other servlet application as
> well. Technically, the
> - Struts application hands over a request to
> Velocity through the
> + <p>We should note that the Velocity servlet is
> not exclusively tied
> + to the Struts application. It can serve
> requests from web clients
> + directly or any other servlet application as
> well. Technically, the
> + Struts application hands over a request to
> Velocity through the
> <code>forward</code> method of
> <code>javax.servlet.RequestDispatcher</code>.
> </p>
> -
> - <p>Application data is passed from the Struts
> servlet to the Velocity
> +
> + <p>Application data is passed from the Struts
> servlet to the Velocity
> servlet as attributes of either the servlet
> request, session or context.</p>
> -
> - <p>Therefore a developer simply needs to set
> an attribute to pass data
> +
> + <p>Therefore a developer simply needs to set
> an attribute to pass data
> to the View layer and make that data available
> for the template. For example:
> </p>
> <p>
> <sourcecode>request.setAttribute("Customer",
> CustomerObj);</sourcecode>
> - Whatever public methods are available on the
> CustomerObj instance will be
> - made available to the template designer.
> Assuming there is a public
> - getName() method, they may for example write:
> $Customer.name or
> + Whatever public methods are available on the
> CustomerObj instance will be
> + made available to the template designer.
> Assuming there is a public
> + getName() method, they may for example write:
> $Customer.name or
> $Customer.getName().
> </p>
>
> <p>[TODO: Explain chaining of attributes] </p>
> -
> +
> </subsection>
>
> <subsection name="Access to Servlet Resources">
>
> - <p>VelocityStruts automatically populates the
> context with the following
> + <p>VelocityStruts automatically populates the
> context with the following
> objects of the Servlet API on each template
> processing request:</p>
> -
> +
> <table>
> <tr>
> <th>Context Key</th>
> @@ -332,13 +342,13 @@
> <td>javax.servlet.http.HttpServletResponse</td>
> <td>the current servlet response</td>
> </tr>
> - </table>
> + </table>
>
> <br clear="all"/>
>
> <p>The following examples illustrates how
> servlet resources are
> accessed from within Velocity template. The
> example renders
> - the list of HTTP header fields of the current
> servlet request.
> + the list of HTTP header fields of the current
> servlet request.
> In the same way, any public method of the
> above listed objects can
> be called from within templates:</p>
>
> @@ -368,23 +378,23 @@
>
> <p>The Struts framework provides resources that
> are useful to template designers. These
> include logical names for
> - physical resources, internationalized
> messages, error handling,
> - form handling, etc. The interesting question
> is now how template
> - designers can gain access these framework
> resources. In the JSP world, a set
> + physical resources, internationalized
> messages, error handling,
> + form handling, etc. The interesting question
> is now how template
> + designers can gain access these framework
> resources. In the JSP world, a set
> of custom tag libraries provide template
> designers access to the Struts framework
> resources. In the Velocity
> - world, the equivalent of the JSP custom tag
> libraries are <b>view
> - tools</b>. View tools are a very simple
> concept. They are Java objects
> + world, the equivalent of the JSP custom tag
> libraries are <b>view
> + tools</b>. View tools are a very simple
> concept. They are Java objects
> with public methods that are put into the
> Velocity context. Tools are
> accessed by key and allows template designers
> to call on their public methods.</p>
> -
> - <p>A set of four view tools is included with
> VelocityStruts
> +
> + <p>A set of seven view tools is included with
> VelocityStruts
> that provide template designers access to
> Struts framework resources.
> - These four view tools essentially achieve the
> integration between
> + These seven view tools essentially achieve the
> integration between
> Struts and Velocity and they can be considered
> the core of this
> project.</p>
> -
> - <table>
> +
> + <table>
> <tr>
> <th>Context Key</th>
> <th>Class</th>
> @@ -401,6 +411,11 @@
> <td>Provides methods to check for and
> output Struts error messages.</td>
> </tr>
> <tr>
> + <td>$actionmsgs</td>
> + <td><a
> href="ActionMessagesTool.html">ActionMessagesTool</a></td>
> + <td>Provides methods to work with Struts
> action messages.</td>
> + </tr>
> + <tr>
> <td>$link</td>
> <td><a
> href="StrutsLinkTool.html">StrutsLinkTool</a></td>
> <td>Provides methods to work with URIs.</td>
> @@ -408,26 +423,38 @@
> <tr>
> <td>$form</td>
> <td><a href="FormTool.html">FormTool</a></td>
> - <td>Provides miscellaneous methods to work
> with forms and form
> + <td>Provides miscellaneous methods to work
> with forms and form
> beans in the context of Struts applications.</td>
> </tr>
> <tr>
> - <td colspan="3">Note: The shown keys are
> the recommended values.
> + <td>$tiles</td>
> + <td><a href="TilesTool.html">TilesTool</a></td>
> + <td>Provides miscellaneous methods to work
> with Tiles in the
> + context of Struts applications.</td>
> + </tr>
> + <tr>
> + <td>$validator</td>
> + <td><a
> href="ValidatorTool.html">ValidatorTool</a></td>
> + <td>Provides methods to dynamically
> generate javascript validation
> + in the context of Struts applications.</td>
> + </tr>
> + <tr>
> + <td colspan="3">Note: The shown keys are
> the recommended values.
> They can be changed in the configuration.</td>
> </tr>
> - </table>
> -
> + </table>
> +
> <p>The following example illustrates some of
> the features of the MessageTool
> for working with internationalized messages.
> For the example we assume that
> the Struts message resources contain the
> following two key=value pairs:</p>
> -
> +
> <sourcecode>
> title=Struts Example Application
> test=This string has 4 replacement parameters: {1}, {2}, {3}, {4}
> -</sourcecode>
> +</sourcecode>
>
> <p>Then, the following script...</p>
> -
> +
> <sourcecode>
> $msg.get("title")
> $msg.get("test", ["bear", "dog", "cat"])
> @@ -443,10 +470,10 @@
> false
> en
> </sourcecode>
> -
> - <p>Please see the <a
> href="StrutsTools.html">Tool Reference Documentation</a>
> - for more details about the view tools.
> Furthermore, the Velocity/Struts
> - <a href="index.html#Download">example
> application</a> comes with several
> +
> + <p>Please see the <a
> href="StrutsTools.html">Tool Reference Documentation</a>
> + for more details about the view tools.
> Furthermore, the Velocity/Struts
> + <a href="index.html#Download">example
> application</a> comes with several
> working examples that show how these tools are
> used.</p>
>
> <br clear="all"/>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org