AJAX capabilities in the Web ADF

In this topic

• About AJAX capabilities in the Web ADF
• Client-side and server-side solutions
• Callback result framework component areas
• JavaScript libraries
• Toolbar control and tool and command interfaces
• Public callback properties
• Custom classes

ASP.NET supports both synchronous and asynchronous communication with Web applications. The ArcGIS Web Application Developer Framework (ADF) controls can leverage two AJAX patterns packaged for use with ASP.NET: ASP.NET script callbacks and ASP.NET AJAX. Both AJAX patterns are provided by Microsoft to enhance the Web application developer and user experience. It is recommended that you become familiar with AJAX and ASP.NET technologies and concepts before proceeding with this topic.

As a Web ADF developer, you can select the AJAX pattern to use in your Web application. At ArcGIS 9.2, the Web ADF supported the ASP.NET script callback framework only. As a result, many existing applications are built on the callback model for asynchronous communication. This model remains valid and supported at ArcGIS 9.3. However, the ArcGIS 9.3 Web ADF also supports the ASP.NET AJAX solution from Microsoft.

The Web ADF controls are designed to use only one model for asynchronous communication per page. The presence of an ASP.NET AJAX ScriptManager control on a page dictates which model is used. If a ScriptManager control is present, the Web ADF controls use the ASP.NET AJAX partial postback model. If a ScriptManager control is not present on the page, the Web ADF controls use the ASP.NET script callback model.

ASP.NET AJAX provides both client-side and server-side solutions. In both cases, Web ADF client-side JavaScript libraries use ASP.NET AJAX client-side JavaScript libraries to provide a foundation for a comprehensive scriptable environment for AJAX solutions in a browser. On the server, Web ADF components can use ASP.NET AJAX components and their framework to work with the partial postback pattern.

The client and server side solutions are illustrated in the following graphic:

In most cases, working with AJAX capabilities in the Web ADF will differ depending on the AJAX solution you use. However, there are some common components and concepts shared by both. In general, any client-server interaction in the Web ADF involves an action request and response, followed by subsequent asynchronous requests to handle changes made during the initial postback. Typically, an action request is initiated by a user action in the browser (for example, zooming in on a map). If the action request is sent to the current page, it can be a synchronous full postback, an asynchronous partial postback, or a callback (also a type of postback).

The action request process is illustrated in the following graphic:

Each postback to a page in a Web application iterates through the page lifecycle. The type of postback dictates the lifecycle events and the response content that are triggered. Subsequent requests can be asynchronous and can iterate through the page lifecycle or request a remote resource, such as an image. As a result, a single user action in the browser can generate multiple requests, some of which iterate through the page lifecycle. For a postback to a page, iterating through the page lifecycle is required because the page and its contents must be reconstructed to process a request.

Regardless of which Microsoft AJAX pattern is used, the Web ADF includes an internal framework to synchronize changes to the state of client and server content in an asynchronous environment. This callback result framework is founded on Web ADF callback results, which are messages generated on the server that communicate changes to the client. The following logical areas in the Web ADF are integral to leveraging the callback result framework and Microsoft AJAX solutions. You can use one or more of these component areas to create and manage custom Web ADF AJAX solutions.

At ArcGIS 9.2, the Web ADF included JavaScript libraries built on the ASP.NET callback framework JavaScript. In addition, the Web ADF JavaScript was not designed to be customized or used publicly. 

At ArcGIS 9.3, the ASP.NET AJAX JavaScript libraries have been leveraged to enhance Web ADF capabilities with a public Web ADF JavaScript library. As a result, Web ADF applications can take advantage of pure client scripting solutions to enhance the usability and performance of the application. The ASP.NET AJAX JavaScript libraries are utilized regardless of the AJAX solution that is used on the server (for example, when using the callback model). This is possible because the AJAX Control Toolkit is included with the Web ADF. The AJAX Control Toolkit, packaged as a single assembly, provides a consistent, Microsoft supported, public platform on which to deploy ASP.NET AJAX solutions. It contains the core client and server components included with ASP.NET AJAX (extensions) as well as other components that support the usability and distribution of Web solutions built on ASP.NET AJAX.

By default, the Web ADF JavaScript library consists of a set of JavaScript files, embedded as resources with the Web ADF controls. Only those JavaScript files required to support the Web ADF controls in the application are streamed to the browser client. 

From a response perspective, the ESRI.ADF.System.processCallbackResult function is very important. Most Web ADF controls generate callback results when their state changes on the server. The ESRI.ADF.System.processCallbackResult function parses and processes callback results from Web ADF controls and updates their content on the client at run time.

The Toolbar control provides a prepackaged framework for adding client-side tools that interact with Web ADF controls. All you need to do is create a class on the server that implements the appropriate interface (depending on the type of toolbar item), and add that class to the toolbar. Implementation code in the toolbar item class can interact and change any server-side resource, and the postback is managed for you. This is the easiest way to access the AJAX capabilities of the Web ADF but requires that you work within the context of the Toolbar control.

All Web ADF controls implement the System.Web.UI.ICallbackEventHandler and System.Web.UI.IPostBackEventHandler interfaces, which handle asynchronous requests and generate responses. When a Web ADF control is modified on the server, it generates a response that tells the client how to update the control. To do this, each Web ADF control maintains a CallbackResults property. The CallbackResults property stores callback results that the control sends to the client browser to be processed by the processCallbackResult() function. Callback results are messages serialized using JavaScript Object Notation (JSON), an efficient, human-readable, data exchange format.

To interact with Web ADF controls other than the Toolbar control and toolbar items, you likely will need to retrieve messages from the CallbackResults property and return them to the client. When implementing ICallbackEventHandler to support the callback model, messages are returned from the GetCallbackResult() method. When implementing IPostBackEventHandler to support the partial postback model, messages are added as data items to a ScriptManager in the RaisePostBackEvent() method.

The CallbackResults property on a Web ADF control returns a CallbackResultCollection. This collection can be modified to include custom CallbackResult objects. Custom CallbackResult objects can be used to interact with non-Web ADF content on the Web page (for example, HTML table, GridView, images, and text). The main benefit of this process is that you can use the existing Web ADF JavaScript libraries to change non-Web ADF content on the client rather than writing your own JavaScript.

Choosing the AJAX solution that works best for your application depends on business rules, application requirements, and technical expertise. Both ASP.NET script callbacks and ASP.NET AJAX are supported equally. In either case, it is important to understand the content and capabilities of the Web ADF callback results framework. Once you decide which AJAX solution you'll use with the Web ADF controls in a Web page, underlying techniques for working the AJAX capabilities of the Web ADF will differ, such as the techniques for packaging callback results in an asynchronous Web response.

For more information, see the "See Also" topics.