| <?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> |