Using wwCallbackHandler with REST Calls

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:

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:

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:

The method in the service handler to call.

The number of JSON parameters passed

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:"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.

  Last Updated: 12/29/2007 | © West Wind Technologies, 2008