AJAX capabilities in the Web ADF

---

ASP.NET supports both synchronous and asynchronous communication with Web applications. The ArcGIS Web Application Developer Framework (ADF) controls can leverage the following Asynchronous JavaScript and XML (AJAX) patterns packaged for use with ASP.NET:

Both AJAX patterns are provided by Microsoft to enhance the Web application developer and user experience. Become familiar with AJAX and ASP.NET technologies and concepts before proceeding with this topic. For more information, see Working with AJAX and ASP.NET.

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 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 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 Web 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 shown in the following illustration:

In most cases, working with AJAX capabilities in the Web ADF differs 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 Web 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 shown in the following illustration:

Each postback to a page in a Web application iterates through the page's life cycle. The type of postback dictates the life cycle events and the response content that are triggered. Subsequent requests can be asynchronous and can iterate through the page's life cycle or request a remote resource, such as an image. As a result, a single user action in the Web browser can generate multiple requests, some of which iterate through the page's life cycle. For a postback to a page, iterating through the page's life cycle 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 cannot 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. For more information, see 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 Web 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. Create a class on the server that implements the appropriate interface (depending on the type of toolbar item), then 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 Web browser to be processed by the processCallbackResult() function. Callback results are serialized messages that use JavaScript Object Notation (JSON), an efficient, human-readable, data exchange format. For more information, see Introducing JSON.

To interact with Web ADF controls other than the Toolbar control and toolbar items, 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, Hypertext Markup Language [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 will use with the Web ADF controls in a Web page, underlying techniques for working the AJAX capabilities of the Web ADF differs, such as the techniques for packaging callback results in an asynchronous Web response.