jford 2004/04/08 13:02:52
Added: tutorial/xdocs/13 mvcintro.xml
Log:
Coverted Chapter 13 tutorial to xdoc format
Revision Changes Path
1.1 jakarta-jetspeed/tutorial/xdocs/13/mvcintro.xml
Index: mvcintro.xml
===================================================================
<?xml version="1.0"?>
<!--
Copyright 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.
-->
<document>
<properties>
<author email="[EMAIL PROTECTED]">David Sean Taylor</author>
<title>Change the Portal Logo</title>
</properties>
<body>
<section name="Introduction to MVC Portlet">
<p>
The MVC Portlet provides a portlet framework independent of any specific view
technology.
It handles the views via a View Processor, which is a pluggable, factory created,
run time module for which ever view technology your portlet uses.
Currently three view processors are supported:
</p>
<p>
<ul>
<li>1. Velocity</li>
<li>2. JSP</li>
<li>3. XSLT</li>
</ul>
</p>
<p>
<a
href="http://jakarta.apache.org/velocity/user-guide.html#What%20is%20Velocity?";>Velocity</a>
is a Java-based template engine.
It permits web page designers to reference methods defined in Java code.
Web designers can work in parallel with Java programmers to develop web sites
according to the Model-View-Controller (MVC) model, meaning that web page designers
can focus solely on creating a well-designed site, and programmers can focus solely on
writing top-notch code.
Velocity separates Java code from the web pages, making the web site more
maintainable over the long run and providing a viable alternative to <a
href="http://java.sun.com/products/jsp/";>Java Server Pages</a> (JSP) or <a
href="http://www.php.net/";>PHP</a>.
</p>
<p>
Jetspeed has a Velocity templating service built directly into the Jetspeed engine.
Many of the controls and controllers are Velocity-driven to create the layout of the
portal. You can also base your portlets on Velocity.
This means that your portlets will also follow the MVC design pattern, separating
content from code.
</p>
<p>
The examples in tutorials 5 and 6 were useful for you to learn the Portlet
interface.
However, overriding the getContent method of the portlet interface is not good
practice.
We recommend abstracting the content generation phase by basing your portlets on one
of the MVC-based portlets provided in the Jetspeed distribution; such as
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_JSP.html";>JSPPortlet</a>,
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_XSL.html";>XSLTPortlet</a>,
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_RSS.html";>RSSPortlet</a>,
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_HTML.html";>HTMLPortlet</a>
or of course the
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_Velocity.html";>VelocityPortlet</a>.
</p>
<p>A Velocity portlet is made up of the typical MVC components:</p>
<p>
<table border="1" cellspacing="0" cellpadding="0">
<tr>
<td width="284" valign="top">
<p>MVC Component</p>
</td>
<td width="284" valign="top">
<p>Velocity Component</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>Model</p>
</td>
<td width="284" valign="top">
<p>Java Objects put in the context</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>View</p>
</td>
<td width="284" valign="top">
<p>Template</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>Controller</p>
</td>
<td width="284" valign="top">
<p>Your Velocity Action</p>
</td>
</tr>
</table>
</p>
<p>
The controller is your Velocity Action class. The base <a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_Velocity.html";>VelocityPortlet</a>
class should rarely have to be modified.
Your view is a Velocity template, which will generate the content of your portlet by
pulling out dynamic model information from the Velocity context.
The getContent method of the <a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_Velocity.html";>VelocityPortlet</a>
should never be edited.
All content is generated by the template, as designed in our MVC design pattern.
</p>
<p>The Life Cycle phases of a portlet are also enhanced with the Velocity
portlet.</p>
<p>
<table border="1" cellspacing="0" cellpadding="0">
<tr>
<td width="284" valign="top">
<p>Phase</p>
</td>
<td width="284" valign="top">
<p>Method</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>Init</p>
</td>
<td width="284" valign="top">
<p>init</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>ProcessAction</p>
</td>
<td width="284" valign="top">
<p>Velocity Action and Action Events</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>Render</p>
</td>
<td width="284" valign="top">
<p>Template is called by Velocity Portlet</p>
</td>
</tr>
<tr>
<td width="284" valign="top">
<p>Destroy</p>
</td>
<td width="284" valign="top">
<p>--none--</p>
</td>
</tr>
</table>
</p>
<p>
Velocity portlets are really about dynamic content.
If you have static content, there is no real benefit to using a Velocity portlet;
take a look at one of the static content generation portlets such as the
<a
href="http://jakarta.apache.org/jetspeed/site/portlet_config_HTML.html";>HTMLPortlet</a>
instead.
The basic function of Velocity is really very simple, it substitutes live Java
objects into a Velocity template.
There is an online tutorial with great examples <a
href="http://jakarta.apache.org/velocity/user-guide.html#What%20is%20Velocity?";>here</a>.
</p>
<p>
Let's look at simple introductory example, but we recommend visiting the Velocity
site and investing some time in their well-written tutorials.
</p>
<hr />
<code>
<![CDATA[
<HTML>
<BODY>
Hello $customer.Name!
<br/>
Here is a list of your current subscriptions:<br/><br/>
<table>
#foreach( $subscription in $subscriptions )
#if ( $customer.isSubscribed($subscription) )
<tr>
<td>
$subscription.Name
</td>
</tr>
#end
#end
</table>
</BODY>
</HTML>
]]>
</code>
<p>This example is not included with the examples source code distribution.</p>
<p>
The above is an example Velocity template that displays all subscriptions for a
given customer.
There are two dynamic model objects that we are working with: the customer and
subscriptions.
Velocity uses a very simple syntax for model variables, simply prefix the variable
with a $ sign.
The designer can then access all public methods and accessors of that Java object.
Velocity uses Java reflection to find the methods.
Thus in our example above, the customer object has a getter and setter for the Name
attribute.
You don't need to specify the get prefix, Velocity will figure it out.
</p>
<p>
Velocity provides a small set of directives for logic control.
Most commonly used are #if and #foreach.
#foreach will iterate over any Java 2 collection or array.
The #if statement above calls a public method to check if the customer is subscribed
to a subscription.
Finally, the subscription name is displayed in a table column by getting the Name
attribute.
</p>
<p>
So where did these two variables ($customer, $subscriptions) come from?
</p>
<p>
They came from your action class. We will look into how to program an action class
in more detail later in this section.
Right now it's important to understand that your action class puts your model
objects into a Velocity construct called the 'context'.
The context is where all variables are made accessible to a template.
The context is the common liaison between your model and view.
Here is how the Java code would put an object into the context:
</p>
<hr />
<code>
Customer customer = CustomerPeer.retrieveByPK(primaryKey);
context.put("customer", customer);
List subscriptions = SubscriptionPeer.doSelect(criteria);
context.put("subscriptions", subscriptions);
</code>
<p>This example is not included with the examples source code distribution.</p>
<p>There is another tutorial on Velocity at <a
href="http://www.javaworld.com/javaworld/jw-12-2001/jw-1228-velocity-p2.html";>Java
World</a>.
Now that we have a basic understanding of the Velocity context and templates, let's
get back to the Velocity Portlet.
The MVC components are all configured in the portlet registry.</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
