Export (0) Print
Expand All

Wizard Class

Provides navigation and a user interface (UI) to collect related data across multiple steps.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

[BindableAttribute(false)] 
public class Wizard : CompositeControl
/** @attribute BindableAttribute(false) */ 
public class Wizard extends CompositeControl
BindableAttribute(false) 
public class Wizard extends CompositeControl
Not applicable.

You can use the Wizard control to:

  • Collect related data across multiple steps.

  • Break up a larger Web page used to collect user input into smaller logical steps.

  • Allow for either linear or nonlinear navigation through the steps.

The Wizard control is made up of the following components:

  • A WizardStepCollection collection of steps that contain the user interface for each step, as defined by the page developer.

  • Built-in navigation capabilities that determine the appropriate buttons to display based on the StepType value.

  • A header area that can be customized to display information specific to the step that the user is currently on.

  • A sidebar area that can be used to quickly navigate to steps in the control.

    NoteNote:

    If you are using Microsoft Visual Studio 2005, note that the ActiveStepIndex is persisted in Source view. If you change the WizardSteps property in Design view by clicking the sidebar buttons, and you then run the page, the first step of the Wizard control might not be shown because the ActiveStepIndex might be pointing to a different step.

Each of the steps in the Wizard control has a StepType property that determines the kind of navigation functionality that the step has. If you do not specify a value for the StepType property, the default value is Auto. The following table lists the available settings for the StepType property and the resulting behavior of the step.

WizardStepType.Auto

The navigation UI that is rendered for the step is determined by the order in which the step is declared.

WizardStepType.Complete

The step is the last one to appear. No navigation buttons are rendered.

WizardStepType.Finish

The step is the last one that collects user data. The Finish button is rendered for navigation.

WizardStepType.Start

The step is the first one to appear. A Previous button is not rendered.

WizardStepType.Step

The step is any step between the first and last. Previous and Next buttons are rendered for navigation.

Using the Wizard control, data can be collected through linear or nonlinear navigation. Some examples of nonlinear navigation are skipping unnecessary steps or returning to a previously completed step to change some value. The Wizard control maintains its state between steps, so the data entered on a step does not need to be persisted to a data store until all the steps of the Wizard control have been completed.

Alternatively, if you want to persist the collected data to a data store as each step is completed, such as when the NextButtonClick event is raised, you should set the AllowReturn property of the WizardStepBase object to false so that the user cannot return to a previously completed step and change the data once it has been submitted.

The Wizard control inherits the following command names from the View class and MultiView class: NextViewCommandName, PreviousViewCommandName, SwitchViewByIDCommandName, and SwitchViewByIndexCommandName. The Wizard control ignores these command names and does not include any special logic to enable these commands to automatically work for navigation. If a command name is removed or is missing from a button in the Wizard control, no exception is thrown. For example, if the StartNavigationTemplate button is missing a value for CommandName, no exception is thrown.

You can use the MoveTo method or the ActiveStepIndex property to dynamically change the step that is currently displayed in the Wizard control.

NoteNote:

If you programmatically add a WizardStep in the Page_Load event handler, you must add the navigation to that step prior to the page loading.

The appearance of the Wizard control is fully customizable through templates, skins, and style settings. For example, you can use the HeaderTemplate, SideBarTemplate, StartNavigationTemplate, FinishNavigationTemplate, and StepNavigationTemplate properties to customize the interface of the Wizard control.

NoteNote:

Setting the FinishNavigationTemplate, DisplaySideBar, HeaderTemplate, SideBarTemplate, StartNavigationTemplate, or StepNavigationTemplate property recreates the child controls of the Wizard control. As a result, the view state for the child controls is lost in the process. To avoid this situation, explicitly maintain the control state of the Wizard control's child controls explicitly, or avoid putting controls inside of templates.

Note that the Wizard control does not support special Microsoft Internet Explorer rendering for non-standard or quirks mode. To get the best Internet Explorer rendering using the Wizard control, use the XHTML doc type, which is added by default in Visual Web Developer and Visual Studio.

Accessibility

The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For example, using CancelDestinationPageUrl or FinishDestinationPageUrl result in a page refresh which is contrary to the accessibility requirement to not refresh a page when clicking a button or link on a page. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.

TopicLocation
How to: Customize the ASP.NET CreateUserWizard ControlBuilding ASP .NET Web Applications
How to: Customize the ASP.NET CreateUserWizard ControlBuilding ASP .NET Web Applications
Walkthrough: Creating a Basic ASP.NET Wizard ControlBuilding ASP .NET Web Applications in Visual Studio
Walkthrough: Advanced Use of the ASP.NET Wizard ControlBuilding ASP .NET Web Applications in Visual Studio
Walkthrough: Advanced Use of the ASP.NET Wizard ControlBuilding ASP .NET Web Applications in Visual Studio

The following code example demonstrates how to define a Wizard control to collect a user's name and address, with the option to enter a separate shipping address. If the user does not select SeparateShippingCheckBox, thereby issuing a request to add a separate shipping address, the Wizard control moves directly from Step2 to Finish. On the Finish step, the user has the option to return to the beginning of the Wizard control by clicking GoBackButton; however, it takes the user to Step2 because the AllowReturn property for Step1 is set to false.

Security noteSecurity Note:

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview (Visual Studio).

<%@ Page Language="C#" CodeFile="WizardClass.cs" Inherits="WizardClasscs_aspx" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
    <form id="form1" runat="server">    
      <asp:Wizard id="Wizard1" 
        runat="server" 
        onfinishbuttonclick="OnFinishButtonClick" 
        backcolor="#EFF3FB" 
        font-names="Verdana" 
        font-size="0.8em"
        borderwidth="1px" 
        bordercolor="#B5C7DE" 
        style="font-size: medium; font-family: Verdana;" 
        onactivestepchanged="OnActiveStepChanged">       
      <StepStyle forecolor="#333333" 
        font-size="0.8em" />
        <WizardSteps>        
          <asp:WizardStep id="Step1" 
            title="One"
            allowreturn="false" 
            runat="server" >
            Welcome to the Wizard example.  This step's AllowReturn property is set 
            to false, so after you leave this step you will not be able to return to it.
          </asp:WizardStep>          
          <asp:WizardStep id="Step2"
            title="Two" 
            runat="server" >
            <!-- ... Put UI elements here ... -->
            Please enter your billing information.
            <br />
            Name:<br />
            <asp:TextBox runat="server" 
              id="BillingName" 
              width="226px" 
              height="17px" /> 
            <br />
            E-mail Address:<br />
            <asp:TextBox runat="server" 
              id="EmailAddress" 
              width="224px" 
              height="17px" />
            <br />
            Address Line 1: <br />
            <asp:TextBox runat="server" 
              id="BillingAddressLine1" 
              width="314px" 
              height="17px" />
            <br />
            Address Line 2: <br />
            <asp:TextBox runat="server" 
              id="BillingAddressLine2" 
              width="314px" 
              height="17px" />
            <br />
            City: <br />
            <asp:TextBox runat="server" 
              id="BillingCity" 
              width="155px" 
              height="17px" /> 
            <br />
            State: <br />
            <asp:TextBox runat="server" 
              id="BillingState" 
              width="75px" 
              height="17px" /> 
            <br />
            ZIP Code: <br />
            <asp:TextBox runat="server" 
              id="BillingZip" 
              height="17px" />
            <br /><br />
            <asp:CheckBox runat="server" 
              id="SeparateShippingCheckBox" 
              text="Please check here if you would like to add a separate shipping address." />
          </asp:WizardStep>          
          <asp:WizardStep id="Step3" 
            title="Three" 
            runat="server" >
            <!-- Gather the shipping address in this step if CheckBox1 was selected. -->
            Please enter your shipping information.
            <br />
                Name:<br />
                <asp:TextBox runat="server" 
                  id="ShippingName" 
                  height="17px" /> 
                <br />
                Address Line 1: <br />
                <asp:TextBox runat="server" 
                  id="ShippingAddress1" 
                  width="370px" 
                  height="17px" />
                <br />
                Address Line 2: <br />
                <asp:TextBox runat="server" 
                  id="ShippingAddress2" 
                  width="370px" 
                  height="17px" />
                <br />
                City: <br />
                <asp:TextBox runat="server" 
                  id="ShippingCity" 
                  height="17px" /> 
                <br />
                State: <br />
                <asp:TextBox runat="server" 
                  id="ShippingState" 
                  width="65px" 
                  height="17px" />
                <br /> 
                ZIP Code: <br />
                <asp:TextBox runat="server" 
                  id="ShippingZip" 
                  height="17px" />
          </asp:WizardStep>
          <asp:WizardStep id="Finish" 
            title="Finish"
            runat="server" >
            <!-- Put UI elements here for the Finish step. -->
            <asp:Button runat="server" 
              id="GoBackButton" 
              text="Go Back to Step 2" 
              onclick="OnGoBackButtonClick"
              forecolor="#284E98" 
              font-names="Verdana"
              font-size="1.0em" 
              borderstyle="Solid" 
              borderwidth="1px" 
              bordercolor="#507CD1" 
              backcolor="White" /> 
          </asp:WizardStep>          
          <asp:WizardStep runat="server" 
            steptype="Complete" 
            title="Complete" 
            id="Complete">
            <asp:Label runat="server" 
              id="CompleteMessageLabel" 
              width="408px" 
              height="24px">
            </asp:Label>
          </asp:WizardStep>
        </WizardSteps> 
        <NavigationButtonStyle forecolor="#284E98" 
          font-names="Verdana"
          font-size="1.0em" 
          borderstyle="Solid" 
          borderwidth="1px" 
          bordercolor="#507CD1" 
          backcolor="White" />
        <HeaderStyle forecolor="White" 
          horizontalalign="Center" 
          font-size="0.9em" 
          font-bold="True"
          backcolor="#284E98" 
          borderstyle="Solid" 
          bordercolor="#EFF3FB" 
          borderwidth="2px" />
        <SideBarStyle verticalalign="Top" 
          horizontalalign="Center"
          font-size="0.8em" 
          forecolor="#000099"
          backcolor="#EFF3FB"
          width="45px" />
        <HeaderTemplate>
          <b>Wizard Example</b>
        </HeaderTemplate>
      </asp:Wizard>
    </form>
  </body>
</html>

The following code example is the code-behind file for the Web page used in the preceding example.

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

public partial class WizardClasscs_aspx : System.Web.UI.Page
{
    protected void OnFinishButtonClick(Object sender, WizardNavigationEventArgs e)
    {
        // The OnFinishButtonClick method is a good place to collect all
        // the data from the completed pages and persist it to the data store. 

        // For this example, write a confirmation message to the Complete page
        // of the Wizard control.
        Label tempLabel = (Label)Wizard1.FindControl("CompleteMessageLabel");
        if (tempLabel != null)
        {
            tempLabel.Text = "Your order has been placed. An e-mail confirmation will be sent to "
            + (EmailAddress.Text.Length == 0 ? "your e-mail address" : EmailAddress.Text) + ".";
        }
    }

    protected void OnGoBackButtonClick(object sender, EventArgs e)
    {
        // The GoBackButtonClick event is raised when the GoBackButton
        // is clicked on the Finish page of the Wizard.  

        // Check the value of Step1's AllowReturn property.
        if (Step1.AllowReturn)
        {
            // Return to Step1.
            Wizard1.ActiveStepIndex = Wizard1.WizardSteps.IndexOf(this.Step1);
        }
        else
        {
            // Step1 is not a valid step to return to; go to Step2 instead.
            Wizard1.ActiveStepIndex = Wizard1.WizardSteps.IndexOf(this.Step2);
            Response.Write("ActiveStep is set to Step2 because Step1 has AllowReturn set to false.");
        }
    }

    protected void OnActiveStepChanged(object sender, EventArgs e)
    {
        // If the ActiveStep is changing to Step3, check to see whether the 
        // SeparateShippingCheckBox is selected.  If it is not, skip to the
        // Finish step.
        if (Wizard1.ActiveStepIndex == Wizard1.WizardSteps.IndexOf(this.Step3))
        {
            if (this.SeparateShippingCheckBox.Checked)
            {
                Wizard1.MoveTo(this.Step3);
            }
            else
            {
                Wizard1.MoveTo(this.Finish);
            }
        }
    }
}

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0

Community Additions

ADD
Show:
© 2014 Microsoft