User Controls
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"
NavigateUrl="#form2" Text="Next" />
</mobile:form>
<mobile:form ID="form2" Runat="server">
<mobile:Link runat="server" id="Link2"
BreakAfter="true"
Text="Return" NavigateUrl="#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 NavigateUrl property of the Link control to specify the URL.
<mobile:Link ID="Link1" Runat="server"
NavigateUrl="#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 |
|
Links to |
On the page |
|
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 |
|
Links to |
In the user control |
|
Links to |
In the user control |
|
Links to |
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.