Wizard

A Wizard is a Toolkit feature that arranges one or more Forms in a sequence in a user interface. For example, the Shopping Cart and Centralized Order Entry pages are built using Wizards. Whereas filling out and saving a form is a one-page, one-step action, a wizard allows for a series of multiple steps.

The Wizard itself is a container that allows you to combine Forms, Controls, and HTML into a sequence of #Wizard Steps, linked together by #Wizard Form Buttons (such as Save, Cancel, Next, Back).

More complex logic can be added to Wizard Form Buttons that can jump steps or branch to various steps based on user's inputs and other underlying data.

Wizards are used in iWeb and eWeb as a Page Detail content type. Wizards are especially powerful in eWeb because they can direct a user to various pages after saving a record by specifying a destination page, with additional querystring parameters if needed.

Wizards are setup in the Toolkit module. Once a Wizard is in the UI, design links appear that enable you to modify the wizard from within the pages the wizard appears.

Wizard

Below is the Wizard form as viewed in the Toolkit module. In most iWeb wizards, the buttons appear on the bottom. In eWeb wizards, you might want the buttons to appear on the top and bottom. The progress and css fields are optional and are often not used.


Wizard Step

Wizard Steps are used for adding an optional progress bar.

Wizard Form

Wizard Forms are added from the Wizard page from a child form.

Wizard Form Button

Wizard Form Buttons are the buttons that appear on the top, bottom, left, right (depending on the checkboxes you checked on the Wizard) of a Wizard form. The buttons are setup from a child form under the Wizard Form.

The Destination URL allows you to put in query string parameters that will be appended to the querystring on the next page. If you want the next page to add a record be sure to add "Action=Add". If your first page adds a record, and the second page lets you edit the record you just added with a different form, then put "ind_cst_key={ind_cst_key}" but do not put "Action=Add" as netFORUM will try to add a new record instead of editing the existing record.

Wizard Form Button Visibility

Wizard Form Buttons can be configured to be visible or invisible programatically depending on certain conditions. Using the visible control setting, you can encode Visibility SQL to make the button turn on or off.

In this field, you type a SQL command that will run. you put it between tags like this: 

SQL[ sql command ]

The SQL command may use parsed values. The SQL command may be a SP or inline SQL. If the SQL command returns 1 or more rows, then the button is visible; otherwise the button is not visible.

By running this SQL command on a netFORUM database we see 20+ examples for inspiration. 

SELECT wzb_visible_control
FROM md_wizard_form_button
WHERE wzb_visible_control IS NOT NULL

Here are some examples of what you can do: 

sql[SELECT 'true' WHERE dbo.av_form_has_tabs({dyc_dyn_key}) = 'true']
SQL[SELECT visible='yes' WHERE {inv_nettotal}!='$0.00']
sql[SELECT 'true' WHERE dbo.av_form_has_tabs({dyc_dyn_key}) = 'false']
SQL[SELECT visible='yes' WHERE {inv_nettotal}!='$0.00']
SQL[SELECT visible='yes' WHERE {inv_nettotal}='$0.00']
SQL[SELECT visible='yes' WHERE {RegPath} = 'EventRegNoFees']
SQL[SELECT visible='yes' WHERE {inv_cst_key}='00000000-0000-0000-0000-000000000000' AND {inv_invoice_detail_count}>0]
SQL[sc_cust_info_cont 'Shipping Fee',{ShoppingCartShippingPage},'$0.00',{inv_invoice_detail_count},{inv_shippable_items_flag}]
SQL[sc_cust_info_cont 'Confirm',{ShoppingCartShippingPage},{inv_nettotal},{inv_invoice_detail_count},{inv_shippable_items_flag}]
SQL[SELECT visible='yes' WHERE {inv_nettotal}='$0.00']
SQL[SELECT visible='yes' WHERE {inv_cst_key}!='00000000-0000-0000-0000-000000000000' AND {inv_invoice_detail_count}>0]  
SQL[SELECT visible='yes' WHERE {RegPath} = 'EventRegFees']
sql[SELECT 'true' WHERE {skipped}='true']
SQL[sc_cust_info_cont 'Payment',{ShoppingCartShippingPage},{inv_nettotal},0,{inv_shippable_items_flag}]

Note that this command is running a SP: 

SQL[sc_cust_info_cont 'Shipping Fee',{ShoppingCartShippingPage},'$0.00',{inv_invoice_detail_count},{inv_shippable_items_flag}]

Best Practice

You may want to have many buttons that turn on and off depending on certain conditions. Just be sure that your conditions are mutually exclusive (eg button A apprears when condition X if false; button B appears when condition X is true) or else you might have too many buttons appearing.

Using the Save for Later Wizard Function

The Save for Later function allows progress to be saved when using a wizard in netFORUM. Enable this button for as many or as few wizards as you wish. For the Save for Later button to appear, the wizard must have a primary progress bar object selected. See User Home - Pending Work for more on how an end user can manage saved work.

Enabling the Save for Later Button

The Save for Later button must be individually enabled where needed for each form in a wizard.  To enable the Save for Later button in a wizard form:

  1. Navigate to the Toolkit module.
  2. Using the Wizardsgroup item, Add or Locate the desired wizard.
  3. In the selected Wizard Profile, expand the formschild form.
  4. Click the folder icon next to the form to which the Save for Later button is to be added.  The Form Button grandchild form will expand.
  5. Click the Add Buttons hyperlink.

    The Add–Wizard Form Button form will appear.

  6. In the button action drop-down menu, select the Save for Later option.
  7. In the button caption field, enter the caption "Save for Later".  If no caption is entered, the button will appear as blank.
  8. Fill in any other desired parameters in the Add–Wizard Form Button form.
  9. Click Save.

The Save for Later button has been created for the form you specified.  If you return to the forms child form and view the buttons, note that the Save for Later button now appears.

Once the Save for Later button has been set up in the desired wizard form, it immediately becomes available.  Forms that have been saved for later appear in the pending facades child form, in User Home.

Setting up Wizard Button Access Keys

Assign quick access keys to wizard buttons, allowing users to perform button actions in the wizard by pressing ALT + the assigned access key letter.  For example, if the letter S is set as the quick access key for the Save action on a wizard form, pressing ALT + S will cause wizard form information to be saved, as though the Save button was actually clicked.

To set access keys for wizard buttons:

  1. Navigate to the desired wizard.  In the following example screenshots, the Individual Event Registration Wizard is used.
  2. Click the Edit Wizard Form button at the bottom of the form.  The Edit–Wizard form appears.
  3. In the Edit–Wizard form, expand the forms child form.
  4. Click the grandchild form folder icon to expand the add button grandchild form.

    Access keys can be applied to new and preexisting form buttons.

  5. Click the add buttons hyperlink to add a new button, or click the edit icon next to a pre-existing button.
  6. In the Add or Edit Wizard Form Button form, locate the access key field. In the access key field, enter the letter to be assigned as the access key for this button.  In the screenshot below, the letter "T" has been set as the access key for this button.

    7. Note: Access keys can be set as a single letter from A to Z.  Numeric values and other characters are not accepted.

    Note: On the Add or Edit Wizard Form Button form, note the values selected in the wizard form and button action drop-down fields

  7. The value selected in the wizard form field indicates on what part of the wizard the access key will work, and the button action value indicates the result of pressing ALT + the access key.  In the example above, the access key will only work on the Payment Information form of the selected wizard, and the action that will result is the Validate action.
  8. Click Save to preserve changes.

Uses

eWeb

Wizards are used in eWeb on a CMS Page Detail.

Suppress Title and Header

If you want to suppress the Wizard Title and Form Header and the pipe that separates them from appearing on a web page, then you can add a new Page Detail that overrides the CSS classes that style these elements. Order the new Page Detail's row under the Page Detail for the Wizard and make the content type be HTML and include this text: 

<STYLE   type="text/css">
.WizardTitle [|display:none;|]
.WizardTitleSeparator [|display:none;|]
.WizardHeader [|display:none;|]
</STYLE>

The [| and |] characters are "escape" characters in CMS that represent { and }. Using braces will cause the text to be parsed. When rendered, the actual HTML delivered to the browser will be: 

<STYLE   type="text/css">
.WizardTitle {display:none;}
.WizardTitleSeparator {display:none;}
.WizardHeader {display:none;}
</STYLE>

Viewed from the CMS Designer, the page and its details will look like the nearby image. Observe that the HTML page detail is below the Wizard page detail.


If you want to suppress the title and heard from all wizards on a site, you could modify your style sheet.

A longstanding trick/hack to suppress this was to set the wizard title to use HTML comment tags as in < !-- BEGIN HIDE WIZARD TITLE and each wizard form header to be END HIDE WIZARD FORM HEADER --> which basically comments out the whole section when rendered. Abila recommends against this because in certain cases, the "closing" comments might not appear when you expect it to, which can result in the rest of the page being hidden.

See Also