Integrating Forms into a Wizard

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

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

• 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"
  }