Wizards

Modern applications increasingly use "wizards" to help users configure systems, provide information, or achieve some complex task that requires a number of selections to be made. Developers have found ways to build wizards in their Web applications, but ASP.NET 2.0 makes it easier than ever by providing a new Wizard control.

The aims of the Wizard control are listed below.

• Make it easy for developers to build wizards, and have the control automatically look after all the requirements other than the actual UI of each step. In other words, the Wizard control looks after things like maintaining values between postbacks, handling navigation, and so on.

• Provide both linear (step 1, step 2, step 3, and the reverse) and nonlinear (from any step to any step) navigation. This allows a user to change his or her mind about the values in one step without having to go back through every step. It also allows navigation paths to be changed at runtime in response to selections made by the user .

• Provide opportunities to build the UI using styles, templates, and themes. Some parts of the UI that are auto-generated (such as the Previous, Next , and Finish buttons ) can instead be overridden using templates in the same way as is possible in controls like the DataGrid .

• Provide support for User Controls, allowing reuse of certain UI and code sections throughout an application.

• Ensure that you don't have to create a page per step and create complex code to pass data or controls between those pages.

The Wizard control uses postbacks to the same page and does not support cross-page posting. The advantage is that all the controls, whether visible in the current step or not, are still part of the control tree of the page, have their values maintained through the ViewState , and are available to code in the page.

From all this you will gather that the Wizard control is quite complex and exposes a great many properties and methods , plus some useful events. In this book we only have room for a description of the more useful basic properties; however, this will be enough for you to get started using the control. You can get a good idea of what the Wizard control provides by simply dragging one onto a page in Visual Studio .NET "Whidbey" (see Figure 9.2).

Figure 9.2. The Wizard control design view

The Basic Structure of a Wizard

The following code shows the declaration of a very basic wizard. The Wizard control shown takes an attribute, sideBarEnabled , that determines whether or not the navigation links between steps are shown at the side of the page. Within the Wizard control element declaration is a WizardSteps element, and this in turn contains one or more WizardStep elements. Each Wizard Step element defines one step, or one "screen" that will appear in the Wizard (see Listing 9.3).

Listing 9.3 Using the Wizard Control

 <asp:Wizard id="Wizard1" runat="server"     sideBarEnabled="True" >   <WizardSteps>     <asp:WizardStep id="WizardStep1" Title="Step 1">       Step 1 Content     </asp:WizardStep>     <asp:WizardStep id="WizardStep2" Title="Step 2">       Step 2 Content     </asp:WizardStep>   </WizardSteps> </asp:Wizard> 

Notice that there are no navigation instructions and no declarations of buttons or links. However, this code produces a fully functional (if not very useful) wizard, as shown in Figure 9.3.

Figure 9.3. The Wizard control in action

Each step is shown as a link in the left-hand side, and the appropriate Next, Previous, and Finish buttons appear in the right-hand side for each step.

Specifying the Wizard Step Types

Each step (i.e., each WizardStep control) is automatically assigned a value from the WizardStepType enumeration for its StepType property. By default the value is Auto , and the order of the steps is determined by the order they are declared within the Wizard control.

However, you can assign specific values to the StepType property to change the default behavior. The first step should be StepType="Start" (which has only a Next button) and the last should be StepType="Finish" (which has Previous and Finish buttons). The intervening steps should be StepType="Step" (which has Previous and Next buttons). One exception is if you want a final "confirmation" page that contains no navigation features to appear as the last step. In this case, assign one of the steps the value StepType="Complete" , as shown below:

 <asp:WizardStep id="Done"  StepType="Complete"  >   Congratulations! The process is complete and your   new software will now work faultlessly forever. </asp:WizardStep> 

Using Styles and Templates in a Wizard

While the basic Wizard control output is extremely plain and functional, it's possible to improve the appearance using styles or themes, or you can even replace the UI by defining templates. The three style properties of the Wizard control are NavigationButtonStyle , SideBarButtonStyle , and TitleStyle . Meanwhile, the templates you can define are listed below.

• HeaderTemplate specifies the UI content, controls, and styles for the section at the top of each step, which is the same for every step.

• SideBarTemplate specifies the UI content, controls, and styles for the left-hand list of steps.

• StartNavigationTemplate specifies the UI content, controls, and styles for the bottom section of the first step (the one with StepType="Start" or the first step in the declaration of the control).

• StepNavigationTemplate specifies the UI content, controls, and styles for the bottom section of the intermediate steps (the ones with StepType="Step" or the steps other than the first and last ones in the declaration of the control).

• FinishNavigationTemplate specifies the UI content, controls, and styles for the bottom section of the final step (the one with StepType="Finish" or the last step in the declaration of the control).

Listing 9.4 shows in outline how these templates are used.

Listing 9.4 Customizing the Wizard Control

 <asp:Wizard id="Wizard1" runat="server">   <HeaderTemplate>     ... content for header goes here ...   </HeaderTemplate>   <SideBarTemplate>     <asp:ImageButton OnClick="Wizard_Step" runat="server" />   </SideBarTemplate>   <StartNavigationTemplate>     <asp:ImageButton OnClick="Wizard_Next" runat="server" />   </StartNavigationTemplate>   <StepNavigationTemplate>     <asp:ImageButton OnClick="Wizard_Previous" runat="server" />     <asp:ImageButton OnClick="Wizard_Next" runat="server" />   </StepNavigationTemplate>   <FinishNavigationTemplate>     <asp:ImageButton OnClick="Wizard_Previous" runat="server" />     <asp:ImageButton OnClick="Wizard_Finish" runat="server" />   </FinishNavigationTemplate>   <WizardSteps>     <asp:WizardStep id="Step1">       ... visual content and controls go here ...     </asp:WizardStep>     ... more WizardStep declarations go here ...   </WizardSteps > </asp:Wizard> 

To change the text displayed on the buttons, set the NextStepButton Text , PreviousStepButtonText , and FinishStepButtonText properties to the text you want to display. You can even replace the Next, Previous, and Finish buttons with LinkButton controls ( hyperlinks ) by setting the UseLinkButton property of the Wizard to True :

 <asp:Wizard id="Wizard1" runat="server"  NextStepButtonText="Forward" PreviousStepButtonText="Back"   FinishStepButtonText="Done" UseLinkButtons="True"  > 

Navigation Methods and Events in a Wizard

The Wizard control also exposes properties, methods, and events that you can use to change the default navigation path through the steps or react to events as the user interacts with the control. The events are shown in Table 9.2.

Table 9.2. Wizard Control Events

Event	Description
ActiveViewChanged	Raised when the user moves from one step to another.
NextButtonClick	Raised when the user clicks the Next button or link.
SideBarButtonClick	Raised when the user clicks one of the buttons or links on the sidebar.
PreviousButtonClick	Raised when the user clicks the Previous button or link.
FinishButtonClick	Raised when the user clicks the Finish button or link.

This allows you to intercept the postback event for the navigation. For example, to have an event procedure run when the Finish step is reached, you would declare the Wizard this way:

 <asp:Wizard id="Wizard1" runat="server"     onFinishButtonClick="Wizard_Finish"> 

The event procedure would then be declared as shown below:

 Sub Wizard_Finish(Sender As Object, E As WizardNavigationEventArgs)   ' code here to carry out the actions selected in the Wizard   ' all values in all controls in all steps are available End Sub 

WizardNavigationEventArgs has the properties shown in Table 9.3.

Table 9.3. Properties of WizardNavigationEventArgs

Property	Description
Cancel	Determines whether to cancel the event. If set to True in the event procedure, the event is canceled .
CurrentStepIndex	Sets the index number of the current step.
NextStepIndex	Sets the index number of the next step.

Note there is no concept of a previous step as you are either moving forward or backward by way of the Next and Previous buttons. The NextStep Index therefore indicates the index number irrespective of direction. Thus for consecutively numbered steps, moving backward from Step 2 to Step 1 would leave NextStepIndex as 1 .

And, at any stage, you can access the individual steps and the content of each one through the WizardSteps property:

 Dim steps As WizardStepCollection steps = MyWizard.WizardSteps 

Other useful properties, methods, and events exposed by the Wizard control are the following:

• ActiveStep , which returns the currently displayed step in the Wizard as a WizardStep object

• ActiveStepIndex , which returns the Integer index of the currently displayed step within the WizardSteps collection or specifies the index of the step that will be displayed

• MoveTo( WizardStep ) , which moves to the selected WizardStep

• GetHistory() , which returns an ArrayList of WizardStep items containing the steps the user has taken