AJAX: Working with Events
Events in ASP.NET AJAX are quite unlike the events in the .NET framework. Rather than having explicit events and event handlers, the framework provides a workaround to this approach that doesn't require any custom syntax definitions to JavaScript itself, while still being able to expose the capability.
The approach is to expose events using an events property. This events property is defined in the Sys.Component class, the base class of all controls and extenders. The get_events() property setter returns an object of type EventHandlerList. This object can add event references to client events stored in a key. For instance, the following methods add, remove, and raise an event. These methods are located in the prototype definition, which is why the function declaration is at the end.
add_propertyChanged : function(handler) {
this.get_events().addHandler("propertyChanged", handler);
}
remove_propertyChanged : function(handler) {
this.get_events().removeHandler("propertyChanged", handler);
}
raise_propertyChanged : function()
{
var handler = this.get_events().getHandler("propertyChanged");
if (handler != null)
handler(this, Sys.EventArgs.Empty);
}
Working with events are done by methods that map the name of the event to a handler. The event is referenced by a string that uniquely identifies the event. Any clients registering to this event would register the name of a JavaScript method. This JavaScript method would be the event handler for the event in the ASPX page that the control or extender resides in.
It's up to something in the AJAX control or extender to call raise_propertyChanged. When some member does (property or method), this then triggers the propertyChanged event. An event handler in the ASPX would receive notification of it, and would be passed the sender and event argument (though the method doesn't have to accept these parameters). An event handler can be wired up like so:
<script language="JavaScript">
function propertyChangedHandler(sender, e)
{
alert("prop changed");
}
var ctl = $find('<%= MyControl.ClientID %>');
ctl.add_propertyChanged(propertyChangedHandler);
</script>
Anything that triggers this event will call the propertyChangedHandler JavaScript method. This method is a client-side event handler for our purpose. Something in the component actually needs to call raise_propertyChanged() to fire the event, but our event handler will catch it.
In ASP.NET AJAX components, the typical way to expose events is through a property (as oxy moronic as that may be). The property stores the name of the JavaScript event handler (propertyChangedHandler) and passes it to the client script when the component is described. In an ASP.NET AJAX component, this is done using GetScriptDescriptors, with a statement as shown below:
descriptor.AddEvent("propertyChanged", this.OnClientPropertyChanged);
It's by convention to include "OnClient" for event handlers to a client event. Using the AJAX Control Toolkit approach, events can be declared using the following approach:
[
ExtenderControlEvent,
ClientPropertyName("propertyChanged")
]
public string OnClientPropertyChanged
{
get { .. }
set { .. }
}
At runtime, the AJAX component is dynamically described by using the metadata defined in the attributes of the property definition, which it sees that the OnClientPropertyChanged property contains the name of a method that is an event handler. This event handler is passed to the add_propertyChanged method. When that event is raised, the event handler defined here gets fired.