Converting a Page to a User Control

It is easiest to understand the user control model by converting a portion of an existing ASP.NET page into a user control. We'll start with a page that provides a simple user interface for entering data. We'll convert the portion of the user interface that contains a TextBox with an associated RequiredFieldValidator into a user control. Listing 4-1 shows in boldface the portion that we want to move into a reusable user control.

Listing 4-1 MyPage.aspx

 <%@Pagelanguage="c#"%> <html> <head> <scriptrunat="server"> privatevoidokButton_Click(objectsender,EventArgse){ infoLabel.Text="Youentered'"+entryTextBox.Text+"'."; } </script> </head> <body> <formid="MyPage"method="post"runat="server"> <p/>

 Thispagedemonstratesasimpleuserinterfaceconsisting ofaTextBoxandaRequiredFieldValidator,whichwillbe encapsulatedintoausercontrol. <p/> Enteravalue: <p/>  <asp:TextBoxid="entryTextBox"runat="server"/> &nbsp; <asp:RequiredFieldValidatorid="RequiredFieldValidator1" runat="server"ErrorMessage="(required)" ControlToValidate="entryTextBox" ToolTip="Youmustenteravalue."/> &nbsp;  <p/> <asp:Buttonid="okButton"runat="server" Text="OK"Width="75px"OnClick="okButton_Click"/> <p/> <asp:Labelid="infoLabel"runat="server"/> <p/> </form> </body> </html>

Listing 4-2 shows the source code for the user control. If you save this listing as a text file with an .ascx extension in an ASP.NET Web application, you create a user control. If you installed the code from the sample files, you will find this control in the BookWeb Web application at the location Chapter4\UserControls\RequiredTextField.ascx.

Listing 4-2 RequiredTextField.ascx

 <%@ControlLanguage="c#"ClassName="RequiredTextField"%> <scriptrunat="server"> publicstringText{ get{ returnentryTextBox.Text; } set{ entryTextBox.Text=value; } } </script> <asp:TextBoxid="entryTextBox"runat="server"/> &nbsp; <asp:RequiredFieldValidatorid="RequiredFieldValidator1" runat="server"ErrorMessage="(required)" ControlToValidate="entryTextBox" ToolTip="Youmustenteravalue."/> &nbsp;

To create our user control, we created a text file with a Control directive at the top and copied the boldface lines in Listing 4-1 into it. In addition, we exposed a property, Text , which allows our users to access the Text property of the contained TextBox control. Properties enable page code to interact with (program against) your control.

The Control directive at the top of the file specifies the programming language for the user control and provides a class name for the control. The Control directive is analogous to the Page directive at the top of an .aspx file. The "ASP.NET Page Syntax" topic in the .NET Framework SDK documentation contains a complete list of directives and attributes used with user controls.

A user control can contain any valid page syntax, including templates, data-binding syntax, and event handlers. However, a user control should not contain enclosing tags such as <html> , <body> , or <form> because these tags are provided by the containing page.

A file with an .ascx extension cannot be served to a Web client. If you enter http://localhost/BookWeb/Chapter4/UserControls/RequiredTextField.ascx in your browser's address bar, you will get a server error message that states, "This type of page is not served." A file with an .ascx extension can be used only from another page or user control.

Accessing a User Control from a Page

Before you can use a user control declaratively in a page, you must register the user control with the page by including a Register directive at the top of the page, as shown in the following example:

 <%@RegisterTagPrefix="mspuc"TagName="RequiredTextField" src="RequiredTextField.ascx"%>

The TagPrefix attribute supplies a tag prefix for the user control (which is similar to the asp tag prefix for Web controls that ship with the .NET Framework SDK), the TagName attribute supplies a tag name, and the Src attribute specifies the path to the user control. You can specify any value (other than asp ) for the TagPrefix attribute and any value for the TagName attribute. The Tag Prefix : TagName combination creates a tag that the parser associates with the user control specified in the Src attribute. This combination must be unique for each user control registered with the page. For example, once you have registered the control with the page, the parser loads RequiredTextField.ascx when it sees the following declaration on the page:

 <mspuc:RequiredTextFieldrunat="server"/>

The value of the Src attribute must be specified as a virtual path within your Web application (/BookWeb/Chapter4/UserControls/RequiredTextField.ascx or ~/Chapter4/UserControls/RequiredTextField.ascx or RequiredTextField.ascx). It cannot be specified as an absolute URL ( http://localhost/BookWeb/Chapter4 /UserControls/RequiredTextField.ascx ) or as a physical path (<path to BookWeb>)\Chapter4\UserControls\RequiredTextField.ascx).

Note that a user control can be used within another user control. If you want to access a user control from another user control, you have to register the inner (nested) user control with the containing user control.

The page in Listing 4-3 uses the RequiredTextField user control that we defined in Listing 4-2.

Listing 4-3 RequiredTextFieldTest.aspx

 <%@Pagelanguage="c#"%> <%@RegisterTagPrefix="mspuc"TagName="RequiredTextField" src="UserControls/RequiredTextField.ascx"%> <html> <head> <scriptrunat="server"> protectedvoidokButton_Click(objectsender,EventArgse){ infoLabel.Text="Youentered'"+ RequiredTextField1.Text+"'."; } </script> </head> <body> <formid="MyPage"method="post"runat="server"> <p/> ThispageusestheRequiredTextFieldusercontrol. <p/> Enteravalue: <p/>  <mspuc:RequiredTextFieldid="RequiredTextField1" runat="server"/>  <p/> <asp:Buttonid="okButton"runat="server" Text="OK"Width="75px"OnClick="okButton_Click"/> <p/> <asp:Labelid="infoLabel"runat="server"/> <p/> </form> </body> </html>

If you access this page in your browser, you will see that the page behaves the same way as MyPage.aspx. However, some of the UI in RequiredTextFieldTest.aspx is encapsulated in the reusable control RequiredTextField .