The ICallbackEventHandler

So, you are interested in knowing about the ICallbackEventHandler which can be "used to indicate that a control can be a target of a callback event on the server" according to MSDN.

A very consise and correct definition of the interface which explains everything, except I can see you scratch your head & wonder whats in it for you. Stick along with this article & hopefully you would have a new toy to impress your peers at work!

The problem:

Suppose you need to build a simple ASP.NET 2.0 web page which has a section to show some quotes. You want to randomize these quotes such that the user sees new quotes every few seconds (this is because of the crappy content, but try telling that to the content writer!)

A few possible solutions:

1. Postback the complete page after a few seconds & put in random quote, with big usablility & server load issues as a side-effect.
2. Put in a UpdatePanel around the section and reload the section by setting a Timer, which is a better solution compared to option 1 in terms of usability, but really no difference on the server load.
3. Implement custom code to fetch the data from the server using the XMLHTTP object, which is a good choice since it does not have the issues aforementioned.
4. Implement the ICallbakEventHandler, which... happens to be the point of this article, isn't it?

Solution I prefer:

I would prefer using the ICallbackEventHandler interface to solve this problem for the following reasons:

1. The ICallbackEventHandler is a wrapper on XMLHTTP & there would not be a lot of javascript code to get it working
2. There are no complex web controls which need to be rendered on the UI because of this call to the server
3. As the target web site is in ASP.NET 2.0, I would prefer using the implementation of the framework out of the box
4. The load on the server is limited to calling the methods needed without the burden of a full page postback

Show me to code:

I know you are excited to see this implemented, so now would be a good time to download the source code for the sample application & use it as a reference for the remaining sections of this article.

All this while, we have been talking about the ICallbackEventHandler interface which looks like so:

public interface ICallbackEventHandler
{
   string GetCallbackResult();
   void RaiseCallbackEvent(string eventArgument);
}

Implementing this interface & getting the code to work is as simple as the 3 steps listed below.

Step 1: implement the interface on the Page/UserControl class

To keep our code a bit organized, I create a RandomQuotesUserControl.ascx user control which would, surprisingly, contain the logic to show a random quote. This user control is then registered on the page which needs to show these quotes. In our sample application, I have registered this control on the default.aspx page itself. Alternatively you could create a MasterPage, register this control on the MasterPage & derive the other pages on the web site from that MasterPage.

The inheritence of the RandomQuotesUserControl class would be like so:

public partial class RandomQuoteUserControl 
        : System.Web.UI.UserControl
        , ICallbackEventHandler

Step 2: Writing implementation for the interface methods

I start by implementing the RaiseCallbackEvent like so:

public void RaiseCallbackEvent(string eventArgument)
{
    m_callbackResult = 
    "document.getElementById('randomQuote').innerHTML ='" 
    + this.getQuote() + "'";
}

In this method, I am setting a string to the a local member which will contain the final output which needs to be placed on the UI when the GetCallbackResult method is called. This method has been implemented like so:

public string GetCallbackResult()
{
    return m_callbackResult;
}

Step 3: Register the client callback reference

In this step, we will be registering the client callback javascripts with the Page so that our client side will understand what to do to get our code working. This is coded in the Page_Load event like so:

protected void Page_Load(object sender, EventArgs e)
{
    // Creating the scripts which need to be called
    string clientScript = "function serverRequest(args, context){{ "
    + Page.ClientScript.GetCallbackEventReference(this, "args", "getResult",
    "context") + "; }} function getResult(result, context){{ eval(result); 
    callServer(); }} function callServer(){
    setTimeout('serverRequest();', 3000);} callServer();";
    // Register the client script
    Page.ClientScript.RegisterClientScriptBlock(this.GetType(), 
    "RandomQuoteCallback", clientScript, true);
}

Thats it, compile & run the application to see the quotes changing every 3 seconds.

This is a very simple example of what can be done using the ICallbackEventHandler interface. You could have a lot more complex implementation like sorting a grid or show tool tips or do something really cutting edge. The options are limitless.

This works for me & hopefully it works for you too.

Happy programming!