Drupal 7 multistep forms using variable functions

I like building forms. So much so that I've even been teased about it. Despite that I want to share how multistep forms have changed for Drupal 7 and to expand on how you can use variable functions to achieve cleaner and easier form step logic, including easily moving backwards in forms. Understanding multistep in Drupal 7 was prompted by my need to create easy forms for an internal GVS project that will hopefully launch soon.

Multistep in Drupal 7

In Drupal 6 to carry data back to your form builder you set the storage key of $form_state in your submit handler. In Drupal 7, upon return to your builder after submission, you carry data over by keeping the Form API from pulling the form array out of cache*. You do so by setting $form_state['rebuild'] to TRUE in your validate or submit handlers. Another change is the first argument of your builder must be $form because of changes to drupal_get_form(). &$form_state is now your second argument to your form builder.

Update: 'rebuild' existed in Drupal 6 (thanks Wim) but now seems to be required for multistep to work in Drupal 7.

Drupal 7:

Let's look at a example:

We could of course set the message in the submit handler but I hope the example helps convey the two points of the definition arguments and setting rebuild in the submit handler.

Multistep with variable functions and FAPI handler convention

Using variable functions is a great way to make readable form step logic. And, if you combine this method with Drupal's form handler definition style and you can easily make advanced forms.

Update: This is by no means a method that exists only in Drupal 7. This is just a process I've written about before for making form-step logic easier to code and extend. What I'm writing about here is an expansion on that process.

The components:

1. Store step names (function definitions) in $form_state['storage']
2. Return the current step's form array in the main FAPI builder
3. Invoke validate and submit handlers for a individual step by appending '_validate' or '_submit' to the step definition

Let me start with the form builder and submit handler for illustration. The form ID known to FAPI will be multistep_form and multistep_form_submit the submit handler. The builder uses functions defined in storage to know which step to return and the submit handler uses FAPI convention to call a individual step's validate or submit.

Step submit handlers specify the next step to use and step builders can skip steps.

Here's a diagram depicting the flow of standard FAPI and how the builder and handlers call off to a individual step.

Here's an example individual step and it's submit handler:

The above example defines a single step and sets us up to move through the chain of several. Let's look at the next step and define how we could move backwards. We'll redefine the primary submit handler now.

Update: The form property #limit_validation_errors and a element submit property are required on back buttons should any step have anything that would trigger validation.

In our second step form builder (multistep_form_songs) we provide a back button. The primary submit handler allows the current step to remove stored data (to avoid a previously set default value when we return) and then removes the most recent step so when returned to the primary builder the previous step is used.

A full multistep example is provided in the attachment. You'll need to rename the files excluding the '.txt' extension to use. Some assumptions are made, of course, so adjustment for your use cases is required.

P.S.
If you didn't catch it, in Drupal 7 you are not limited to 'storage' for carrying data across requests. It's used in most of the examples, but you'll see that it's not required.
*I'm not clear on some core implementation specifics regarding the form cache so if you know please share!