Formhandler › How to set up a multistep form

How to set up a multistep form

If you haven't, please read the article "How to set up a simple form" first.

A multistep form is very similar to a singlestep form. Formhandler treats all forms as multistep forms internally, so a single step form is just a multistep form with only one step. Keeping that in mind, let's move on to the interesting stuff.

Options for each step of a multistep form can be accessed using the according step number (e.g. "1" for the first step).

The HTML Template

In the HTML template you have used the subpart ###TEMPLATE_FORM1### before. This subpart holds the HTML content of the first step. The subpart of the second step is called ###TEMPLATE_FORM2###.

Warning: Ugly form markup ahead. Please don't try this at home!

<!-- ###TEMPLATE_FORM1### begin -->
<form action="###REL_URL###" method="post" class="formhandler">
    <label for="name">###LLL:name###</label><br />
    <input type="text" name="formhandler[name]" value="###value_name###" /><br /><br />
 
    #button to the next step
    <input type="submit" value="###LLL:next###" ###submit_nextStep### />
</form>
<!-- ###TEMPLATE_FORM1### end -->
 
<!-- ###TEMPLATE_FORM2### begin -->
<form action="###REL_URL###" method="post" class="formhandler">
    <label for="street">###LLL:street###</label><br />
    <input type="text" name="formhandler[street]" value="###value_street###" /><br /><br />
     
    <label for="zip">###LLL:zip###</label><br />
    <input type="text" name="formhandler[zip]" value="###value_zip###" /><br /><br />
     
    <label for="city">###LLL:city###</label><br />
    <input type="text" name="formhandler[city]" value="###value_city###" /><br /><br />
     
    #button to go back to the first step
    <input type="submit" value="###LLL:prev###" ###submit_prevStep### />
     
    #button to the next step or finish
    <input type="submit" value="###LLL:next###" ###submit_nextStep### />
</form>
<!-- ###TEMPLATE_FORM2### end -->

So, as you can see, there are two separate subparts for the two steps and you can use the markers ###submit_prevStep### und ###submit_nextStep### to create buttons to lead to the steps.

TypoScript

In a multistep form it is very important to be able to control the settings separately for each steps. Formhandler lets you do this, by using the step number to group the settings:

plugin.Tx_Formhandler.settings {
 
  #Global settings valid for all steps
  templateFile = ...
  langFile = ...
   
  finishers {
    ...
  }
 
  #Settings only for the first step
  1 {
    markers {
      ....
    }
 
    initInterceptors {
      ....
    }
 
    validators {
      1.class = Validator\DefaultValidator
      1.config.fieldConf.name.errorCheck.1 = required
    }
  }
 
  #Settings only for the second step
  2 {
    markers {
      ....
    }
 
    initInterceptors {
      ....
    }
 
    validators {
      1.class = Validator\DefaultValidator
      1.config.fieldConf {
        street.errorCheck.1 = required
        zip.errorCheck.1 = required
        city.errorCheck.1 = required
      }
    }
  }
}

The specific settings for each step are grouped in a block with the key being the step number. The most important use case of this feature, setting validation rules for each step, is shown in the example code.

The rest of the workflow (creating lang files, email template, ...) is in no way different to the setup of a single step form.

You can use the markers ###value_[fieldname]### (and similar ones) to access values of fields from previous steps. Formhandler stores the values in a session and passes them on from step to step.