Section 5.2. Wizard Control
Users expect modern applications to provide wizards to walk them through multi-step processes. These UIs are distinguished by the use of magic. Sorry, just kidding.
Wizards provide the infrastructure to present the user with successive steps in a process, providing access to all the data collected in all the steps, with easy forward and backward navigation.
Similar to the MultiView control, the Wizard control contains a collection of WizardStep objects. These WizardSteps derive from the View class as can be seen in Figure 5-3, and the relationship between WizardSteps and the Wizard control is analogous to the relation between the View and MultiView .
Figure 5-3. View class hierarchy
As with the MultiView control, all the controls on all the WizardSteps are part of the page's control hierarchy and are accessible via code at runtime regardless of which specific WizardStep is currently visible. Every time a user clicks on a navigation button or link, the page posts back to the server. Cross-page posting, described in Chapter 6, is not supported.
The Wizard control takes care of all the plumbing required to implement navigation, both linear (going from one step to the next or back) and non-linear (going from any step to any other step). It automatically creates the appropriate buttons , such as Next, Previous, and Finish (on the very last step). The first step does not have a Previous button, and the last step does not have a Next button. It also makes provisions for steps that can only be navigated to a single time. In addition, by default, the Wizard displays a toolbar with navigation links, enabling the user to go to any step from any other step.
Almost every aspect of the look and feel of the Wizard can be customized with styles and templates. This includes all the various buttons and links, the header and footer, the sidebar, and the WizardSteps .
The best way to explore the Wizard control is to look at an example. In this example, you will create a whimsical wizard to guide you through the steps you follow when waking up in the morning.
Create a new web site called WizardDemo . Drag a Wizard control onto the page. It creates a default two-step wizard, which, though sparse, is fully functional. In Design view, you will see the two sidebar links, the first step, and the Next button, as shown in Figure 5-4.
Figure 5-4. The Wizard control in Design view
Looking at the Source view of the content page, you will see that the Wizard declaration looks something like the following:
<asp:Wizard ID="Wizard1" runat="server"> <WizardSteps> <asp:WizardStep ID="WizardStep1" runat="server" Title="Step 1"> </asp:WizardStep> <asp:WizardStep ID="WizardStep2" runat="server" Title="Step 2"> </asp:WizardStep> </WizardSteps> </asp:Wizard>
Within the <asp:Wizard> tags are a pair of <WizardSteps> tags. The WizardStep controls are declared within those tags.
If you run this page, you will see the web page shown in Figure 5-5. Since this is the first step, only the Next button is displayed, but the sidebar shows links for both steps.
Figure 5-5. Default Wizard control
Now let's spiff this example up a bit. Click on the content area of the WizardStep and type in some text, for example, an <h2> heading that says "Wake Up," as shown in Figure 5-6.
Figure 5-6. Adding content to a Wizard step
Next, click the smart tag of the Wizard control and select Add/Remove WizardSteps . This will bring up the WizardStep Collection Editor, as shown in Figure 5-7. Add five more steps so there are a total of seven. For each (including the first two), enter a value for the Title and for the ID , as listed in Table 5-2.
Table 5-2. WizardSteps for WizardDemo
| ID | Title |
|---|---|
| stpWakeUp | Step 1 |
| stpShower | Step 2 |
| stpTakeMeds | Step 3 |
| stpBrushTeeth | Step 4 |
| stpGetDressed | Step 5 |
| stpEatBreakfast | Step 6 |
| stpFinish | Step 7 |
Figure 5-7. WizardStep Collection Editor
Though you can click on the smart tag, select each step in turn and add content to each step as you did above with Step 1; it is easier to switch to Source view and edit the WizardStep declarations directly. When you are done, the Wizard control declaration should look something like that shown in Example 5-6.
Example 5-6. Wizard declaration after adding steps
<asp:Wizard ID="wzrdMorning" runat="server"> <WizardSteps> <asp:WizardStep ID="stpWakeUp" runat="server" Title="Step 1"> <h2>Wake Up</h2> </asp:WizardStep> <asp:WizardStep ID="stpShower" runat="server" Title="Step 2"> <h2>Shower</h2> </asp:WizardStep> <asp:WizardStep ID="stpTakeMeds" runat="server" Title="Step 3"> <h2>Take Medicine</h2> </asp:WizardStep> <asp:WizardStep ID="stpBrushTeeth" runat="server" Title="Step 4"> <h2>Brush Teeth</h2> </asp:WizardStep> <asp:WizardStep ID="stpGetDressed" runat="server" Title="Step 5"> <h2>Get Dressed</h2> </asp:WizardStep> <asp:WizardStep ID="stpEatBreakfast" runat="server" Title="Step 6"> <h2>Eat Breakfast</h2> </asp:WizardStep> <asp:WizardStep ID="stpFinish" runat="server" Title="Step 7"> <h2>Out the Door</h2> </asp:WizardStep> </WizardSteps> </asp:Wizard>
The Wizard control has many properties for controlling appearance and behavior. Table 5-3 lists some of the most important Wizard properties other than those relating to the appearance of the buttons. The button- related properties are listed in Table 5-4. You'll see many of these properties as you continue with this example, WizardDemo .
Table 5-3. Wizard Properties not related to style or button display
| Name | Type | Get | Set | Description |
|---|---|---|---|---|
| ActiveStep | WizardStepBase | | The currently displayed step in the WizardsSteps collection. | |
| ActiveStepIndex | Integer | | | The zero-based index of the currently displayed step in the WizardsSteps collection. |
| CancelDestinationPageUrl | String | | | The URL the user navigates to when clicking the Cancel button. |
| CellPadding | Integer | | | Number of pixels between the cell 's contents and border. Defaults to 0. |
| CellSpacing | Integer | | | Number of pixels betweens cells . The default is 0. |
| DisplayCancelButton | Boolean | | | If true , a Cancel button will be displayed. Default is false . |
| DisplaySideBar | Boolean | | | If true , the default, the sidebar area will be displayed. |
| FinishDestinationPageUrl | String | | | The URL the user navigates to when clicking the Finish button. |
| FinishNavigationTemplate | ITemplate | | | The template used to specify content and styles for the navigation area of the Finish step, either the last step or the step with StepType = Finish . |
| HeaderStyle | TableItemStyle | | Style properties for the header area. | |
| HeaderTemplate | ITemplate | | | The template used to specify content and styles for the header area displayed at the top of every step. |
| HeaderText | string | | | Text displayed in the header area. |
| NavigationButtonStyle | Style | | The style properties that specify the appearance of the buttons in the navigation area. | |
| NavigationStyle | TableItemStyle | | Style properties for the navigation area. | |
| SideBarButtonStyle | Style | | The style properties that specify the appearance of the buttons in the sidebar area. | |
| SideBarStyle | TableItemStyle | | Style properties for the sidebar area. | |
| SideBarTemplate | ITemplate | | | The template used to specify content and styles for the sidebar area. |
| SkipLinkText | string | | | Rendered as alternate text with an invisible image to work with assistive technologies. Default is "Skip Navigation Links", localized for server locale. |
| StartNavigationTemplate | ITemplate | | | The template used to specify content and styles for the navigation area of the Start step, either the first step or the step with StepType = Start . |
| StepNavigationTemplate | ITemplate | | | The template used to specify content and styles for the navigation area of all the steps other than Start, Finish, or Complete. |
| StepStyle | TableItemStyle | | Style properties for the WizardStep objects. | |
| WizardSteps | WizardStepCollection | | Collection of WizardStep objects. |
Table 5-4. Wizard Properties related to button displays
| Property | Type | Get | Set | Values | Description |
|---|---|---|---|---|---|
| CancelButtonImageUrl FinishStepButtonImageUrl FinishStepPreviousButtonImageUrl NextStepButtonImageUrl PreviousStepButtonImageUrl StartStepNextButtonImageUrl | string | | | The URL of the image displayed for the button. | |
| CancelButtonStyle FinishStepButtonStyle FinishStepPreviousButtonStyle NextStepButtonStyle PreviousStepButtonStyle StartStepNextButtonStyle | Style | | The style properties that specify the appearance of the button. | ||
| CancelButtonText FinishStepButtonText FinishStepPreviousButtonText NextStepButtonText PreviousStepButtonText StartStepNextButtonText | string | | | The text displayed on the button. | |
| CancelButtonType FinishStepButtonType FinishStepPreviousButtonType NextStepButtonType PreviousStepButtonType StartStepNextButtonType | ButtonType | | | Button , Image , Link | The type of button rendered as the button. |
Many of the properties are of type TableItemStyle . This class, which derives from System.Web.UI.WebControls.Style , contains properties used to format the table rows and cells that make up the Wizard control. The TableItemStyle class has many properties, including BackColor , BorderColor , BorderStyle , BorderWidth , CssClass , Font , ForeColor , Height , HorizonalAlign , VerticalAlign , Width , and Wrap .
When setting the properties of a Wizard control in VS2005 in Design view, the properties that are of type TableItemStyle appear in the Properties window with a plus sign next to them. Clicking on the plus sign expands the list to display the TableItemStyle properties as subproperties , as seen in Figure 5-8. Properties set in this manner will be contained in separate elements within the Wizard control declaration in the content file, as in the highlighted code in the following snippet:
<asp:Wizard ID="Wizard1" runat="server" ActiveStepIndex="0"> <WizardSteps> <asp:WizardStep ID="stpWakeUp" runat="server" Title="Step 1"> <h2> Wake Up</h2> </asp:WizardStep> <asp:WizardStep ID="WizardStep2" runat="server" Title="Step 2"> </asp:WizardStep> </WizardSteps> <HeaderStyle BackColor="Gray" BorderColor="Black" BorderStyle="Solid" BorderWidth="2px" Font-Size="0.9em" ForeColor="White" HorizontalAlign="Center" /> </asp:Wizard> Figure 5-8. TableItemStyle type properties in Design view
When working in Source view, however, the TableItemStyle type properties are listed and inserted directly into the Wizard control declaration in the format shown in Figure 5-9 and shown in the highlighted code in the snippet below:
<asp:Wizard ID="Wizard1" runat="server" ActiveStepIndex="0" SideBarStyle-BackColor="Yellow" SideBarStyle-BorderStyle="Dashed" SideBarStyle-Font-Bold="true" SideBarStyle-ForeColor="Black"> <WizardSteps> <asp:WizardStep ID="stpWakeUp" runat="server" Title="Step 1"> <h2> Wake Up</h2> </asp:WizardStep> <asp:WizardStep ID="WizardStep2" runat="server" Title="Step 2"> </asp:WizardStep> </WizardSteps> </asp:Wizard> The WizardStep has a StepType property, which has one of the values of the WizardStepType enumeration listed in Table 5-5. By default, the StepType is Auto , in which the navigation UI is determined by the order of the steps in the WizardSteps collection. The first step has only a Next button, the last step has only a Previous button, and all the other steps of StepType Auto have both Previous and Next buttons.
Alternatively, you can assign a different value to the StepType property to modify the default behavior, as described in Table 5-5. For example, you can create a confirmation page, with no navigation buttons at all, by changing the StepType to Complete .
Figure 5-9. TableItemStyle type properties in Source view
Table 5-5. WizardStepType enumeration members
| Member | Description |
|---|---|
| Auto | Navigation UI determined automatically by the order in which the step is declared. The default value. |
| Complete | The last step to display. No navigation buttons rendered. |
| Finish | The final data collection step. Renders only Finish and Previous buttons. |
| Start | The first step. Renders only a Next button. |
| Step | Any step other than Start, Finish, or Complete. Renders Previous and Next buttons. |
The WizardStep class has one additional property of particular interest: AllowReturn . This property enforces linear navigation. It is impossible to navigate to a step with AllowReturn set to false more than once. If the DisplaySideBar property is true (the default) so the sidebar is displayed, then any step with AllowReturn set to false will still display in the navigation links, but clicking on that link will have no effect.
|
The Wizard control has six events, listed in Table 5-6. One is the ActiveStepChanged event, raised when the current step is changed. The other five events are all raised in response to button clicks. As noted in Table 5-6, all the button click events other than CancelButtonClick have an event argument of type WizardNavigationEventArgs , which exposes three properties:
-
Cancel
-
Boolean value is TRue if the navigation to the next step should be canceled . The default is false .
-
CurrentStepIndex
-
The zero-based integer index of the current step in the WizardSteps collection.
-
NextStepIndex
-
The zero-based integer index of the step that will display next. If the Previous button has been clicked, for example, the value of NextStepIndex will be one less than the CurrentStepIndex .
Table 5-6. Wizard events
| Event | Event Argument | Description |
|---|---|---|
| ActiveStepChanged | EventArgs | Raised when a new step is displayed. |
| CancelButtonClick | EventArgs | Raised when the Cancel button is clicked. |
| FinishButtonClick | WizardNavigationEventArgs | Raised when the Finish button is clicked. |
| NextButtonClick | WizardNavigationEventArgs | Raised when the Next button is clicked. |
| PreviousButtonClick | WizardNavigationEventArgs | Raised when the Previous button is clicked. |
| SideBarButtonClick | WizardNavigationEventArgs | Raised when a sidebar button is clicked. |
The Wizard control has three methods of particular interest, listed in Table 5-7.
Table 5-7. Wizard methods
| Method Name | Return Type | Description |
|---|---|---|
| GetHistory | ICollection | Returns a collection of WizardStepBase objects in the order they were accessed, where index 0 is the most recent step. |
| GetStepType | WizardStepType | The type of step, as listed in Table 5-5. |
| MoveTo | void | Moves to the WizardStep object passed in as a parameter. |
Now, let's return to the WizardDemo example, where you will apply many of the properties, methods, and events that we just listed and discussed.
First, add a bit of text to each of the WizardSteps . The content of each step can include text and HTML, other ASP.NET server controls, and user controls, enabling the easy reuse of UI and code.
Next, set the StepType of the first step to Start and Step 7 to Finish . Set the AllowReturn property of Step 3 to False , so you can only access that step a single time. Finally, add one additional WizardStep to the WizardSteps collection, with a StepType of Complete . The new <WizardSteps> section of the Wizard declaration will now look like Example 5-7, with the modified code highlighted (except for the added text content).
Example 5-7. WizardSteps declaration
<WizardSteps> <asp:WizardStep ID="stpWakeUp" runat="server" Title="Step 1" StepType="Start"> <h2>Wake Up</h2> Rise and shine sleepy head. </asp:WizardStep> <asp:WizardStep ID="stpShower" runat="server" Title="Step 2"> <h2>Shower</h2> Make it cold! </asp:WizardStep> <asp:WizardStep ID="stpTakeMeds" runat="server" Title="Step 3" AllowReturn="False"> <h2>Take Medicine</h2> Only do this once. </asp:WizardStep> <asp:WizardStep ID="stpBrushTeeth" runat="server" Title="Step 4"> <h2>Brush Teeth</h2> Don't forget to floss. </asp:WizardStep> <asp:WizardStep ID="stpGetDressed" runat="server" Title="Step 5"> <h2>Get Dressed</h2> Got to look good. </asp:WizardStep> <asp:WizardStep ID="stpEatBreakfast" runat="server" Title="Step 6"> <h2>Eat Breakfast</h2> The most important meal of the day. </asp:WizardStep> <asp:WizardStep ID="stpFinish" runat="server" Title="Step 7" StepType="Finish"> <h2>Out the Door</h2> Meet the world! </asp:WizardStep> <asp:WizardStep ID="stpComplete" runat="server" StepType="Complete" Title="Complete"> <h2>Complete!</h2> Your morning routine is now complete. </asp:WizardStep> </WizardSteps>
Next, add a drop-down along with several labels to the page. The labels will be used to display various information and the drop-down will be used to demonstrate how step navigation can occur programmatically outside the Wizard control. The code snippet from the content file shown in Example 5-8 declares these additional controls.
Example 5-8. Additional controls in WizardDemo
<br /> Select a step: <asp:DropDownList ID="DropDownList1" runat="server" AutoPostBack="True" OnSelectedIndexChanged="DropDownList1_SelectedIndexChanged" > <asp:ListItem>1</asp:ListItem> <asp:ListItem>2</asp:ListItem> <asp:ListItem>3</asp:ListItem> <asp:ListItem>4</asp:ListItem> <asp:ListItem>5</asp:ListItem> <asp:ListItem>6</asp:ListItem> <asp:ListItem>7</asp:ListItem> </asp:DropDownList> <br /> <br /> Active Step: <asp:Label ID="lblActiveStep" runat="server" /> <br /> ActiveStepIndex: <asp:Label ID="lblActiveStepIndex" runat="server" /> <br /> StepType: <asp:Label ID="lblStepType" runat="server" /> <br /> Button Info: <asp:Label ID="lblButtonInfo" runat="server" /> <br /> <br /> <u>History</u> <br /> <asp:Label ID="lblHistory" runat="server" />
Go back to the Design view, click the smart tag of the Wizard control and select Auto Format. Select one of the format schemes presented; in this example, we use Simple. This will automatically apply a number of formatting properties, as you will see momentarily.
In the Properties window for the Wizard control, set the DisplayCancelButton to true .
While in Design view with the Wizard control selected, click the Events icon (the lightning bolt) in the Properties window. Double-click the cell next to ActiveStepChanged to insert an event handler with the default name ( wzrdMorning_ActiveStepChanged ) for that event. Do the same for the CancelButtonClick event. For the FinishButtonClick event, enter the name Button_Click , which will insert a skeleton event handler with that name in the code-behind file. Finally, enter Button_Click for each of the NextButtonClick , PreviousButtonClick , and SideBarButtonClick events.
Switch over to the code-behind file, Default.aspx.cs . Add the following using statement to the top of the file:
using System.Collections;
This is necessary so you can use the ICollection object returned by the GetHistory method of the Wizard control without typing in full namespace qualification.
Add the highlighted code from Example 5-9 to all the event handler code skeletons already inserted by VS2005.
Example 5-9. Event handlers in Default.aspx.cs for WizardDemo
protected void wzrdMorning_ActiveStepChanged(object sender, EventArgs e) { lblActiveStep.Text = wzrdMorning.ActiveStep.Title; lblActiveStepIndex.Text = wzrdMorning.ActiveStepIndex.ToString(); lblStepType.Text = wzrdMorning.ActiveStep.StepType.ToString(); // get the history ICollection steps = wzrdMorning.GetHistory(); string str = ""; foreach(WizardStep step in steps) { str += step.Title + "<br/>"; } lblHistory.Text = str; } protected void Button_Click(object sender, WizardNavigationEventArgs e) { string str = "Current Index: " + e.CurrentStepIndex.ToString() + ". Next Step: " + e.NextStepIndex.ToString(); lblButtonInfo.Text = str; } protected void wzrdMorning_CancelButtonClick(object sender, EventArgs e) { lblActiveStep.Text = ""; lblActiveStepIndex.Text = ""; lblStepType.Text = ""; lblButtonInfo.Text = "Canceled"; wzrdMorning.Visible = false; } protected void DropDownList1_SelectedIndexChanged(object sender, EventArgs e) { DropDownList ddl = (DropDownList)sender; int index = ddl.SelectedIndex; WizardStepBase step = wzrdMorning.WizardSteps[index]; wzrdMorning.MoveTo(step); } The ActiveStepChanged event handler, wzrdMorning_ActiveStepChanged , is fired every time the current step changes, whether through user interaction or programmatically. This method gathers three pieces of information, populates the labels, and displays a history of the steps accessed.
The first label displays the currently active step. The ActiveStep property of the Wizard control returns a WizardStep object. The Title property of that object gives you the information you want. The second label is filled with the ActiveStepIndex property value. Since it is of type integer, it must be converted to a string. The third label displays the StepType property of the WizardStep class, which is of type WizardStepType and, therefore, must be converted to a string for assignment to the Text property of the TextBox .
Second, the wzrdMorning_ActiveStepChanged method calls the GetHistory method of the Wizard class, which returns a collection of WizardStep objects ( strictly speaking it returns a collection of WizardStepBase objects, from which WizardStep derives). The collection is iterated and the Title property of each step is appended to a text string which is then assigned to the lblHistory label. The most recent step accessed has an index of 0, the subsequent step has an index of 1, and so on.
All the buttons and links, other than the Cancel button, use the same event handler method: Button_Click . This method fills lblButtonInfo with the current step index and the next step index, both of which are properties of the event argument.
The Cancel button click event handler, wzrdMorning_CancelButtonClick , clears all the labels and hides the Wizard control.
The DropDownList on this page lets the user move to any of the wizardsteps . It casts the sender object to type DropDownList , then extracts the SelectedIndex property. This value is used as an index into the WizardSteps collection to get a reference to the desired WizardStep object (actually a WizardStepBase object, from which WizardStep is derived). Then the MoveTo method of the Wizard is called to move programmatically to that step. The really interesting thing here is that it is possible to move multiple times to a step, such as Step 3, which has the AllowReturn property set to false .
As a result of setting the event handlers and the Auto Formatting, the Wizard declaration will now look something like that shown in Example 5-10.
Example 5-10. Wizard declaration after adding event handlers and formatting
<asp:Wizard ID="wzrdMorning" runat="server" DisplayCancelButton="True" OnCancelButtonClick="wzrdMorning_CancelButtonClick" OnActiveStepChanged="wzrdMorning_ActiveStepChanged" OnFinishButtonClick="Button_Click" OnNextButtonClick="Button_Click" OnPreviousButtonClick="Button_Click" OnSideBarButtonClick="Button_Click" BackColor="#E6E2D8" BorderColor="#999999" BorderWidth="1px" Font-Names="Verdana" Font-Size="0.8em" > <WizardSteps> <!-- unchanged from Example 5-7 -- > </WizardSteps> <StepStyle BackColor="#F7F6F3" BorderColor="#E6E2D8" BorderStyle="Solid" BorderWidth="2px" /> <SideBarStyle BackColor="#1C5E55" Font-Size="0.9em" VerticalAlign="Top" /> <NavigationButtonStyle BackColor="White" BorderColor="#C5BBAF" BorderStyle="Solid" BorderWidth="1px" Font-Names="Verdana" Font-Size="0.8em" ForeColor="#1C5E55" /> <SideBarButtonStyle ForeColor="White" /> <HeaderStyle BackColor="#666666" BorderColor="#E6E2D8" BorderStyle="Solid" BorderWidth="2px" Font-Bold="True" Font-Size="0.9em" ForeColor="White" HorizontalAlign="Center" /> </asp:Wizard>
Running the web page and navigating through several of the steps will yield something similar to Figure 5-10.
Figure 5-10. WizardDemo after some navigation
The Wizard control is a fairly well-defined control, with obvious uses. You could walk your user through entering their preferences or setting up a stock sale. Any time you want a clearly defined series of steps for the user to follow, the Wizard control is useful.
EAN: 2147483647
Pages: 173