| <?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>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> |
| http://www.server.com/servlet/Turbine/template/AddUser/action/NewUser |
| 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 (RunData data, Context context) throws Exception |
| { |
| // put code here to add the user to the system |
| context.put ("username", username ); |
| data.setMessage("User Added!"); |
| } |
| |
| public void doPerform(RunData data, Context context) throws Exception |
| { |
| 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"> |
| ]]></source> |
| |
| <p> |
| When your Action is executed, an "event" is sent to it by attempting |
| to execute a "doAdd()" method in your Action. 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. |
| </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 ParameterParser makes all the key values 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. |
| </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> |