ASP.NET script callback solutions

Summary This topic discusses utilizing and extending Asynchronous JavaScript and XML (AJAX) capabilities of the Web Application Developer Framework (ADF) in an ASP.NET script callback solution. This topic builds on information presented in the AJAX and ASP.NET and AJAX capabilities in the Web ADF topics. You should be familiar with the technologies and concepts presented in both topics before proceeding with this one.

In this topic

About ASP.NET script callback solutions

Two properties of ASP.NET script callbacks are important to understand from the perspective of the Web ADF. First, the callback message for both the request and response can only contain string content. The format of the Web ADF callback message is serialized using JavaScript Object Notation (JSON), a light-weight text-based data transmission format. The Web ADF defines a set of parameters to package information in the JSON formatted response message, explicitly designed to be processed by Web ADF JavaScript. Second, only one control on the server is responsible for processing a callback request and generating a response. Any ASP.NET server control can implement the System.Web.UI.ICallbackEventHandler interface and be utilized for processing callbacks (a Page is a type of server control). All Web ADF controls implement the ICallbackEventHandler interface and can process a callback request and generate a callback response.
A callback request is initiated in a browser client with a call to the WebForm_DoCallback() function. The WebForm_DoCallback() function is included with JavaScript embedded in the ASP.NET System.Web.dll assembly and is available when a client script reference is registered (see the callback walkthrough in the AJAX and ASP.NET topic).
How do you know which control is responsible for processing the callback? On the client, the first parameter in the WebForm_DoCallback() JavaScript function defines the id of the server side control to process the callback. In the server application, you can interrogate the current Request object for the parameter "__CALLBACKID". The string returned is the id of a control in the Page. The following code provides an example to determine if a postback is a callback, and which server-side control will process the callback:
[C#] 
if (Page.IsCallback)
{
    string control_id = Request.Params["__CALLBACKID"];
    Control control = Page.FindControl(control_id);
}

Custom callback scenarios

This section describes three scenarios you can use to customize the Web ADF and utilize its implementation of the ASP.NET 2.0 Callback model. In these scenarios, the Web ADF CallbackResult and CallbackResultCollection classes are integral to synchronizing changes to the Web ADF controls on the server with the client browser.

Using Web ADF components to generate and process callbacks on the client and server

The following diagram illustrates the following events:
  1. A Web ADF control on the client (rendered using HTML and JavaScript in the client browser) initiates the callback request.
  2. A Web ADF control processes the request on the server and generates one or more Web ADF CallbackResults. 
  3. The client processes the callback response using Web ADF JavaScript designed for Web ADF CallbackResult strings.
The most important characteristic of this scenario is that the Web ADF control is responsible for processing the callback and generating a response message in a format that Web ADF JavaScript can use, namely the format defined by Web ADF CallbackResult classes and collections. The Web ADF control creates the callback response; no explicit work is required by the developer to construct or return the callback response.
This is the most common scenario for leveraging Web ADF AJAX capabilities. It includes the pattern for creating custom toolbar items that execute server-side logic using the Web ADF toolbar architecture. When using the Web ADF toolbar, the ASP.NET callback framework is managed for you, so it's relatively easy to incorporate and execute custom code solutions in the Web ADF without explicitly managing callback messages or classes.
The Web ADF control on which the event occurrs is responsible for generating the callback response, but changes to other controls or browser content can be packaged with the response. The Web ADF control generating the callback response maintains a collection of CallbackResult objects (a CallbackResultCollection) accessible via the CallbackResults property.
Callback results generated by other Web ADF controls can be added to the callback results of the Web ADF generating the response. In addition, custom CallbackResult objects can be created and added to the collection.

Using non-Web ADF content to generate and process callback requests and Web ADF JavaScript to process callback response on the client

The following diagram illustrates how a callback request can be generated by non-Web ADF content on the client and be processed by a non-Web ADF control on the server. Since Web ADF JavaScript is responsible for processing the callback response, the response string needs to be in a format the processCallbackResult() function recognizes. The format is defined by the CallbackResult class. This means you can use the CallbackResult and CallbackResultCollection classes to construct the response string. The easiest way to accomplish this is to either create a CallbackResultsCollection or work with a Web ADF control's callback result collection and add CallbackResult objects to it.
Every Web ADF control maintains a collection of CallbackResult objects available via the CallbackResults property. For example, a simple Hypertext Markup Language (HTML) input button triggers a JavaScript call to generate a callback request to the server specifying that the Page process the callback. The ICallbackEventHandler interface has been implemented on the Page, so the RaiseCallbackEvent() and GetCallbackResult() methods are called during request processing (the Page lifecycle). In the process, the Web ADF Map control is changed and a GridView of data needs to be rendered on the client.
In the GetCallbackResult() method in the Page, a new CallbackResultCollection object is created and the CallbackResults from the Map control are copied to it (via the CopyFrom() method). A custom CallbackResult object is created to update the HTML content that represents the GridView on the server. The object is then added to the CallbackResultCollection (via the Add() method). The callback response string is returned from the GetCallbackResult() method by converting the CallbackResultCollection to a string (via the ToString() method). The Web ADF processCallbackResult() JavaScript function processes the callback results in the string and updates the appropriate content on the client. The following diagram illustrates this scenario (the "Other Web control" represents the Page):
This can be a common scenario for developers who want to leverage Web ADF JavaScript to process callback response content while triggering the callback request in a non-Web ADF control. 

Using non-Web ADF components to generate and process callbacks on the client and server

The following diagram illustrates the same behavior discussed in the previous scenario, except the callback response is processed by a non-Web ADF JavaScript function on the client. The difference is that you are responsible for handling the raw callback response string on the client, which may contain CallbackResult formatted strings for Web ADF content. When a client script reference is generated on the server, the client-side JavaScript function that will handle the callback response is defined. For example, the following code generates a line of JavaScript that can be called to initiate a callback request on the client at runtime:
[C#] 
string m_ADFCallbackFunctionString = Page.ClientScript.GetCallbackEventReference
    (this, "message", "customFunction", "context", "handleError", true);
The string returned from the GetCallbackEventReference method contains the call to the ASP.NET JavaScript function WebForm_DoCallback() with the provided parameters. The third parameter defines the JavaScript function to process the callback response string. In the previous scenario, the value is processCallbackResult, which is the Web ADF JavaScript function to process callback response strings in the format defined by CallbackResults. For more information about GetCallbackEventReference, see AJAX and ASP.NET.
In this scenario, however, the value is a developer-defined JavaScript function (in the example code, "customFunction"). If Web ADF CallbackResult formatted strings are returned to the custom function, you must parse the CallbackResult related content and forward it to the Web ADF processCallbackResult() function.
This scenario is not common but is technically possible, which is why it's presented here. The primary use-case for implementing this scenario is a business requirement to manually process the callback response string using custom JavaScript. If you have an existing JavaScript framework for processing callback response content and want to utilize Web ADF content, this scenario can provide a solution. Essentially you need to parse the Web ADF-specific content in the response string and pass it to the Web ADF processCallbackResult() JavaScript function.

Typical situations

To interact with Web ADF controls on the client using callbacks, the Web ADF JavaScript libraries must be used. To process the callbacks on the server, the following options are available:
  • Use the existing Web ADF toolbar framework
  • Implement a custom solution to manage callback content
  • Work with non-Web ADF content in your Web page


See Also:

AJAX and ASP.NET
AJAX capabilities in the Web ADF