Dr. Dobb's | Programmatic Loading of User Controls

Programmatic Loading of User Controls

Dino explains how to set up a user control for your web site so that it can be modified on the fly or modified based on changing runtime conditions

April 17, 2007
URL:http://www.drdobbs.com/windows/programmatic-loading-of-user-controls/199100366

Programmatic Loading of User Controls Dino explains how to set up a user control for your web site interface so that it can be modified on the fly or based on changing runtime conditions

A user control is a kind of Web form made of any combination of server controls sewn together with managed and script code. A typical user control has a rich user interface and represents a block of reusable UI gadget. It can also optionally feature an object model and make some its encapsulated components visible to developers. All of its constituent controls are protected and inaccessible from outside components unless they're made available through a public programming interface.

A user control can be seen as an embeddable Web form that can be nested inside other container forms. You create a user control in much the same way you create a Web form. You can easily convert a page into a user control and vice versa. A user control is given a mandatory ASCX extension.

Pages see the new control as a monolithic component and treat it as a regular native server control. A user control is normally simpler to write than a custom control and doesn't usually require special ad hoc skills, as is often the case with custom controls.

Just like any other ASP.NET server control, a user control can be created via code and based on runtime conditions. Unlike server controls, though, you don't use the new operator to instantiate a user control. You rather resort to the LoadControl method defined on the page class. The method returns a Control object that it created from the contents of an ASCX file. The file refers to a virtual path.


Control ctl = thePage.LoadControl("Sample.ascx");

As long as the user control doesn't feature additional properties, you are ready to add it to the page for display. Here's the code you need:


thePage.Controls.Add(ctl);

What if the user control contains properties and methods to configure its behavior? As you can see, the LoadControl method returns a reference to a Control object; you need to cast the reference to the appropriate user control type in order to set properties and use the control to its fullest. But what's the type of the user control?

You can give a user control an explicit type name by using the ClassName attribute of the @Control directive.


<% @Control ClassName="MyUserControl" %>

However, this is still not enough. You can't just cast the object that LoadControl returns to the user control type. In order to do so, you need to have a reference to the assembly that contains the compiled code of the control. This is just the role of the @Reference directive. When you create the user control programmatically, the strong type for the user control is available to the page only after you have created a reference to it.


<%@ Reference Control="Sample.ascx" %>

The net effect of this directive is to make available in the context of the Web page a reference to a type that represents the specified control.


MyUserControl ctl;
ctl = (MyUserControl) thePage.LoadControl("Sample.ascx");
// Configure the user control
thePage.Controls.Add(ctl);

Dynamically loading user controls from an external URL is a handy trick for modifying on the fly, or based on changed runtime conditions, a piece of the page's user interface. If you need to make sure that each user control serving a given purpose has a fixed behavior, you simply inherit all user controls from a common base class or force them to implement a given interface.