User Controls

Article
11/16/2012

ASP.NET mobile user controls provide a quick, efficient technique to create your own user control on an ASP.NET mobile Web page. You can use the contents of any mobile page within another mobile page by combining one or more controls with their associated logic, and then encapsulating them into a user control. With a few exceptions, a user control is identical to a MobilePage control.

A mobile user control:

Must have a file name extension of .ascx.
Does not require an @ Page directive.
Must contain an @ Register directive.

The @ Register directive associates aliases with namespaces and classes, so that you can declare mobile controls in the user control.

ASP.NET distinguishes between user controls and composite controls. A user control is persisted as an .ascx text file, whereas a composite control is compiled and persisted in an assembly. In ASP.NET mobile Web pages, a user control can contain multiple controls, as the examples in this topic demonstrate.

Creating a User Control

You create a new user control by creating a file with an .ascx extension. The following code example includes a user control that uses multiple labels to display the details of a car.

<%@ Control Language="VB" ClassName="CarControl"  
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile"  
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script runat="server">
    ' Private field of externally defined CarInfo type 
    Private _car As New CarInfo()

    ' Public Property for the CarInfo 
    Public Property Car() As CarInfo
        Get 
            Return _car
        End Get 
        Set(ByVal value As CarInfo)
            _car = value
        End Set 
    End Property
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1" runat="server" BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2" runat="server" BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3" runat="server" BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4" runat="server" BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

<%@ Control Language="C#" ClassName="CarControl" 
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script runat="server">
    // Private field of externally defined CarInfo type 
    private CarInfo _car = new CarInfo();

    // Public Property for the CarInfo 
    public CarInfo Car
    {
        get { return _car; }
        set { _car = value; }
    }
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1" runat="server" BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2" runat="server" BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3" runat="server" BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4" runat="server" BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

Deploying a User Control

After you create a mobile user control, you can add it to an ASP.NET mobile Web page in the following ways:

Registering it on the page and declaring it in markup.
Programmatically loading the control into the page.

To register a user control, use the @ Register directive. To load the control programmatically, use the LoadControl method.

The following example code shows how to register and use a custom control declaratively in a page, and also how to load a user control programmatically.

<%@ Page Language="VB"  
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile"  
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="~/CarControl.ascx" %>

<script runat="server">
    Protected Sub Page_Load( _
        ByVal sender As Object, ByVal e As EventArgs)
        ' Set the existing car control's data
        CarCtl.Car = New CarInfo("TreeCars", "Rooter", _
            2003, "Tan")

        ' Load a new car control and set the data 
        Dim ccar As CarControl = _
            CType(Page.LoadControl("~/CarControl.ascx"), _
            CarControl)
        ccar.ID = "newCarCtl" 
        ' Set the new car control's data
        ccar.Car = New CarInfo("TreeCars", "Climber", _
            2001, "Green")
        ' Add the new car control to form2.Controls
        form2.Controls.Add(ccar)

        ' Bind the data and the controls
        DataBind()
    End Sub
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" runat="server">
        <carp:CarControl ID="CarCtl" runat="server" /><br />
        <mobile:Link ID="Link1" Runat="server"
            href="#form2" Text="Next" />
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Link runat="server" id="Link2" 
            BreakAfter="true" 
            Text="Return" href="#form1" />
        <br />
    </mobile:form>
</body>
</html>

<%@ Page Language="C#" 
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="CarControl.ascx" %>

<script runat="server">
    protected void Page_Load(
        object sender, EventArgs e)
    {
        // Set the existing car control's data
        CarCtl.Car = new CarInfo("TreeCars", "Rooter", 
            2003, "Tan");

        // Load a new car control and set the data
        CarControl ccar = 
            (CarControl)Page.LoadControl("~/CarControl.ascx");
        ccar.ID = "newCarCtl";
        // Set the new car control's data
        ccar.Car = new CarInfo("TreeCars", "Climber", 
            2001, "Green");
        // Add the new car control to form2.Controls
        form2.Controls.Add(ccar);

        // Bind the data and the controls
        DataBind();
    }

    // Toggles the visible form 
    protected void Command_Click(
        object sender, EventArgs e)
    {
        if (this.ActiveForm == form1)
            this.ActiveForm = form2;
        else 
            this.ActiveForm = form1;
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" runat="server">
        <carp:CarControl ID="CarCtl" runat="server" /><br />
        <mobile:Command ID="Command1" Runat="server" 
            OnClick="Command_Click">Next</mobile:Command>
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Command ID="Command2" Runat="server" 
            OnClick="Command_Click">Return</mobile:Command>
        <br />
    </mobile:form>
</body>
</html>

Resolving URLs

When you create a page that accesses a user control located in a different directory, all relative URLs in the user control are resolved relative to the user control's directory, rather than to the page's directory. The following describes a typical scenario:

The page's address is /Default.aspx.
The page contains user control subfolder/UserControl.ascx.
The user control in turn contains user control B.ascx.

In this scenario, B.ascx is resolved as subfolder/B.ascx. Resolving URLs this way enables the user control to encapsulate any links or other relative resources that it might require.

The following URLs resolve relative to a user control:

Any navigation URLs — for example, URLs for a Link control.
An image URL on an Image control.
An action URL for a Form control.

When writing controls or control adapters, you must ensure that you resolve relative URLs where necessary. In your controls and adapters, call the mobile control's ResolveUrl method to resolve a URL relative to the directory containing the page or user control. Some helper methods in the adapter base classes automatically call the ResolveUrl method to resolve hyperlinks.

An exception is when you include a DeviceSpecific control in a custom user control, and the user control references device filters listed in the <deviceFilters> section of the Web.config file. In that case, the control uses the Web.config file in the directory where the page is located, not the Web.config file located in the control's subdirectory.

Formatting and Linking in User Controls and Form References

You can link to a form on the same page using a URL that begins with a number sign (#) followed by the form ID. The following code sample uses the href property of the Link control to specify the URL.

<mobile:Link ID="Link1" Runat="server"
    href="#form2" Text="Next" />

In a typical scenario, you have a user control that is inserted into a page at the top level. The page and the user control might contain one or more forms. Controls on the page and on each user control can refer to forms contained within each other, following these rules:

When a control on the page refers to a form in a child user control, the URL must include the full unique ID of the form. The format is ucid:formid, where ucid is the ID of the user control and formid is the ID of the form.
When a control within a user control refers to a form, ASP.NET first searches for the form in the user control, then in its parent, and so on, all the way up to the page level.

For example, suppose a page contains two forms whose IDs are FormA and FormB. The page also contains a top-level user control with the ID UserControl1. This user control contains two additional forms whose IDs are FormA and FormC. The following table shows examples of possible URLs and their behavior for this scenario.

Control location	Form URL	Behavior
On the page	#FormA	Links to FormA on the page itself.
On the page	#FormC	Throws an exception, because the page does not contain any form with the specified ID. (Only the user control has such a form.)
On the page	#UserControl1:FormA	Links to FormA in the user control.
In the user control	#FormA	Links to FormA in the user control, because ASP.NET first searches in the user control itself.
In the user control	#FormB	Links to FormB on the page, because ASP.NET resolves the form reference relative to the user control's parent.

Special Considerations for Creating Mobile User Controls

You must consider the following issues when developing user controls for your mobile application.

Working with Predefined Styles

For fully functional style support in user controls, when you create mobile user controls, you must derive them from the MobileUserControl class in your .ascx file, rather than from the standard UserControl class. This following code example shows this.

<%@ Control Language="C#"
    Inherits="System.Web.UI.MobileControls.MobileUserControl" 
    %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

Location of the Web.config File Affects Its Use

ASP.NET uses the directory of the currently running page to find configuration information for controls in that page. Thus, if you have device-specific filters defined in a Web.config file, that Web.config file must be located at the root of the mobile Web pages section of your ASP.NET Web application. For example, if you have a page named /Reports/Report1.aspx that includes a user control named /Sales/Inventory.ascx, and you also have a /Sales/Web.config file that contains device filters, the /Sales/Inventory.ascx control will look for device filter definitions in the /Reports/Web.config file, not the /Sales/Web.config file.

Handling Literal Text in User Controls

Text in a user control is parsed as a LiteralControl and not as a LiteralText control. If the user control contains literal text, and if the user control contains controls with internal pagination, such as Form, the text appears on all pages. To avoid this issue, place the contents of the user control in a Panel control so that the text is parsed by the ASP.NET page framework and treated as a LiteralText control.

User Controls

Creating a User Control

Deploying a User Control

Resolving URLs

Formatting and Linking in User Controls and Form References

Special Considerations for Creating Mobile User Controls

Working with Predefined Styles

Location of the Web.config File Affects Its Use

Handling Literal Text in User Controls

See Also

Reference

Other Resources

Additional resources