Handle Events From Web User Controls
by Paul Delcogliano

November 2002 Issue

Technology Toolbox: ASP.NET, VB.NET

Level: Intermediate

You might notice that each page in a Web application has some common functionality on it—say, a toolbar. Before ASP.NET, you could encapsulate all the toolbar code and include it on every page using the <#include> tag. ASP.NET simplifies this process by enabling you to create a Web user control for your toolbar. Once you create the toolbar Web user control, you can simply drag and drop it onto every form in your application that requires one.

A common question that arises when using Web user controls is how to handle the events raised from the controls on your toolbar in your containing ASPX page. ASP.NET events provide a mechanism for doing this. Events raised on a Web user control are said to "bubble up" to the parent container. The process of bubbling events occurs even when user controls are nested within one another. The process is the same whether the container you want to handle the bubbled event is another user control or an ASPX page. I'll show you how to do it using an ASPX page to handle the bubbled events.

Using Visual Studio .NET, create a user control named MyToolbar with two button controls on it. Set the buttons' ID properties to btnSave and btnCancel and each button's text properties to Save and Cancel, respectively. The HTML looks like this after you're done:

<% @Control Language="vb" 
   AutoEventWireup="false" 
   Codebehind="MyToolbar.ascx.vb" 
   Inherits="WebApplication2.MyToolbar" 
   TargetSchema=http://schemas.
   microsoft.com/intellisense/ie5%>
< asp:Button id="btnSave" Text="Save" 
   runat="server">
< asp:Button id="btnCancel" Text="Save" 
   runat="server">

Now add the newly created toolbar control to an ASPX page by dragging the control from the Solution Explorer window onto the page. Also add a label to the ASPX page, name the label lblEvent, and set its Text property to "". Next, you need to add the code that handles events bubbled up from the control to the page. Select "(Overrides)" from the code view window in the Class Name dropdown. Select OnBubbleEvent in the Method Name dropdown. You get an event procedure that looks like this:

Protected Overrides Function _
   OnBubbleEvent(ByVal source As _
   Object, ByVal args As _
   System.EventArgs) As Boolean

End Function

The OnBubbleEvent handles all events bubbled up from the control. The source parameter is the control that raised the event. The args parameter contains any arguments that were passed along when the control's event fired. Once you know which control fired, you can take the appropriate action in your Web page. In the toolbar example, check if the source object is a button; if so, use the id property to determine which button. Add this code to the OnBubbleEvent event procedure:

If source.GetType.Equals _
   (GetType(Button)) Then

   Dim oButton As Button = source

      Select Case oButton.ID

         Case "btnSave"
   ' Save the record
   lblEvent.text = "Saved record"
         Case "btnCancel"
   ' Cancel the changes
   lblEvent.text = "Canceled changes"
         Case Else
         ' Some other button fired the 
         ' event
         End Select

End If

After you handle the bubbled event, you need to decide what to do with the event now. Your choices are to do nothing or to raise the event to parent containers in the hierarchy. You don't have to do anything if you're handling the bubbled event in a top-level container. However, if you're handling the event in a container that isn't the top-level container—say, a nested user control—you should raise the event to the container's parent. Invoking RaiseBubbleEvent raises the event you just handled to any parent container. Raising an event this way ensures that all containers in the hierarchy receive the event and can each determine how to handle the event. You can raise the event by adding this code to the end of your OnBubbleEvent event procedure:

RaiseBubbleEvent(source, args)

About the Author
Paul Delcogliano is the director of technology at Progressive Systems Consulting, a New York City-based firm specializing in the development of Internet/intranet, client/server, and other custom database applications for organizations in a variety of industries. Reach Paul at .