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. Become familiar with the technologies and concepts presented in both topics before proceeding with this one.

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

Typical situations

About ASP.NET script callback solutions

The following properties of ASP.NET script callbacks are important to understand from the perspective of the Web ADF:

The callback message for 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 to be processed by Web ADF JavaScript.
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. For more information, see the callback walkthrough in AJAX and ASP.NET.

The following determines 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 returned string is the ID of a control on the page. The following code example determines if a postback is a callback, and which server-side control processes the callback:

[C#]


        if (Page.IsCallback)
{
    string control_id = Request.Params["__CALLBACKID"];
    Control control = Page.FindControl(control_id);
}

Custom callback scenarios

The following describes three scenarios you can use to customize the Web ADF and utilize its implementation of the ASP.NET 2.0 callback model. In the following 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 illustration shows the following events:

Web ADF control on the client (rendered using Hypertext Transfer Protocol [HTML] and JavaScript in the client browser) initiates the callback request.
Web ADF control processes the request on the server and generates one or more Web ADF CallbackResults.
Client processes the callback response using Web ADF JavaScript 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.

Illustration of the most common scenario for leveraging Web ADF AJAX capabilities.

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 is 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 occurs 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 illustration shows 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 that you can use the CallbackResult and CallbackResultCollection classes to construct the response string. The easiest way to accomplish this is to create a CallbackResultsCollection or work with a Web ADF control's callback result collection, then 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 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 illustration shows this scenario ("Other Web control" represents the page):

Illustration of using Web ADF JavaScript to process callback response content while triggering the callback request in a non-Web ADF control.

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 illustration shows 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 can contain CallbackResult formatted strings for Web ADF content.

When a client script reference is generated on the server, the client-side JavaScript function that handles the callback response is defined. For example, the following code example 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 the previously referenced topic, AJAX and ASP.NET.

In this scenario, however, the value is a developer-defined JavaScript function (in the code example, "customFunction"). If Web ADF CallbackResult formatted strings are returned to the custom function, parse the CallbackResult related content and forward it to the Web ADF processCallbackResult() function. See the following illustration:

Illustration showing how to use non-Web ADF components to generate and process callbacks on the client and server.

This scenario is not common but is technically possible, which is why it is 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, 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, use the Web ADF JavaScript libraries. To process the callbacks on the server, use the following options:

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