Once you have defined the initial look for your User Control, you can use it on any web page any number of times.
You can add Web User Controls to Web Forms in much the same way as other Web Controls, by adding their tags and defining any attributes in the .aspx file. You can do this in two ways:
- By dragging the control from the Project Manager window onto the designer for a Web Form.
- By manually entering the required tags and attributes.
Start by creating a new Web Forms page; call it UserControlTest.aspx. Make sure the "Design" view for the page is active, then simply drag the "ContactInfo.ascx" file from the Project Manager onto the UserControlTest designer.
Notice how the design time appearance bears no relationship to the content placed on your user control. This is quite confusing until you get used to this designer behavior. As expected, when you view the page in the Browser, the control renders as expected.
Registering a User Control on a Web Forms Page
Let's take a quick HTML view of our test page:<%@ Page language="c#" Debug="true" Codebehind="UserControlTest.pas" AutoEventWireup="false" Inherits="UserControlTest.TUserControlTest" %>As you can see, the drag-drop approach hides the details of how ASP.NET embeds a User Control in the Web Forms page. This information is important if you want to manually add another user control to the page.
<%@ Register TagPrefix="uc1" TagName="ContactInfo" Src="~/Controls/ContactInfo.ascx" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body>
<form runat="server">
<uc1:ContactInfo id="UserControl1" runat="server"></uc1:ContactInfo>
</form>
</body>
</html>
The @Register directive associates an arbitrary TagPrefix and TagName with the User Control located in the file specified by the Src attribute. The TagPrefix determines a unique namespace for the user control (so that multiple user controls with the same name can be differentiated from each other). The TagName is the unique name for the user control (you can choose any name). The Src attribute value can be either a relative or an absolute path to the user control source file from your application's root directory. For ease of use, it is recommended you use a relative path. The tilde (~) character represents the root directory of the application.
After registering the user control, you may place the user control tag in the Web Forms page just as you would an ordinary server control (including the runat="server" attribute).
If you open up the UserControlTest.aspx page in the Browser you'll be presented with an "empty" page. Of course, the page is not empty - only the a tag's link will be displayed from the User Control. A look at the HTML source will reveal our User Control's HTML table and two additional SPAN elements - those two Label controls have rendered into. Since we have not specified the Text property - the page only displays the static link.
Adding Properties and Methods to User Controls
In most cases your User Controls will need to expose properties and methods of their own, as well as responding to and raising events.Like all .NET components, Web User Controls are implemented using classes. This means you define custom properties and methods just as you would for any class.
Let's now add a property called "Contact" to our ContactInfo User Control. The Contact property will wrap the text property of the infoLabel Label control located on our user control.
TContactInfo = class(System.Web.UI.UserControl)
...
public
function GetContact: string;
procedure SetContact(const Value: string) ;
property Contact : string read GetContact write SetContact;
end;
...
implementation
...
function TContactInfo.GetContact: string;
begin
result := infoLabel.Text;
end;
procedure TContactInfo.SetContact(const Value: string) ;
begin
infoLabel.Text := Value;
end;
Note that beside adding public properties, public fields and methods of a User Control are also promoted to public properties (that is, tag attributes) and methods of the control.
Setting Properties of a User Control
The simplest way of setting the Contact property value is by assigning a value for the Contact attribute:<uc1:ContactInfoSince the Contact property is a wrapper for the Text property of the infoLabel control, assigning a string value for it, by accessing the Contact property as a tag of our user control, will set the Text property of the infoLabel control.
id="UserControl1"
runat="server"
Contact="Author: Zarko Gajic">
</uc1:ContactInfo>
Programmatically accessing a user control from the Web Forms Page's code-behind involves a few extra steps ...
