User Controls

Article
09/14/2006

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

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

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

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 Forms pages, a user control can also contain multiple controls, as the following section demonstrates. The following User Control example uses a list mobile control to create a menu.

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 are creating mobile user controls, you must derive them from the MobileUserControl class in your .ascx file, rather than from the standard System.Web.UI.UserControl class. This is shown in the following code.

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

Location of Web.config Affects Its Use

ASP.NET references the directory of the currently running page for configuration information for the running control. Thus, if you have device-specific filters or other information that is defined in a Web.config file and stored in a location other than the directory where the page will run, the configuration will not be found. For example, if you have a page running in the current directory that includes a user control called Sales/Inventory.ascx, and you also have a Sales/Web.config file within that same Sales directory, the Inventory.ascx page will not process the Sales/Web.config file; it will get the configuration from the page that is running the control. This means that any filters referenced from Inventory.ascx, but defined in Sales/Web.config, will not be found or used.

Handling Literal Text in User Controls

Text in a user control is parsed as System.Web.UI.LiteralControl and not System.Web.UI.MobileControls.LiteralText. If literal text is present in a user control, it appears on all pages if the user control contains controls with internal pagination, such as Form. 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 the text is specified as LiteralText.

<mobile:Panel runat=Server Paginate=true>
...
</mobile:Panel>

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.

<%@ Register TagPrefix="mobile" 
         Namespace="System.Web.UI.MobileControls" 
         Assembly="System.Web.Mobile" %>

// Car is a public field, of externally defined CarInfo type.
public CarInfo Car;

<mobile:Label id="Label1" runat="server">Make: <%# Car.Make %></mobile:Label>
<mobile:Label id="Label2" runat="server">Model: <%# Car.Model %></mobile:Label>
<mobile:Label id="Label3" runat="server">Year: <%# Car.Year %></mobile:Label>
<mobile:Label id="Label4" runat="server">Color: <%# Car.Color %></mobile:Label>

When the page runs on a mobile device, the make, model, year, and color of the car appear on the screen.

Deploying a User Control

After you create a mobile user control, you can deploy it in either of two ways: by registering it, or by programmatically loading the control on a mobile page. To register a user control, use the @ Register directive; to load the control, use the LoadControl method. The following code describes how to register your control.

<%-- Registers the control on the page. Car.ascx is the relative URL of the user control. --%>
<%@ Register TagPrefix="myCompany" TagName="CarCtl" Src="Car.ascx" %>

[C#]

    // Add other code here.

    // Binds the car object to the control declared
    // in the following code.
    myCarCtl.Car = car;
    myCarCtl.DataBind();

    // Add other code here.

    <%-- Control declaration --%>
    <myCompany:CarCtl id="myCarCtl" runat="server" />

Or, if you prefer, you can use the LoadControl method in place of the @ Register directive, as shown in the following code.

[C#]

// Use the LoadControl method.
    CarCtl = LoadControl("Car.ascx")
    Form.Controls.Add(CarCtl);
    // Insert the remainder of the previous code here.

Resolving URLs

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

The page's address is /default.aspx.
The page accesses a user control found at subdir/UserControl.ascx.
The user control contains a link that points to the user control, b.ascx.

The link described in this scenario resolves to subdir/b.ascx. The reason for this is that a user control can encapsulate any links or any 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. You can write your controls and adapters to call the ResolveUrl method of a mobile control to resolve a URL relative to the directory of the page or user control that contains the control. Some helper methods in the adapter base classes automatically call the ResolveUrl method to resolve hyperlinks.

Formatting and Linking in User Controls and Form References

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

    <mobile:Link runat="server" 
        id="Link1" 
        Text="Click here!" 
        NavigateURL="#Form2">
    </mobile:Link>

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

When a control on the page refers to a form within a child user control, the URL must include the full unique ID of the form, in the format 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. This page also contains a top-level user control with the ID, Control1. 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 form does not contain any form with the specified ID.
On the page	#Control1:FormA	Links to FormA in the user control.
In the user control	#FormA	Links to FormA in the user control, because the ASP.NET first searches in the user control itself.
In the user control	#FormB	Links to FormB on the page, because the ASP.NET ultimately resolves the form reference relative to the user control's parent.