<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-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>
  <title>Velocity Site Howto</title>
 </properties>

<body>

<section name="Velocity Site">

<p>
In Turbine, we have excellent integration with the template tool
<a href="http://jakarta.apache.org/velocity/">Velocity</a>,
we call this VelocitySite building. The reason why we want to wrap Turbine
around Velocity instead of using it on its own is to provide a completely
MVC model for building web applications where the framework has control
over the authentication, security, connection pool, etc and Velocity is
simply used as the View portion of the MVC model. Turbine is responsible
for helping you manage all the different templates as well so that you
can easily construct a site that both designers and engineers can work
together on (<strong>that is our primary goal!</strong>). The reason why this is
good is that it will help you design and build web applications that have
more functionality and less duplication of code since Turbine is fully
re-usable.
</p>

<p>
Knowledge of how Velocity works and what a Velocity Context object is
are required for understanding this documentation. This documentation also
assumes that you are using a Servlet API 2.2 and higher serlvet engine
such as <a href="http://jakarta.apache.org/tomcat/">Tomcat</a> because
we are now targeting towards using WAR archives. Although, this should
work with older servlet engines as well...it just may be slightly harder
for you to setup. You should also be familiar with the rest of the Turbine
documentation that is referenced on the <a href="index.html">index page</a>.
</p>

<p>
Here is a brief description of the way that the system works: all requests
are passed through the Turbine Servlet. The servlet is then responsible
for brokering the request, building up the Context object and then calling
Velocity's template engine to process your template document and return
the results. Pretty simple. Now, lets move on to some more detailed instructions...:-)
</p>

</section>

<section name="Screens">

<p>
Lets start off with a simple Velocity Screen to get things rolling
so you can see how powerful things are. You should compile this class into
your <em>WEB-INF/classes</em> directory.
</p>

<p>
Note: In the examples below, you should replace <code>com.yourcompany.app</code>
with the correct value for your application.
</p>

<source>
package com.yourcompany.app.modules.screens;

// Velocity Stuff
import org.apache.velocity.context.Context;

// Turbine Stuff
import org.apache.turbine.util.RunData;
import org.apache.turbine.modules.screens.VelocityScreen;

public class HelloWorld extends VelocityScreen
{
    public void doBuildTemplate( RunData data, Context context )
        throws Exception
    {
        // the context object has already been setup for you!
        context.put ("hello", "this is a test...");
    }
}
</source>

<p>
Ok, as you can see, you do not even need to return a value from your method!
You simply stuff objects into the Velocity Context and that is it! Next,
you will want to create a .vm template of the same name as your class:
HelloWorld.vm...within that template you will put the BODY portion of your
page. In other words, there is no reason to put the header/footer into
this file since that will be built seperately (more documentation on that
futher down...). You should save this document in your <em>templates/screens/</em>
directory.
</p>

<p>
You will also need to modify your TurbineResources.properties file to tell 
Turbine where to look for your new screen class.
</p>

<source>
module.packages=org.apache.turbine.modules, com.yourcompany.app.modules
</source>

<source><![CDATA[
<p>
    <font color="red">
        $hello of the emergency broadcast station.
    </font>
</p>
]]></source>

<p>
When you request a URL like this:
</p>

<p>
http://www.server.com/servlet/Turbine/template/HelloWorld.vm
</p>

<p>
What that will do is cause the system to first execute the HelloWold.java
class (if it exists) and then it will call Velocity's template engine directly
and execute the HelloWorld.vm template and then return the results back
to you.
</p>

<p>
<em>NOTE:</em> Turbine capitalizes the first letter in the class file name
before looking for the matching class in the classpath.  This allows you to
follow (somewhat) normal class naming guidelines. For example:
</p>

<p>
index.vm and Index.vm both map to Index.class

roleeditor.vm maps to Roleeditor.class

role_editor.vm maps to Role_editor.class
</p>

<p>
The result will be a fully formed HTML document with the <em>$hello</em>
replaced with the value: "this is a test...". If you want to make the URI
above shorter or easier to read, you could simply re-write things using
<a href="http://www.apache.org/docs/mod/mod_rewrite.html">mod_rewrite</a>.
For example, by removing the "<em>/servlet/Turbine/template</em>" portion
of the URI.
</p>

<p>
As you can see, this is much easier than doing servlet after servlet
because it removes a lot of the setup and other things that could potentially
go wrong. It also makes the individual template files easier to manage
and more re-usable because there isn't any surrounding page layout mixed
in with the page.
</p>

<p>
If you want to do something that is more complicated than this that
is reflected across all of your Screens, then you should write a class
that is a subclass of VelocityScreen and then put your specific code
in there. For example, if you wanted a security method to be called automaticially
without having to normally call super() to get it from an overridden method
in the superclass, you could have something like this (semi-pseudo untested
code):
</p>

<source>
package com.yourcompany.app.modules.screens;

// Velocity Stuff
import org.apache.velocity.context.Context;

// Turbine Stuff
import org.apache.turbine.util.RunData;
import org.apache.turbine.modules.screens.VelocityScreen;

public abstract class SecureScreen extends VelocityScreen
{
    protected boolean doCheckSecurity(RunData data)
        throws Exception
    {
        if (data.isSecure())
            return true;
        else
            return false;
    }

    /*
     * override the doBuild() method of the
     * TemplateScreen to always check security first
     */
    public void doBuild(RunData data, Context context) throws Exception
    {
        if ( !this.doCheckSecurity(data))
        {
            // set the template and screen to be different or do
            // some other short circuit code here
        }
        doBuildTemplate(data, context);
        return super.buildTemplate(data, context);
    }
}
</source>

<p>
What this would do is override the doBuild() method in TemplateScreen (which
is the base class that VelocityScreen subclasses from) and have it
always do a security check before displaying the content. The benefit of
this is that all you need to do to add security to your screen is to simply
subclass this class instead of VelocityScreen. There is also no need
to remember to call super() since the doBuild() method will be called for
you automaticially by Turbine. You can start to see how Turbine is simply
an extension of the servlet framework itself. For example, the Servlet
Engine will call HttpServlet's service() method for you, just like Turbine
will call your doBuild() method for you. Tight integration with tools like
Velocity just make things even cleaner. :-)
</p>

<p>
One other feature in this system is that if you are not building up
a Context object that is specific for your screen, then you do not need
to create a Java class to match the template file. You simply create the
.vm template and put it in a directory and call it with the same URI described
above. This is really useful when you have a static site of content that
you are converting to be dynamic and you only want to do small portions
of it at any one time. You can also do the opposite of this which is to
only create a Java class file and no template file. You can do this by
simply overriding the doBuild() method in TemplateScreen and returning
your results directly instead of attempting to build a template. Later,
when you want to add a template and remove the HTML code, you can change
the doBuild() into a doBuildTemplate(), build the Context object up and
you are done. Cool!
</p>

<p>
Here is an example of having templates in subdirectories and making
links to each of them.
</p>

<p>
Create a directory structure like this:
</p>

<p>
WEB-INF/templates/screens/admin/
Put <em>index.vm</em> into the <em>screens/</em> directory.
Put <em>UserAdmin.vm</em> into the <em>screens/admin/</em> directory.
</p>

<p>
In index.vm, if you want to link to UserAdmin.vm, you would add something
like this to the HTML:
</p>

<source><![CDATA[
<a href="$link.setPage("admin,UserAdmin.vm")">User Admin Screen</a>
]]></source>

<p>
As you can see above, I used a "," instead of a "/". You can use either
one here. The above will create a fully formed URI with the session information
encoded into the link if the clients brower has cookies turned off.
</p>

</section>

<section name="Layout and Navigations">

<p>
Now that you know how to create simple Screens, you are probably wondering
where the layout and navigation portions of the page come from and how
you control that. If you were not wondering that, then shame on you. :-)
Essentially, it is the same exact procedure as before except you subclass
VelocitySiteLayout and VelocitySiteNavigation instead. Again, it is possible
to not have Java class files always match up with the template and in most
cases, you probably won't need to have a user defined Context in the Layout.
</p>

<p>
Below is an example Layout. It will be searched for in the templates/layouts
directory structure and also takes advantage of the same template path
lookup code as described below:
</p>

<source><![CDATA[
#if ( $data.getMessage() )
{
    $data.getMessage()
}

<table width="100%">

<tr>
    <td>$navigation.setTemplate("/default_top.vm")</td>
</tr>
<tr>
    <td>$screen_placeholder</td>
</tr>
<tr>
    <td>$navigation.setTemplate("/default_bottom.vm")</td>
</tr>

</table>
]]></source>

<p>
The variable <em>$screen_placeholder</em> is important here because that
is where the output from your Screen will be placed. VelocitySiteLayout
is responsible for taking care of this. The other variables are for including
your Navigations into the system. The benefit of all of this is that it
enforces the View portion of the MVC model because the "body" and "navigation"
portions of your page simply becomes a variable that you can plug into
any number of Layouts and in any location. If you want to write code so
that the Layout is determined by a variable in the database or in the HTTP
request or whever, all you need to do is write your own VelocitySiteLayout
and override some of the methods in there to determine the layout based
on your own conditions instead of the system default conditions.
</p>


</section>

<section name="How the templates are found">

<p>
Since everything is keyed off the template variable, if
<em>data.getParameters().getString("template")</em>
returns <em>/about_us/directions/driving.vm</em>, the search for the Screen
class is as follows (in order):
</p>

<ol>
<li>about_us.directions.Driving</li>

<li>about_us.directions.Default</li>

<li>about_us.Default</li>

<li>Default</li>

<li>VelocityScreen</li>
</ol>

<p>
If the template variable does not exist, then <em>VelocityScreen</em>
will be executed and <em>templates/screens/index.vm</em> will be executed.
If <em>index.vm</em> is not found or if the template is invalid or Velocity
execution throws an exception of any reason, then <em>templates/screens/error.vm</em>
will be executed.
</p>

<p>
For the Layouts and Navigations, the following paths will be searched
in the layouts and navigations template subdirectories (in order):
</p>

<ol>
<li>/about_us/directions/driving.vm</li>

<li>/about_us/directions/default.vm</li>

<li>/about_us/default.vm</li>

<li>/default.vm</li>
</ol>

</section>

<section name="Actions">

<p>
Actions happen when you have an <em>action</em> parameter defined in the
URI. For example:
</p>

<p>
<ul><u>http://www.server.com/servlet/Turbine/template/HelloWorld.vm/action/UpdateWorld</u></ul>
</p>

<p>In this case, what happens is that the class UpdateWorld class (located in your
<em>WEB-INF/classes/com/yourcompany/app/modules/actions/</em> directory) 
is executed first before
anything. Then your HelloWorld class (located in your 
WEB-INF/classes/com/yourcompany/app/modules/screens/
directory) is executed. Then your template (for screen/navigation/layout)
HelloWorld.vm is executed. The point of an action is that it should perform
some sort of "action" on your system. Usually, this means storing some
information from a POST request into a database or sending email or something
of that nature. Actions themselves do not return results, but may set a
message with data.setMessage(). They can also short circuit the system
by changing the Template and Screen to be executed. You might want to do
that if there is an error with the form data and you want to re-display
the same page again. Unlike most of the rest of the modules (ie: Screens,
Navigations, Layouts), there is no corresponding Velocity template file
for an Action.
</p>

<source>
package com.yourcompany.app.modules.actions;

// Velocity Stuff
import org.apache.velocity.context.Context;

// Turbine Stuff
import org.apache.turbine.util.RunData;
import org.apache.turbine.modules.actions.VelocityAction;

public class AddUser extends VelocityAction
{
    public void doPerform( RunData data, Context context ) throws Exception
    {
        if ( data.getParameters().getString("username",null) == null)
        {
            data.setMessage("Username does not exist");
            setTemplate ( data, "AddUser.vm" );
            return;
        }

        // store user info into database
        data.setMessage("Information stored!");
        setTemplate( data, "MainMenu.vm");

        // stuff something into the Velocity Context
        context.put ("variable", "foo");
    }
}
</source>

<p>
In the very basic example Action above, a check is performed to make sure
that
the form data contained a "username" variable. If there is no data, the
template is changed back to the "AddUser" template and the processing is
stopped with an error message that can be easily displayed in the template.
If the processing finishes, then the MainMenu.vm template will be shown
and the message can be displayed.
</p>

</section>

<section name="Action Event">

<p>
There is also a new feature of Turbine that the VelocitySiteAction takes
advantage of, it is called <a href="action-event-howto.html">Action Event</a>.
Please click the link and read more documentation about it. This is an
excellent way to write your actions because now they are entirely event
driven based on which button was clicked in the HTML form.
</p>

</section>

<section name="Velocity Frames">

<p>
Frames are easily achieved with Velocity, the frameset tag being implemented at
the screen level. The default setting for the layout.default directive in the
TurbineResources.properties is the VelocityECSLayout class.
The VelocityECSLayout wraps the Screen in Body tags. For frames this needs to be
removed. The layout.default needs to be changed to;
</p>

<source>
layout.default=VelocityOnlyLayout
</source>

<p>
The layout Velocity template needs to point to the screen_placeholder. As an
example modify the Default.vm in the /WEB-INF/templates/layouts/;
</p>

<source>
$screen_placeholder
</source>

<p>
The screen_placeholder marker will load and process the template marked as the
template.homepage in the TurbineResources.properties. To create frames this is
the template which will need to contain the frameset tag. Edit
/WEB-INF/templates/screens/Index.vm;
</p>

<source><![CDATA[
$page.setTitle("Frames example");

<frameset>
  <frame src="$link.getPage("FrameTop.vm")" />
  <frame src="http://www.something.com/" />
</frameset>
]]></source>

<p>
Create a FrameTop.vm template in the /WEB-INF/templates/screens directory. The
top frame will load this template. The reference to something.com requires an
internet connection and is shown as an example, anything can be linked to the
lower frame, another Velocity Screen for instance.
</p>

<source><![CDATA[
## Example FrameTop.vm
<p><b>The FrameTop Velocity Template</b>
]]></source>

</section>

<section name="Multiple Velocity Paths">

<p>
The VelocityService can support many paths for the Velocity Templates to
be loaded and read from. This is specified in the
TurbineResources.properties file;
</p>

<source>
services.VelocityService.file.resource.loader.path = /templates,/my-templates,/more-tempates
</source>

<p>
The multiple paths are comma delimited and are specified from the
Servlet Engines context.
</p>

</section>

</body>
</document>