The Bakery Everything CakePHP

If you have ever tried creating a multi-page form, you have probably realized that adding even a second page introduces several new considerations, such as: data persistence, user navigation, page refreshing and double submission, and cleanly handling each page's data validation and error handling. The wizard component automates the nitty gritty that comes with multi-page forms and lets you focus on handling the user's data.

Simple Example

Lets create a simple example to show how rapidly a multi-page form can be created with the WizardComponent.

For this example, I am going to be creating a 4 step signup wizard that includes the following steps:

1. Account Info
2. Mailing Address
3. Billing Info
4. Review

There will also be a "confirmation" page at the end to confirm the user's signup. This is a very simple example and a wizard like it probably doesn't have a whole lot of real world usefulness, but I just want to demonstrate how the component is used and highlight a couple things as we go along.

It is important to note that though we will using multiple models, the entire wizard will be contained in one controller. Also, I will be using the words 'step' and 'page' interchangeably - I'm merely referring to a page in the multi-page wizard.

So after downloading wizard.php into our project's component folder, we include it in our controller's $components array just as we would any other component:

Controller Class:

Download code <?php 
class SignupController extends AppController {
    var $components = array('Wizard');
}
?>
Next, we're going to setup our $steps array, which is an ordered list of steps for the wizard to follow. Each step will have its own view and will be processed by its own controller callback method. There is also another optional callback for each step that will be discussed later.

The steps array is setup in your controller's beforeFilter():

Download code
    function beforeFilter() {
        $this->Wizard->steps = array('account', 'address', 'billing', 'review');
    }

The next step is to create the views used in the signup wizard. The names of the views correspond to steps names included in $steps (account.ctp, address.ctp, etc). I'll include the first view (account.ctp) just to highlight a couple things.

View Template:

Download code
<?=$form->create('Signup',array('id'=>'SignupForm','url'=>$this->here));?>
    <h2>Step 1: Account Information</h2>
    <ul>
        <li><?=$form->input('Client.first_name', array('label'=>'First Name:','size'=>20,'div'=>false));?></li>
        <li><?=$form->input('Client.last_name', array('label'=>'Last Name:','size'=>20,'div'=>false));?></li>
        <li><?=$form->input('Client.phone', array('label'=>'Phone Number:','size'=>20,'div'=>false));?></li>
    </ul>
    <ul>
        <li><?=$form->input('User.email', array('label'=>'Email:','size'=>20,'div'=>false));?></li>
        <li><?=$form->input('User.password',array('label'=>'Password:','size'=>20,'div'=>false,));?></li>
        <li><?=$form->input('User.confirm',array('label'=>'Confirm:','size'=>20,'div'=>false,'type'=>'password'));?></li>
    </ul>
    <div class="submit">
        <?=$form->submit('Continue', array('div'=>false));?>
        <?=$form->submit('Cancel', array('name'=>'Cancel','div'=>false));?>
    </div>
<?=$form->end();?>

The first thing I want to point out is the url that the form is submitted to. Rather than submitting to the next step in the wizard, each step submits to itself, just as a normal form would do. (My favorite method is above : 'url'=>$this->here.) This is important because one of my main goals in creating this component was to allow the wizard to be easily setup and easily modified. This meant keeping the views divorced, as much as possible, from their inclusion or position in the steps array. To further this goal, I have created a WizardHelper that will be published in the bakery soon. In the above example, "Step 1" would be replaced with the $wizard->stepNumber() method.

The second thing I wanted to highlight was the component's ability to handle data for multiple models (the same as single page forms). This is possible because every step has its own custom callback to process its data.