Creating User Controls | Microsoft .NET and J2EE Interoperability Toolkit (Pro-Developer)

ASP.NET divides the built-in server controls in two groups: HTML controls and web controls. Each is contained within its own namespace. HTML controls map one to one with standard HTML elements, whereas some elements do not map to a specific HTML control. You have the option of changing the functionality of a page at runtime by modifying the control’s attributes programmatically. Creating a user control is new to ASP.NET. User controls consist of HTML markup or ASP.NET code that bears the .ascx file extension. You can employ the @ Control directive to specify precisely how a control behaves on the web form. A caveat to employing user controls is that you cannot call them directly. They must reside on an already existing page. In addition, user controls should not contain <html>, <body>, or <form> elements primarily because they are already present on the page where your control is placed. You can strong type the control programmatically by adding the ClassName attribute as follows:

<%@ Control ClassName="RegisterClient" %>

Let’s create a user control and see how easy it is to do.

<%@ Control ClassName="RegisterClient" %>
<script language="vb" runat="server" %>
  Private name  As String = ""
  Public Property Name As String
  Get
  Return name
  End Get
 
  Set
  name = Value
  End Set
  End Property
 
  Public Sub GreetClient()
  Label1.Text = "Please register to use our services", & name
  End Sub
  </script>
  <asp:Label   runat="server"></asp:Label>

The file should be saved as Register.ascx and stored in your Internet Information Services virtual directory.

The code declares a string variable called name; then a property procedure called Name sets and retrieves the value of the variable. Finally, a Sub procedure called GreetClient() sets the Text property of the Label server control.

Adding a User Control Declaratively

Two methods exist for adding the control to a web form page. The first method allows you to place the control declaratively. Create a new web form page called GreetContainer.aspx, and place it in the virtual directory where you saved Register.ascx. Write the following code:

<%@ Page Language = "vb" %>
<%@  Register TagPrefix = "ASPNETsbtn" TagName=RegisterClient"
  Src = "Register.ascx" %>
<html>
<head>
  <script runat="server">
  Sub Page_Load(Sender as Object, E As EventArgs)
  MyRegister.Name = "Steve"
  MyRegister.GreetClient
  End Sub
  </script>
</head>
<body>
  <ASPNETsbtn:RegisterClient id= "MyRegister" runat ="server"/>
</body>
</html>

The output is as expected:

Please register to use our services, Steve

Adding a User Control Programmatically

Adding a user control to a web forms page programmatically is similar to the declarative method, but with a few changes. Create a new web forms page named RegisterMoreClients.aspx. Then, save it to the same directory as you did previously:

<%@ Page Language = "vb" %>
<%@ Reference Control = "Register.ascx" %>
<html>
<head>
<script runat="server">
  Sub Page_Load(Sender As Object, E as EventArgs)
  Dim MyRegister As Control = LoadControl("Register.ascx")
  RegisterHolder.Controls.Add(MyRegister)
  CType(MyRegister.Register).Name = "Steve"
  CType(MyRegister.Register).GreetClient
  End Sub
  </script>
 </head>
<body>
<asp:placeholder  runat="server"/>
</body>
</html>

The @ Reference directive tells ASP.NET to compile and link the user control Register.ascx with the page when compiled. The Placeholder control allows you to insert a placeholder in the HTML markup so you can add a control to a specific location on the page. Reference the saved page just as you did previously from the Internet Services Manager. Right-click this page, and select Browse to render the page to the browser.

Server Control Types

Server controls can be placed on a web forms page. You can add an HTML control to the page by referencing the System.Web.HTMLControls namespace. Here is how you would add your HTML control to the page:

<%@ Page Language = "vb" %> 
<html>
<head>
</head>
<body>
  <form runat ="server">
  <input id ="ButtonName" type="submit" runat = "server"/>
  </form>
 </body>
</html>

By adding the runat = “server”, you can access the control programmatically on the server side. As you will recall, the server-side <form> causes the page to post back to the server when the user clicks the Submit button.

Web Controls

The syntax for adding a web control is slightly different from syntax for an HTML control. Instead of defining your own tag prefix, use the asp prefix. Here is how you add a web control to the page:

<asp: TextBox id = "myTextBox" runat = "server" />

Let’s add a TextBox control and two web labels to a server-side form. Write the following code to the ServerSideControl.aspx page beginning with the <html> tag:

<html>
<head>
 <script runat="Server">
  Sub Page_Load(Sender As Object, E As EventArgs)
  If Is PostBack Then
  GreetingsLabel.Text = "Greetings, " & _
  Server.HTMLEncode(MyNameTextBox.Text)
  End If
  End Sub
  </script>
</head>
<body>
  <form runat="Server">
  <asp:Label id = "MyNameLabel" runat="server">Name: </asp:Label>
  <asp:TextBox  runat="Server"/>
  <input  type="submit" runat="server"/>
  </form>
  <asp:Label id = "GreetingLabel" runat = "server"/>
 </body>
</html>

If you run this page, you can enter text in the TextBox control and submit the page. After the post back occurs, provide the proper URL and view the page.

Note

Assuming you set the AutoEventWireup to true, if you manually write your code in a text editor such as Notepad, you must set the AutoEventWireup attribute to true. If Visual Studio .Net generates the page, by default this attribute is set to false. This indicates that all event handlers must be manually wired to the events they will handle.

Handling Events in the Server Control

An event handler was provided for the Page_Load event in the previous example. The event handler checks the IsPostBack page property to determine whether a post back occurs because the user has interacted with the Submit button. If this evaluation is true, set the Text property for the label to the appropriate text. In addition, employ the Server.HtmlEncode methodology to encode your text.

Note that when you add an event handler for the Load stage, you should check the IsPostBack page-level property. Handling Control events is slightly different. In this scenario, apply the controlname_eventname instead. Here is an example:

Sub NameTextBox_TextChanged
(Sender As Object, E As EventArgs)GreetingLabel.Text
 &=" your name has changed"
End Sub

Next, add the following attribute to your NameTextBox server control tag:

<asp:TextBox id ="NameTextBox" onTextChanged = "NameTextBox_TextChanged"
runat="server"/>