This example shows how Struts Flow can be used to easily create a multi-page form, commonly called a wizard. The example uses a script called wizard.js which uses Struts Flow to define a Wizard object. The Wizard object handles displaying forms, automatic handling of forward-backward navigation buttons, and data model population. The validation and population processes are pluggable so custom code can be inserted at those steps.

To demonstrate the wizard, this example shows a user registration process with three screens: names, hobbies, and a summary display. A java.util.Map is used to store the information submitted by the forms. To keep it simple, no Struts JSP tags are used, but could be by wrapping model with an ActionForm. There are two parts to the example: the flow code which uses the Wizard object, and the JSP's that display the output - again, no Struts configuration file necessary.

Here is what the flow code for the Registration controller looks like:

flow.load("/WEB-INF/wizard/controllers/wizard.js");

RegistrationController = function() {

    this.register = function() {
        var model = new java.util.HashMap();

        var wizard = new Wizard(model);
        wizard.populate = populate;
        wizard.validate = validate;
      
        wizard.showForm( { "action" : "name-form" }, {
                  "title" : "User Name Information"
                  });
        wizard.showForm( { "action" : "hobbies-form" }, {
                  "title" : "User Hobbies"
                  });
        wizard.showForm( { "action" : "summary-form" } , {
                  "title" : "User Summary"
                  });  
    };              
}

function populate() {
  var m = struts.paramValues;
  for (var i = m.keySet().iterator(); i.hasNext(); ) {
    var key = i.next();
    this.model.put(key, m.get(key)[0]);
  }
  // Bug in commons-chain prevents this
  //this.model.putAll(struts.paramValues);
}

function validate() {
  if (this.model.get("name").length() < 2) {
    return "Name must be specified";
  }
}

Notice the logic for the wizard itself is really simple. The validation and population methods can either be manually done as show here, or use frameworks like commons-validator and commons-beanutils. Notice also there is no handing of navigation as that is all taken care of by the Wizard object.

This is the first form in the wizard:

<html>
<head>
  <title><%=request.getAttribute("title")%></title>
</head>
<body>

  <h1><%=request.getAttribute("title")%></h1>
  <p>
  Enter your name information:
  </p>

  <center style="color:red"><%=(request.getAttribute("errors") != null ? request.getAttribute("errors") : "")%></center>
  <form action="register.do" method="POST">

  <% java.util.Map form = (java.util.Map)request.getAttribute("form"); %>
  <table>
   <tr>
      <th>First Name</th>
      <td><input type="text" name="name" value="<%=(form.get("name") != null ? form.get("name") : "")%>"/></td>
    </tr>

   <tr>
      <th>Last Name</th>
      <td><input type="text" name="lastname" value="<%=(form.get("lastname") != null ? form.get("lastname") : "")%>"/></td>
    </tr>

   <tr>
      <th>Middle Name</th>
      <td><input type="text" name="middlename" value="<%=(form.get("middlename") != null ? form.get("middlename") : "")%>"/></td>
    </tr>
  </table>

  <input type="hidden" name="contid" value='<%= request.getAttribute("contid") %>' />
  <input type="submit" name="next" value="Next" />
  </form>

</body>
</html>

The hidden input variable contid stores the continuation to load from when the form gets submitted. Since no Struts JSP tags are used, scriptlets are necessary to retrieve and display data stored in the request.