Getting started with ZedSeriesWizard

How to create a simple wizard using ZedSeries Library extension for TYPOlight webCMS

Before reading this you must have a (almost basic) knowledge of how to create extension for TYPOlight.

Please refer to "How to create a custom module" at http://dev.typolight.org/wiki/typolight/TutorialsExtension for more information about module creation

Our first wizard

A wizard is composed by a set of steps that, once completed, will end in an action.

We'll create our first wizard prompting user for name, age and email address; our wizard will contains the following steps:

1. print a welcome message
2. ask for name and age
3. ask for email address
4. display a "thank you" message

To build our wizard we can use standard TYPOlight widget as:

FormExplanation: used in steps 1 and 4 to display the messages
FormTextField: used in steps 2 and 3 to collect name and email
SelectMenu: used in step 2 to let user choose his age from a set of predefined values

Some notes on widget:

AFAIK there is no explicit documentation for Widget class. Luckily we can use the same options used in writing DCA fields definition

Take a look at Learn how to develop for TYPOlight - TYPOlight Open Source CMS on typolight.org for more informations about writing a Data Configuration Array

ZedSeriesWizardHelper class

ZedSeries Library comes with the ZedSeriesWizardHelper class that can be used to quickly setup our wizard. This is an abstract class that contains only one abstract mehotd: getSteps. As the name suggests the getSteps method must returns an array of steps to perform in order to complete the wizard. Each step is an array of widgets to display.

The name of our class will be MyFirstWizard: we are going to extend the ZedSeriesWizardHelper class so we only need to implement the getSteps method.

<?php

class MyFirstWizard extends ZedSeriesWizardHelper {

    protected function getSteps() {
    
        $steps = array();
        
        $steps[0] = array(
        # FormExplanation is a frontend widget used by TYPOlight form generator
        # is located in TL_ROOT/system/modules/frontend/ directory
        new FormExplanation(array('text' => 'Welcome to our first wizard click next to begin'))
        );
        $steps[1] = array();
        
        # this time we'll use Controller prepareForWidget method (through ZedSeriesControllerUtils)
        # to create our input text, prepareForWidget allow us to use the same field's configuration options used in dca
        # please refer to http://api.typolight.org/Controller/Controller.html#prepareForWidget
        # for more information about parameters
        
        $steps[1][] = new FormTextField(
                $this->cu->prepareForWidget(
                    array(
                    'label' => array('Full name', 'Please enter your name'),
                    'eval' => array('mandatory'=>true)
                    ), 'fullname'
                )
            );
        
        $ageOptions = array_combine(range(17, 42), range(17, 42));
        
        $steps[1][] = new SelectMenu(
            $this->cu->prepareForWidget(
                array(
                'label' => array('Age', 'Please Enter your age'),
                'options' => $ageOptions,
                'eval' => array('mandatory'=>true)
                ), 
                'age'
            )
        );
        
        $steps[2] = array(
            new FormTextField(
                $this->cu->prepareForWidget(
                    array(
                    'label' => array('Email', 'Please enter your email address'),
                    'eval' => array('mandatory'=>true, 'rgxp' => 'email')
                    ), 
                    'email'
                )
            )
        );
        $steps[3] = array(
            new FormExplanation(
                    array('text' => 'Thank you, click finish to end the wizard')
                )
        );
        
        return $steps;
    }
}

 

Running the wizard inside TYPOlight

Ok, we have our wizard but how we can run it?

There are two ways:

1. as standalone script after initializing the TYPOlight engine: pretty useless, but useful if you want to try your wizard quickly.
   
   
   
2. inside a  (Backend|Frontend)Module using the "generate" method
   

1st way:

create a file named MyFirstRun.php and place it inside your TL_ROOT

paste the code below

<?php
define('TL_MODE', 'FE');
require_once 'system/initialize.php';

/**
* put here the MyFirstWizard class code
*
* class MyFirstWizard extends ....
*/

$obj = new MyFirstWizard();
$data = $obj->run();
echo $data;

then open http://yourhost/path/to/typolight/MyFirstRun.php and play with wizard going back and forth

2nd way:

override your module "generate" method in this way:

<?php
public function generate() {
    $wz = new MyFirstWizard();
    $data = $wz->run();
    return $data;
}
?>

then access your module and play with the wizard as usual

Array?

If you follows the above directions after hitting the "Finish" button, you've got "Array" on your screen

As you may guessed the ZedSeriesWizardHelper's run method return an array with the data entered when user completes the wizard

The ZedSeriesWizardHelper class has a "completed" property that can be used to detect if the wizard was completed:

<?php

$wz = new MyFirstWizard();

$data = $wz->run();

/* if $wz->completed == false $data contains the wizard html output

if (!$wz->completed) { 
    // use return if you are inside the generate method of a module
    # return $data; 
    echo $data;
} else {
    // $data is an associative array containing the entered user data
    print_r($data);
}

?>

The next steps

In following articles we extend our Wizard adding some validators and learning how to customize it.