About the MultiPage WebControl

Article
10/23/2013

The MultiPage control enables the definition of collections of PageView elements. Like the other Windows Internet Explorer WebControls, the MultiPage generates Web pages that are tailored for both downlevel and uplevel browsers. (With WebControls, an uplevel browser is Microsoft Internet Explorer 5.5 or later and a downlevel browser is Internet Explorer 5.01 or earlier or a browser other than Internet Explorer.) The MultiPage can be authored declaratively and also exposes both a client-side and server-side scripting object model.

MultiPage and the TabStrip controls can be synchronized easily, so that updates to the selected Tab in a TabStrip menu automatically trigger an update to the currently selected PageView element. Using both the MultiPage and the TabStrip controls together enables content to be presented and paged without requiring actual navigation to another URL. For more information on using these controls together, see Using the MultiPage with the TabStrip WebControl.

This document includes the following sections.

Authoring with the MultiPage Control
MultiPage Objects
- MultiPage Behavior
- MultiPage ASP.NET Objects
Writing a Simple MultiPage
Scripting Web Forms with the MultiPage
Adding PageView Controls Dynamically
Using the MultiPage with the TabStrip WebControl
Related Topics

Authoring with the MultiPage Control

In ASP.NET any HTML element in a Web page can be marked as a server control. When an element is marked as a server control, ASP.NET processes the control on the Web server and generates output that is tailored to render correctly in the specific client browser. In the case of the WebControls, the Web pages sent to Internet Explorer 5.5 include Dynamic HTML (DHTML) behaviors and use several advanced browser features.

The MultiPage supports two distinct modes of authoring. MultiPage interfaces can be implemented in ASP.NET Web Forms, using elements and objects exposed by the MultiPage server-side controls, and MultiPage interfaces can also be written in HTML pages using the MultiPage behavior. In either case, the same set of elements can be authored in the Web page, but due to differences in the component architecture in ASP.NET and Internet Explorer 5.5, the client and server object models are slightly different.

In general, when the client browser is not known, it is recommended that you author ASP.NET Web Forms using the MultiPagecontrols. Using this approach ensures that the content will render correctly in most commonly used browsers; this is because the ASP.NET controls detect the browser type. The content downloaded from ASP.NET in Internet Explorer 5.5 automatically includes the MultiPage behavior.

When authoring content specifically for Internet Explorer 5.5 or later versions, it is recommended that you write Web pages that use client-side script in conjunction with the MultiPage behavior. This approach results in slightly faster downloads because server-side processing is avoided. Also, Web pages that use the MultiPage behavior provide a better user experience because round trips to the Web server are unnecessary.

MultiPage Objects

The MultiPage control is authored by using a combination of one or more of the following elements.

Element name	Description
MultiPage	Defines a container for PageView elements.
PageView	Creates a PageView within the MultiPage.

For links to the complete set of reference documentation for the client-side and server-side objects implemented by the MultiPage control, see MultiPage Reference. The reference documentation is organized into client- and server-side object pages. The client objects are exposed by the MultiPage behavior, and the ASP.NET objects pages are presented separately.

The next two sections explain the main differences between the client- and server-side objects exposed by the MultiPage.

MultiPage Behavior

The component object model in Internet Explorer 5.5 or later versions enables custom XML elements to be defined. These custom elements are called element behaviors. An element behavior can be defined using a HTML Component (HTC) file containing script that defines the behavior of the custom element.

When defining an element behavior, the script component can only define the behavior of a single element. However, as already shown in the previous section, a MultiPage UI is implemented using two different elements: the MultiPage and the PageView. Therefore, because the implementation of the MultiPage behavior uses a single HTC file, the child elements of the MultiPage are actually parsed as literal content.

In the implementation of the MultiPage behavior, the script in the HTC file parses the PageView elements, which are children of the MultiPage element, and generates the appropriate UI with DHTML. This approach enables different element types to be authored and scripted using a single element behavior.

The objects exposed by the MultiPage behavior can be scripted using either Microsoft JScript or Microsoft Visual Basic Scripting Edition (VBScript).

MultiPage ASP.NET Objects

In contrast to DHTML behaviors, ASP.NET controls can implement as many custom elements as are needed in a single assembly. And, in the case of the WebControls, all of the ASP.NET elements are implemented by an assembly named Microsoft.Web.UI.WebControls.dll, the filename of this assembly is the same as the namespace used by these controls. Therefore, the component architecture on the ASP.NET platform requires no use of literal content elements. Any of the common language runtime languages can be used in an ASP.NET Web Form to control the MultiPage objects.

Writing a Simple MultiPage

This section walks through the steps to create a simple MultiPage. You can perform all the steps using any text editor.

If you do not have WebControls installed on your computer, see the Internet Explorer WebControls Download page for installation instructions.
Create a Web application using Microsoft Visual Studio.

The Web application should be named webcontrols and can be used for all the samples in this article.

Note You can also use an existing Web application, but the Web must be configured as a Web application in order for the WebControls to run properly.
Create an empty Web Form page.

Add a new file to the Web and save it as multipage1.aspx.
Add the import directive.

Code the import directive for the WebControls on the first line of the Web Form. It should look like the following:
```
<%@ import namespace="Microsoft.Web.UI.WebControls" %>
```
Note In this example, the @ Import directive is optional. This directive is only required when writing Web Forms that use server-side script to create or modify WebControls objects.

Add the @ Register directive.

Code the @ Register directive for the WebControls on the second line of the Web Form.

<%@ Register TagPrefix="mymultipage" 
Namespace="Microsoft.Web.UI.WebControls" 
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>

Add the document structure.

Add the following content below the @ Register directive to provide a basic document structure.
```
<HTML>
<HEAD></HEAD>
<BODY></BODY>
</HTML>
```
Add a Form element.

All WebControls elements must be authored inside a FORM element; therefore, add the following markup inside the document BODY.
```
<BODY>
<FORM runat="server"></FORM>
</BODY>
```
Note that the runat attribute is specified for the FORM, indicating that ASP.NET is to process the results of any user input.

At this point, the Web Form includes all the processing directives, elements, and content that are required to begin authoring with the WebControls elements. The contents of the multipage1.aspx file should now look similar to the following:
```
<%@ import namespace="Microsoft.Web.UI.WebControls" %>
<%@ Register TagPrefix="mymultipage" 
Namespace="Microsoft.Web.UI.WebControls" 
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
<HEAD></HEAD>
<BODY>
  <FORM runat="server"></FORM>
</BODY>
```
Save the page and view it in your browser. If everything is correct, you should only see an empty page. The page is compiled before it is viewed, and any errors in the syntax will be raised. If you see an error at this point, correct the reported error. If the sample code provided above doesn't work, it is possible that the WebControls have not been installed correctly.

Tip For the adventurous reader: Try misspelling the value of the namespace or the assembly attributes in the declarations; save and view the page again. This is a useful exercise, because you can see how the common language runtime reports errors for Web Forms.
Add a MultiPage element.

Add a MultiPage element as a child element of the FORM and set its runat attribute to server.
```
<BODY>
  <FORM runat="server">
    <mymultipage:multipage runat="server"></mymultipage:multipage>
  </FORM>
</BODY>
```
At this point, the MultiPage element doesn't contain any content, so nothing renders in the Web page.

Note In tag prefix for the MultiPage element, the value mymultipage is used for all WebControls elements in the page because it has been predefined in the @ Register directive.
Add PageView elements to the MultiPage.

Next, add two PageView as child elements of the MultiPage element.
```
<mymultipage:multipage runat="server" selectedindex="1">
  <mymultipage:pageview><p>This is page number one</p></mymultipage:pageview>
  <mymultipage:pageview><p>This is page number two, and this page view
  is selected!</p></mymultipage:pageview>
</mymultipage:multipage>
```
Save the page and reload it in your browser. The HTML in the second PageView element should be rendered because the SelectedIndex attribute has been used on the MultiPage element.

The indices are zero-based; therefore, setting SelectedIndex to 1 selects the second PageView for the initial rendering of the page.

This concludes the basic MultiPage sample. Further examples follow to illustrate additional properties and features of the MultiPage.

Scripting Web Forms with the MultiPage

This section illustrates how to control the MultiPage and PageView controls with script. The code sample illustrates how a few simple scripting methods can be used to create a simple wizard for a shopping cart application.

The wizard prompts the user for information, which, in a real application, could be used to process an online purchase. In this example, an entirely fictitious Sky Hook is offered for an exorbitant price. The wizard guides the user through four steps, each step presenting a small form that collects information. Therefore, the Web Form uses four PageView controls to organize the HTML for each form.

Here is the main body of the Web Form.

<body runat="server">

<h1>Sky Hooks for Sale!</h1>

<form id="theForm" runat="server">

<mywiz:MultiPage id="Wizard" runat="server" BorderWidth="1" BorderStyle="Solid" BorderColor="Gray">
<mywiz:PageView id="Cart">
<h2>Shopping Cart</h2>
<p>This is a sample checkout wizard that demonstrates the MultiPage control.</p>

<ul>
  <li>This sample not for a real application.</li>
  <li>The only thing on offer today is a Sky Hook.</li>
  <li>The shopping cart contents cannot be changed.</li>
</ul>

<p>Sky Hook (Left-hand thread)
<br>$250.00
<br>Quantity: 1
</p>
</mywiz:PageView>

<mywiz:PageView id="Shipping">
<h2>Shipping</h2>
<p>Please enter shipping information.
<table>
<tr>
<td>First Name:</td>
<td><asp:TextBox id="FirstName" runat="server" /></td>
</tr>
<tr>
<td>Last Name:</td>
<td><asp:TextBox id="LastName" runat="server" /></td>
</tr>
<tr>
<td>Address:</td>
<td><asp:TextBox id="Address" runat="server" TextMode="MultiLine" Rows="3"/></td>
</tr>
</table>

</mywiz:PageView>

<mywiz:PageView id="Billing">
<h2>Billing</h2>
<p>Please enter billing information.
<table>
<tr>
<td>Credit Card:</td>
<td><asp:TextBox id=Card runat=server /></td>
</tr>
<tr>
<td>Bill to shipping address:</td>
<td><asp:CheckBox id=BillShipping runat="server" Checked="true" /></td>
</tr>
<tr>
<td>First Name:</td>
<td><asp:TextBox id="BillFirstName" runat="server" /></td>
</tr>
<tr>
<td>Last Name:</td><td><asp:TextBox id="BillLastName" runat="server" /></td>
</tr>
<tr>
<td>Address:</td><td><asp:TextBox id="BillAddress" runat="server" TextMode="MultiLine" Rows="3"/></td>
</tr>
</table>

</mywiz:PageView>

<mywiz:PageView id="Receipt">
<h2>Receipt</h2>
<p>Sky Hook (Left-hand thread)
<br>$250.00
<br>Quantity: 1
<br>
<br>Shipping: $10.00
<br>Tax: $2.00
<br>Total: $262.00
<br>
</p>
<div id="ReceiptPane" runat="server"></div>
</mywiz:PageView>

</mywiz:MultiPage>

<asp:Button id="BackBtn" runat="server" Text="< Back" OnClick="BackClick" /> 
<asp:Button id="NextBtn" runat="server" Text="Next >" OnClick="NextClick" />

</form>
</body>

The four PageView elements provide convenient containers for each of the panels in the wizard. Note that both ASP.NET controls and HTML elements can be used in the innerHTML of the PageView control.

The SelectedIndex property is not set explicitly on the MultiPage control; therefore, when the page loads, the content of the first PageView is rendered. Two ASP.NET button controls are used to control the paging through the steps of the wizard, and these buttons invoke the BackClick and NextClick methods.

The following code shows the methods that initialize the Web Form.

<%@ Import Namespace="Microsoft.Web.UI.WebControls" %>
<%@ Register TagPrefix="mywiz" 
Namespace="Microsoft.Web.UI.WebControls" 
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
<html>
<head>

<title>Shopping Wizard</title>

<script language="C#" runat="server">

    public void Page_Load(Object sender, EventArgs e)
    {
        if (!IsPostBack)
        {
            SetupButtons();
        }
    }

    public void SetupButtons()
    {
        if (Wizard.SelectedIndex == 0)
        {
            BackBtn.Visible = false;
            NextBtn.Text = "Start > ";
        }
        else if (Wizard.SelectedIndex == 1)
        {
            BackBtn.Visible = true;
            NextBtn.Text = "Next >";
        }
        else if (Wizard.SelectedIndex == (Wizard.Controls.Count - 3))
        {
            NextBtn.Text = "Next >";
        }
        else if (Wizard.SelectedIndex == (Wizard.Controls.Count - 2))
        {
            NextBtn.Text = "Finish";
        }
        else if (Wizard.SelectedIndex == (Wizard.Controls.Count - 1))
        {
            BackBtn.Visible = false;
            NextBtn.Visible = false;
        }
    }

// Note: other methods not shown 
</script>

</head>

The Page_Load method tests the IsPostBack property. If the page is not in its initial state, the SetupButtons method is called.

The SetupButtons method checks for all possible states of the SelectedIndex property, which indicates the currently selected PageView. If the wizard is at the first PageView, then BackBtn is hidden, the other possible PageView selections are also checked, and the buttons are set to the appropriate state.

The MultiPage contains a collection of four PageView controls. In the conditional expressions, the Controls object is used to reference the current count of the collection of PageView elements.

Note The collection of PageView controls can be updated dynamically using script.

The next code snippet shows the BackClick and NextClick methods.


public void BackClick(Object sender, EventArgs e)
{
    if (Wizard.SelectedIndex > 0)
    {
        Wizard.SelectedIndex--;
        SetupButtons();
    }
}

public void NextClick(Object sender, EventArgs e)
{
    if (Wizard.SelectedIndex < (Wizard.Controls.Count - 1))
    {
        Wizard.SelectedIndex++;
        SetupButtons();

        if (Wizard.SelectedIndex == (Wizard.Controls.Count - 1))
        {
            CreateReceipt();
        }
    }
}

As shown by these methods, the currently selected PageView control, which is rendered on the page, is controlled by incrementing and decrementing the SelectedIndex property. In the NextClick method, if the final PageView has been reached, then the CreateReceipt method is called to conclude the wizard processing.


public void CreateReceipt()
{
    string html = "<p>Order Number: <b>123456</b><p>Ship to:<br>";
    html += "<pre style=\"font-size:small\">" + FirstName.Text + 
    " " + LastName.Text + "\n" + Address.Text + "</pre>";
    html += "<p>Bill to:<br>";
        
        if (BillShipping.Checked)
        {
            html += "<i>(Same as shipping)</i>";
        }
        else
        {
            html += "<pre style=\"font-size:small\">" + BillFirstName.Text 
            + " " + BillLastName.Text + "\n" + BillAddress.Text + "</pre>";
        }

    ReceiptPane.InnerHtml = html;
}

This method summarizes the information collected by the wizard in the innerHTML of the ReceiptPane object, which is a div tag on the final PageView.

Adding PageView Controls Dynamically

The following short sample illustrates how to add PageView controls to a MultiPage dynamically, using an ASP.NET script method.

<%@ Import Namespace="Microsoft.Web.UI.WebControls" %>
<%@ Register TagPrefix="myns" 
Namespace="Microsoft.Web.UI.WebControls" 
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>

<script language="C#" runat="server">
    
public void SetupPictures()
{
    ArrayList list = new ArrayList();

    list.Add("pic1.gif");
    list.Add("pic2.gif");

    foreach (string url in list)
    {
        PageView pv = new PageView();
        myMultiPage.Controls.Add(pv);

        System.Web.UI.WebControls.Image image 
        = new System.Web.UI.WebControls.Image();
        pv.Controls.Add(image);

        image.ImageUrl = url;
    }
}
</script>

<body>
<form id="theform" runat="server">
    <myns:MultiPage id="thePics" runat="server" />
    <asp:Button id="addPics" runat="server" Text="Add Pictures" 
    OnClick="SetupPictures" /> 
</form>
</body>

In this Web Form, the MultiPage is initially empty. The SetupPictures method creates an array of URLs and then inserts each one into a new PageView control.

Using the MultiPage with the TabStrip WebControl

Many UI designs present a set of navigation buttons that, when clicked, present different views to the user. The view might consist of HTML or it might be an entire Web page. Using the WebControls makes it easier to author UI that integrates the MultiPage and TabStrip controls.

When authoring such an interface, there should be one Tab element for each PageView element.

<form id="tabstrip" method="post" runat="server">
<iewc:TabStrip id="TabStrip1" runat="server" TargetID="MultiPage1">
   <iewc:Tab Text="Page 1">
   </iewc:Tab>
   <iewc:Tab Text="Page 2">
   </iewc:Tab>
   <iewc:Tab Text="Page 3">
   </iewc:Tab>
</iewc:TabStrip>
            
<iewc:MultiPage id="MultiPage1" runat="server">
   <iewc:PageView id="page1">
   This is page one
   </iewc:PageView>
   <iewc:PageView id="page2">
   This is page two
   </iewc:PageView>
   <iewc:PageView id="page3">
   This is page three
   </iewc:PageView>
</iewc:MultiPage>
</form>

In this example, the two controls are synchronized by setting the TargetID attribute in the TabStrip to the ID attribute of the PageView. Clicking the Tab elements navigates to the appropriate content. Synchronizing these controls using the TargetID attribute means that the order of the content is important—the first Tab is linked to the first PageView, the second Tab to the second PageView, and so on.

The TargetID attribute can also be set on the Tab element. When this approach is used, the TargetID points to the ID attribute of a PageView element.

Note The Target attribute is read-only and returns the PageView object that corresponds to the TargetID. If the PageView object is not found, then null is returned.