<?xml version="1.0"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you 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>Action Events Howto</title>
 </properties>

<body>

<section name="Action Events">

<p>
Turbine has a very useful feature that makes handling form submission
much more painless for the developer. In order to understand this, you
need to be familiar with the way that Turbine handles Actions. What happens
is that when a URI has the action= variable defined, a class is executed
before all of your other Screen classes by your Page class. So, consider
the following URI (I'm using the
<a href="velocity-site-howto.html">VelocitySite Howto</a> example):
</p>

<p>
<code>http://www.server.com/servlet/Turbine/template/AddUser/action/NewUser</code>
What happens is that Turbine will first execute the Java class file Action
named NewUser. Then, any class that extends the ActionEvent class instead
of the Action class will be able to take advantage of what happens next...
</p>

<source><![CDATA[
public class NewUser extends VelocityAction
{
    public void doAdd (PipelineData data, Context context) throws Exception
    {
        // put code here to add the user to the system
        context.put ("username", username );
        getRunData(data).setMessage("User Added!");
    }

    @TurbineActionEvent("save")
    public void saveUser (PipelineData data, Context context) throws Exception
    {
        // put code here to save the modified user to persistent storage
        getRunData(data).setMessage("User Saved!");
    }

    public void doPerform(PipelineData data, Context context) throws Exception
    {
        getRunData(data).setMessage("Button not found!");
    }
}
]]></source>

<p>
Then, write your HTML tags specially like this:
</p>

<source><![CDATA[
<input type="submit" name="eventSubmit_doAdd" value="Add User">
<input type="submit" name="eventSubmit_save" value="Save User">
]]></source>

<p>
When your Action is executed, an "event" is sent to it by attempting
to execute a "doAdd()" method in your Action or a method annotated with the
event name "save", respectively. The cool thing about this
is that each of your "actions" that are performed within your Action class
now are componentized into a single method that can be javadoc'ed individually.
The annotation adds the possibility to name your events and methods any way you
like.
</p>

<p>
This new functionality does not mean that you should write all of your
actions in one single class, what it means is that if you have a screen
with many buttons on it that are very specific to that screen, it might
be a good idea to place all those methods into a single class. This allows
you to do it easily and also prevents you from having to do a "if then
elseif" tree to figure out which button was clicked.
</p>

<p>
For a catchall, the doPerform() method will be executed if no other
method or button could be found.
</p>

<p>
Because all keys processed by ParameterParser are subject to URL
case folding, (in default mode lowercase), we have
to do some work to format the string into a method name. For example, a
button name eventSubmit_doDelete gets converted into eventsubmit_dodelete.
Thus, we need to form some sort of naming convention so that dodelete can
be turned into doDelete.
</p>

<p>
Thus, the convention is this:
<ul>
    <li>The variable name MUST have the prefix "eventSubmit_".</li>
    <li>The variable name after the prefix MUST begin with the letters "do".</li>
    <li>The first letter after the "do" will be capitalized and the rest will be
        lowercase</li>
</ul>
</p>

<p>
If you follow these conventions, then you should be ok with your method
naming in your Action class. If you make use of the <code>@TurbineActionEvent</code>
annotation, you can get rid of the latter two limitations and name your events
methods as you like. Note that the event names are still subject to URL
case folding, so that by default, <code>@TurbineActionEvent("save")</code>
and <code>@TurbineActionEvent("Save")</code> are identical - unless you
run the ParameterParser with URL case folding set to NONE.
</p>

<p>
There is a property in the TurbineResources.properties file, called "action.eventsubmit.needsvalue".
If you set this to "true", only the events that contain a non-empty, non-zero value will be
executed. This is useful if you have a form with multiple, different events, that need to be executed
and the form is submitted by client-side code, e.g. JavaScript.
</p>
<p>
If you want to trigger an action event from an html link, versus a button, then just add a parameter with the name eventSubmit_doMyaction.
The value can be anything as the name is all that is important.
</p>
</section>

</body>
</document>
