Using the wwMethodCallback control makes it extremely easy to create AJAX callback on a page. The steps are:

• Add a wwCallbackMethod to the page
  
• Create a method in your server page (or control) class that is to be called from the client
  
• Mark the method with the [CallbackMethod] attribute
  
• Set up your client event handler to handle the response and error callbacks
  
• Implement the client handlers
  
• Call the proxy object and server method:
  Callback.HelloWorld("Rick",HelloWorldCallback,OnPageError);
  

Let's walk through it. First make sure the control is registered with the page - if you drop the control from the toolbox then this is automatic - otherwise you have to manually add it like this:

<%@ Register Namespace="Westwind.Web.Controls" Assembly="Westwind.AjaxToolKit" TagPrefix="ww" %>

The add a HoverPanel control to the page with visually from the toolbox or using code like this:

<ww:wwMethodCallback ID="Proxy" runat="server" 
        PostBackMode="PostMethodParametersOnly"                          
></ww:wwMethodCallback>

I set almost no properties here, but there are a couple of implicit properties that are defaulted and bear explanation. PostBackMode determines how data is sent back to the server. By default all form data, plus the method parameters are posted. Here I don't require the form data so I override and use only PostMethodParametersOnly. In addition there's a ServerUrl property which defaults to the current page, which is what we want in this example. But you can override ServerUrl to point at another page that contains callback methods or at an HttpHandler derived from wwCallbackHandler which provides a high performance and fully self contained mechanism for hosting a class with [CallbackMethod] attributed methods.

You're now ready to start calling remote methods. So lets set up the server side method. What else than a Helloworld method?

[CallbackMethod]
protected string HelloWorld(string Name)
{
    return "Hello " + Name + ". Server Time: " + DateTime.Now.ToString();
}
[CallbackMethod]
protected decimal AddNumbers(decimal x, decimal y)
{
    return x + y;
}

Very simple. You just create your method and have it return normal parameter types. Make sure you mark up each method with the [CallbackMethod] Attribute. This is done so that you can control which methods are callable since the client code can be declarative and dynamic and so the control can create a client class wrapper for only the exposed methods.

On the client you now need to hook up the call to some sort of client side action. Let's use a textbox and button for our Helloworld sample:

Enter your name:
<asp:TextBox ID="txtName" runat="server" Width="178px">John Doe</asp:TextBox>
<input id="btnSubmit" type="button" value="Say Hello" 
                   onclick="HelloWorld();" />

Next create the HelloWorld function that handles this operation (you could also do this directly in the onclick handler, but i like to break it out for clarity):

function HelloWorld()
{
    // *** 'Proxy' is a the generated object with the same name as the wwMethodCallback ID.
    // *** This object is static and accessible anywhere within the page to call the server
    // *** methods with.   
    Proxy.HelloWorld($w("txtName").value,Helloworld_Callback,OnPageError);
}
function Helloworld_Callback(Result)
{
    // *** Simple Alert
    alert(Result);
}
function OnPageError(Result)
{
    alert("*** OnPageError captured a CallbackMethod error:\r\n\r\n" + Result.message)
}

So the onclick fires the Helloworld function. This function is the kick off point for the AJAX callback and it uses the Proxy class that was generated by the wwMethodCallback control. wwMethodCallback generates a proxy object instance with the same name as the control (hence 'Proxy' for the classname) which can then be used to call the HelloWorld method directly. Each client proxy method matches the server method's parameter signature, plus it adds two parameters for the Callback handler when the call completes and an error handler if the call fails.

If the call succeeds the callback handler - Helloworld_Callback here - is called with the result value. The result value is typed the same as the return value of the server method. So if you return a string a string is passed. If you return an int it'll be a JavaScript number. If you return an object you get a JavaScript object. On success the result is passed and you can use the result as you want.

If the callback fails - due to invalid signatures, a method execution error, or connectivity or other HTTP problem the error handler is called instead. This handler is passed a single error object which has a message property that contains error information.

That's really all there's to it. It's extremely easy to implement this functionality!

Calls are asynchronous by default

All remote method calls are made asynchronously. This means when you call the method in question control returns to you immediately but you don't get a result back. All results are returned only to callback handlers.

Multiple callbacks can be made on the same control simultaneously. For example:

Proxy.HelloWorld($w("txtName").value,Helloworld_Callback,OnPageError);
Proxy.HelloWorld2($w("txtName2").value,Helloworld_Callback,OnPageError);

will result in two calls that are executing basically side by side, and there's no guarantee that one or the other will execute first.