## Integrating Forms into a Wizard

Templating System : User Guide

This document outlines the steps necessary to build a dynamic form wizard in Tcl code.

Updated documentation of wizards

### Create a wizard

Use the `wizard create` command to initialize a wizard, declaring any wizard state variables in the `-params` option:

    wizard create make_sandwich -params { sandwich_id }

See the wizard API for optional parameters to this command.

### Add steps

Once the wizard is created, use the `wizard create` command to add steps to it:

    wizard add make_sandwich -label "Add the lettuce" -url "add-lettuce"

In auto-generated wizards, the wizard steps appear in the order they were created. See the wizard API for optional parameters to this command. Alternatively, wizard steps can be created in the `wizard create` statement with the `-steps` option:

    wizard create make_sandwich -action "eat-sandwich.acs?sandwich_id=$sandwich_id" -params {
      sandwich_id
    } -steps {
      1 -label "Add Meat"    -url "add-meat" -repeat
      2 -label "Add Lettuce" -url "add-lettuce"
      3 -label "Add Cheese"  -url "add-cheese" -repeat
    }

### Setting wizard state variables

Most likely, a wizard will store one or more state variables using the `-params` option in the `wizard create` statement. At any point in the wizard process, a state variable's value can be updated using the `wizard set_param` command.

    # check to see if a sandwich_id has been passed in by the wizard
    request set_param sandwich_id -datatype integer -optional

    # if not, then set the sandwich_id
    if { [template::util::is_nil sandwich_id] } {

      set db [ns_db gethandle]
      query sandwich_id onevalue "select sandwich_id_seq.nextval from dual" -db $db
      ns_db releasehandle $db

      wizard set_param sandwich_id $sandwich_id
    }

### Integrating forms into the wizard

Integrating forms into the wizard involves augmenting the standard ATS form by:

- Adding wizard submit buttons to the form in place of the standard form submit button:

  In the .tcl file:

      if { [wizard exists] } {
        wizard submit form_name -buttons {
          { previous "Back" } repeat { next "Continue" } { finish Save }
        }
      } else {
        element create form_name submit -datatype keyword -widget submit
      }

  In the .adp file:

      <formtemplate id=@form_name@ style=wizard>

- Advancing the wizard with the `wizard forward` command. The page the wizard forwards to depends on which wizard submit button was pressed (next, repeat, previous, finish):

      if { [wizard exists] } {
        # go to the next wizard step
        wizard forward
      } else {
        template::forward "http://cms.arsdigita.com"
      }

templating@arsdigita.com