I recently had to write a multi-step form in Drupal 6. Of course, I turned to documentation to see how others are doing it. Pro Drupal Development offers the basics, so do the 5 to 6 upgrade notes, and others. I felt that many approaches suffered from design flaws that made the code cumbersome to manage beyond a couple steps. I set out to develop a multi-step form method with the following goals:

• One form builder with nested conditional statements is difficult to manage, each step should be its own form array function
• Steps shouldn't be numbered, e.g. to move to the next step don't $form_state['storage']['step']++
• Each step should be able to have its own validate and submit handlers
• Steps should be form alterable

Skip to the attachments for full code example

As far as Form API knows, there is one form builder and thus one validation and submit function. The key is, each piece (builder, validate, and submit function) directs to sub-functions that perform during the appropriate step. Value elements are heavily used to control flow by informing the system what the next step is and for handling step validation and submit.

Let's look at some pseudo-code to explain the main idea of what I'm doing.

The advantage here is each step knows the next step and each step is contained within its own function, allowing for easy modification. The main form builder function dispatches to each individual step to build its own form array. The form submit handler stores submitted values in form storage per usual.

Let's look at some Drupal code now.

See the full example in the attachments section

As you can see, this method uses special form value elements to define the flow. The main builder uses variable functions to delegate which step it is. The second step, _multistepform_form_food() does not set a 'step_next' value and so on submission we don't set a step that will be called when we return to the main builder. I use the 'this_step' value to namespace submitted values in form storage. Other than displaying the message "Complete!" I am not actually doing anything with the final, collected values yet.

The same delegation method using variable functions that the main form builder does can be applied to validate and submit handlers by creating value elements 'step_validate' and 'step_submit' with function names as the value in step form builders and the following main validate and submit addition:

And this code in multistepform_form_submit().

Custom validation functions can form_set_error() normally. By specifying a step submit, our submit function can alter the form flow, skipping steps.

In this example if the user says (s)he doesn't like music (Who would choose that, really?) then instead of seeing the step _multistepform_form_music() (s)he gets sent to _multistepform_form_final().

I touched on the 'this_step' value element earlier, but it plays the part of identifying individual steps, allowing each step to be form alterable. Your implementation of hook_form_alter() could look for the multi-step form_id and if $form['this_step'] matches what you're looking for. hook_form() may offer a solution, but I'm not certain it's better or easier than using an additional value element.

After developing this method I was informed it is like Chaos tool suite's wizard. Other multi-step form approaches exist such as Pageroute, an object-based approach to steps of a flow.

The important pieces to use are variable functions and passing the $form_state array around by reference. For further exploration on this method I plan to see if it could be used to move backwards in a form, returning to previous steps. And the special value elements here are just a convention but I could see them being defined by hook_element().

Take a look at the attached .module for a full example spanning more than two steps. The code implements custom validation and a custom submit handler to alter form flow. If you would like to demo the code you'll need a multistepform.info file. Further directions for module development is in the Drupal handbooks.

• Ben Jeavons's blog
• 
• 
• 
• 
• 
• 
• 
•