Working with AJAX capabilities of the Web ADF

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

As a Web ADF developer, you have the option to select which AJAX pattern you will utilize in your Web application.   In version 9.2, the Web ADF only supported the ASP.NET script callback framework.  As a result, many existing applications have been built on the callback model for asynchronous communication.  This model remains valid and supported in 9.3.  However, the 9.3 Web ADF also supports the latest Microsoft AJAX solution, ASP.NET AJAX.   The Web ADF controls are only designed to use one model for asynchronous communication per page.  The presence of an ASP.NET AJAX ScriptManager control in a page dictates which model will be used.  If a ScriptManager is present, Web ADF controls will use the ASP.NET AJAX partial postback model.  If a ScriptManager is not present in the page, the Web ADF controls will use the ASP.NET script callback model.   Note, the ScriptManager must be the first control in the page. 

ASP.NET AJAX provides both a client and server side solution.  In all 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 within a browser.   On the server, Web ADF components have the option of utilizing ASP.NET AJAX components and their framework to work with the partial postback pattern.   




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

 

Each postback to a page in a Web application will iterate through the page lifecycle.   The type of postback will dictate the which lifecycle events are triggered and the response content.  Subsequent requests can be asynchronous and may iterate through the page lifecycle or just request a remote resource, like an image.   As a result, a single user action in the browser may 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 framework, termed the "callback result framework", is founded on Web ADF "callback results" which are messages generated on the server to communicate changes with the client.   The following logical areas in the Web ADF are integral to leveraging the callback result framework and Microsoft AJAX solutions.  As a developer, you can utilize one or more of these component areas to create and manage custom Web ADF AJAX solutions.  

• JavaScript libraries to manage postbacks on the client
  
  In version 9.2, the Web ADF included a set of JavaScript libraries built on the ASP.NET callback framework JavaScript.  In addition, the Web ADF JavaScript was not designed to be utilized publicly or customized.  In 9.3 this has changed.  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 used on the server (for example, even 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 includes the core client and server components included with ASP.NET AJAX (Extensions) as well as other components to 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 response perspective, the ESRI.ADF.System.processCallbackResult function is most important.  Most Web ADF controls generate callback results when their state changes on the server.    The ESRI.ADF.System.processCallbackResult function is designed to parse and process callback results from Web ADF controls and update their content, at runtime, on the client.
  
• Tool/command interfaces accessed via a Toolbar control to easily process callbacks on the server
  
  The Toolbar control provides a prepackaged framework for adding client-side tools to interact with Web ADF controls.  You only need to 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 tap into the AJAX capabilities of the Web ADF, but requires you to work within the context of a Toolbar control. 
  
• Public callback properties on each Web ADF control
  
  All Web ADF controls implement the System.Web.UI.ICallbackEventHandler and System.Web.UI.IPostBackEventHandler  interfaces handle asynchronous requests and generate responses.   When a Web ADF control is modified on the server, it generates a response to tell the client how to update the control.   To do this, each Web ADF control maintains a CallbackResults property.  The CallbackResults property stores a collection of callback results the control will send to the client browser to be processed by the processCallbackResult() function.   Callback results are messages serialized using JSON , JavaScript Object Notation, an efficient, human-readable, data exchange format.  If you want to interact with a Web ADF control apart from the Toolbar control and toolbar items, you often 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.    
  
• Custom classes to create and manage callback messages     
  
  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 in the Web page (e.g. HTML table, GridView, images, text).    The main benefit being that you can use the existing Web ADF JavaScript libraries to change non-Web ADF content on the client instead of writing your own JavaScript.  
  

Choosing which AJAX solution works for you depends on business rules, application requirements, and technical expertise.  Both ASP.NET script callbacks and ASP.NET AJAX are supported equally.   In either case, is important to understand the content and capabilities of the Web ADF callback results framework.  It is discussed in detail in the topic Working with CallbackResults .  Once you decide which AJAX solution you will use with Web ADF controls in a Web page, underlying techniques for working the AJAX capabilities of the Web ADF will differ.   This includes the techniques for packaging callback results in an asynchronous Web response.  Each AJAX pattern is presented in a separate topic: ASP.NET callback solutions and ASP.NET AJAX partial postback solutions .