wwCallbackHandler is a base JSON Service implementation that allows for remote method calls to be made against the server. The service returns JSON string results. To create a service you simply inherit from wwCallbackHandler (either in a .ASHX file or by creating a class and registering it as an HttpHandler) and setting [CallbackMethod] attributes on each of the methods of this class to expose those methods for remote access.

Any wwCallbackHandler derived 'service' can be easily accessed via REST calls simply by providing the proper QueryString or POST variables to the server. The handler makes the remote method call and returns a JSON formatted string in response.

The handler provides a mechanism for remote method calls by creating methods in a derived class that have a [CallbackMethod] attribute. Each of the methods is then exposed as a callback method that returns a JSON string representation of the method result value. Methods are called by name and MUST HAVE matching signatures to the client objects that are passed to them.

There are two call models available:

• Using raw AJAX calls
  You can also make direct AJAX call to the handler by passing a querystring of Method=MethodName. You can then also POST additional data either by simply sending a standard POST buffer that is then accessible from within the method. You can also pass a single JSON formatted object in the POST buffer. You can use wwScriptLibraries ajax functions or any external library like jQuery - your choice although the wwScriptLibrary calls are easiest.

• wwCallbackHandler Interface
  Compatible with the wwCallbackHandler server and wwMethodCallback client controls. Using POST or querystring you can specify the method to call and parameters to pass (as JSON strings). This mechanism works with the wwCallbackMethod server control and wwCallbackMethod client control. You drop a control and point at a URL and the control embeds a JavaScript proxy with the available methods. The data is sent using form a fixed set of form POST variables encoded for a method call with parameters.
  

Raw Ajax

Calling the handler with raw AJAX is easy as well. You simply call the service URL with the name of the method to invoke. There are several ways that you can specify 'parameters' to the method call:

• Raw POST buffer
  You can simply pass POST data to the server and do nothing else. In this scenario your server methods can have no parameters and purely rely on POST data to get its input data. You can then use Request.Form to read data out of the Post buffer.

  
  

• JSON Object in POST buffer
  You can pass a single serialized JSON object as a parameter and set the content type to application/json. The handler then converts your JSON object/value into a .NET type and passes it as a parameter to your method. The method must have a matching single parameter signature.
  

To make a callback with raw POST data using wwScriptLibrary's ajaxJson function:

ajaxJson("ClientCallbacks.ashx?Method=CallbackWithPost",
         "Name=Rick&Date=01/10/2008&Value=10",                 
         function(result) {alert("Message from Server:\r\n" + result) },
         function(error) { alert(error.message); }, true );

This passes the raw post data to the CallbackWithPost() method on the server. The server can then read the values with Request.Form["Name"], Request.Form["Date"] for example. You can really specify any kind of data you like here. Note the final parameter of true which indicates using raw POST data as opposed to a JSON object.

To pass JSON to the server and treat the value as a single parameter use code like the following:

ajaxJson("Chat/chatservice.ashx?Method=TestMethod",
             "Frightful ain't it", 
             function(result) {alert("Message from Server: " + result); },
             function(error)  {alert(error.message);}
             );

The parameter passed here is a string which is ajaxJson converts into a JSON string that is sent to the server.

To handle the server call implement a handler method like this:

[CallbackMethod]
public string TestMethod(string Message)
{
    return "You sent: " + Message + ". Time is: " + DateTime.Now;
}

You can pass exactly one parameter to the server, but the parameter can be a complex object. If necessary you can create a parameter object that contains multiple values. For example imagine this type:

public class Person
{
    public string Name = null;
    public int Value = 0;
    public DateTime Date = DateTime.MinValue;
}

and a callback method with this signature:

[CallbackMethod]
public string TestMethod2(Person person)
{
     return person.Name + " " + person.Value.ToString() + " " + person.Date;
}

To pass this value from the client:

ajaxJson("Chat/chatservice.ashx?Method=TestMethod2",
             { Name:"Rick", Value:"10", Date: new Date() }, 
             function(result) {alert("Message from Server:\r\n" + result) },
             function(error) { alert(error.message); } 
            );

The type doesn't have to match exactly - it'll read only matching properties from the JSON value so if you pass only Name (ie. { Name:"Rick" } ) and leave out the other object properties/fields the code still works.

ajaxJson is not required for this - you can use any AJAX client as long as the data that you are sending is properly JSON encoded.

wwCallbackMethod POST Data Interface

This mechanism relies on regular POST or Querystring values that define the method to call and the parameters to pass. The POST/querystring values for the callbacks are simple and only the following variables need to be supplied:

CallbackMethod
The method in the service handler to call.

CallbackParmCount
The number of JSON parameters passed

Parm1..n
0 or more parameters to be passed to the method called. Note the method must support these parameters. Parameters passed must be JSON encoded in the POST buffer. Values can be simple types or complex types as long as the server's input type matches the object signature.

GET Example:

http://site.com/app/jsonHandler.ashx?CallbackParmCount=2&CallbackMethod=HelloWorld&Parm1="Rick Strahl"&Parm2={"x":10,"y":20}

Note that parameters are JSON formatted (note the quotes around a string for example), so you can pass any JSON value to the server as long as it is calling a method that has a signature that expects that signature. Objects are matched based on properties/fields that are updated from matching properties.

Keep in mind that if you use the wwMethodCallback control or wwCallbackMethod client class the parameter encoding is handled for you automatically, so you don't need to manually create parameters.

var Callback = new wwCallbackMethod();
Callback.serverUrl = "jsonHandler.ashx";  
Callback.postbackMode = "PostMethodParametersOnly";  // default 
Callback.callMethod("HelloWorld",[Rick,new Date()],HelloWorld_Callback,onError);

Parameters are passed in an array as raw values (ie. string, date, object etc.) and the client code handles encoding these parameters into JSON and passing them to the server which decodes the JSON and passes the parameters as .NET values to the methods.