Action Events

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 VelocitySite Howto example): 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...

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!");

Then, write your HTML tags specially like this:

<input type="submit" name="eventSubmit_doAdd" value="Add User">

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.

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.

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

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.

Thus, the convention is this:

  • The variable name MUST have the prefix "eventSubmit_".
  • The variable name after the prefix MUST begin with the letters "do".
  • The first letter after the "do" will be capitalized and the rest will be lowercase

If you follow these conventions, then you should be ok with your method naming in your Action class.

There is a property in the 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.