ASP.NET AJAX partial postback solutions

Summary This topic provides a detailed discussion on utilizing and extending Asynchronous JavaScript and XML (AJAX) capabilities of the Web Application Developer Framework (ADF) in an ASP.NET partial postback solution. This topic builds on information presented in the AJAX and ASP.NET and Working with AJAX capabilities of the Web ADF topics. You should be familiar with the technologies and concepts presented in both topics before proceeding.

In this topic

About ASP.NET AJAX partial postback solutions

Web ADF controls utilize Microsoft ASP.NET AJAX client and server libraries for AJAX solutions. The level to which ASP.NET AJAX is utilized depends on which postback model is leveraged in a Web page. Client implementation for both postback models is the same—Web ADF JavaScript builds on the ASP.NET AJAX JavaScript library to provide pure client scripting capabilities and client-server synchronization.
Server implementation determines how client-server synchronization is achieved. For Web ADF partial postback solutions, Web ADF server controls build on ASP.NET AJAX server controls and capabilities to manage the asynchronous exchange of data via a partial page postback. Web ADF controls use the partial postback solution if the ASP.NET AJAX ScriptManager control is present on the same page. With this in mind, two characteristics of ASP.NET AJAX are important to understand from the perspective of the Web ADF. First, controls that initiate a partial postback (called triggers), must implement IPostBackEventHandler, IPostBackDataHandler, or INamingContainer and must be registered with a ScriptManager. Second, partial updates to page content can be managed using ASP.NET AJAX UpdatePanel controls, dynamic script blocks, or data items. 
The ScriptManager must be the first control on the page.
At a minimum, Web ADF controls implement IPostBackEventHandler and register themselves with the current ScriptManager on the page, triggering a partial postback by default. When a Web ADF control triggers a partial postback, Web ADF JavaScript uses the ASP.NET AJAX JavaScript library to add an event handler. The JavaScript event handler listens for the page loading event for the duration of the postback. During postback processing on the server, updates to Web ADF controls are managed by adding CallbackResults as data items to the partial postback response. When the response is returned to the client browser, the page loading event handler processes the data items and updates the Web ADF content. The logic to update Web ADF controls is included with both Web ADF JavaScript and server control implementation.

UpdatePanel and Web ADF controls

The ASP.NET AJAX UpdatePanel control provides a convenient means for triggering updates and updating page content via an asynchronous partial postback. Postbacks triggered by Web controls in an UpdatePanel are asynchronous partial postbacks by default. In addition, Web controls outside an UpdatePanel can trigger an asynchronous postback to update all content inside an UpdatePanel.
If outside an UpdatePanel, controls must explicitly register with the ScriptManager to trigger a partial postback. The following code shows how this registration occurs during the page load event for an ASP.NET Button control with the id Button1:
[C#] 
protected override void OnLoad(EventArgs e)
{
    base.OnLoad(e);
    ScriptManager scriptManager1 = ScriptManager.GetCurrent(Page);
    if (scriptManager1 != null)
    {
        scriptManager1.RegisterAsyncPostBackControl(Button1);
    }
}
Web ADF JavaScript and server control implementations include the logic necessary to register with the ScriptManager, trigger postbacks, and update content within a partial postback solution. As a result, Web ADF controls do not require the use of an UpdatePanel. Web ADF controls will function within an UpdatePanel and operate as a trigger to update content in an UpdatePanel. However, using a Web ADF control in an UpdatePanel can be inefficient and is not recommended for optimum performance.
The reason for this inefficiency is the technique used by the UpdatePanel to update content. During a partial postback, content in an UpdatePanel is completely rerendered. As a result, the rerendered content of a Web ADF control—which includes the Hypertext Markup Language (HTML) content, JavaScript references, and JavaScript function calls—is returned to the browser.
When outside an UpdatePanel, Web ADF controls operate with optimum efficiency. During a partial postback, Web ADF CallbackResults are generated on the server, serialized to JavaScript Object Notation (JSON), and registered with a ScriptManager as data items. On the client, Web ADF-specific data items are processed by Web ADF JavaScript and control content is updated. Thus, instead of completely rerendering a Web ADF control, specific updates are defined within the context of ASP.NET AJAX data items.
The following partial postback scenarios build on this architecture to create efficient custom solutions. In both scenarios, the Web ADF CallbackResult and CallbackResultCollection classes are integral to synchronizing changes to Web ADF controls on the server with the client browser.

Web ADF components initiate the partial postback

The following diagram illustrates the following processes:
  1. How a Web ADF control on the client (rendered using HTML and JavaScript in the client browser) initiates a partial postback request
  2. How a Web ADF control handles the postback on the server, which generates one or more Web ADF CallbackResults
  3. How the ASP.NET AJAX library processes the partial postback and calls an event handler added by Web ADF JavaScript to parse Web ADF CallbackResults as data items in the response
The important point here is that the Web ADF control that initiated the partial postback returns information that can be used to update itself and other content on the page. The Web ADF control (the trigger in this example) maintains a collection of Web ADF CallbackResults that are included in the partial postback response generated by the ASP.NET AJAX ScriptManager control.
The CallbackResults collection can include CallbackResult instances from the following sources:
  • The trigger generates CallbackResults
  • Custom CallbackResults can be created and added to the trigger's CallbackResults collection
  • The CallbackResults collections for other Web ADF controls can be copied to the trigger's CallbackResults collection
The exception in this situation is CallbackResults that are generated by Web ADF controls that maintain a property relationship with the trigger are added automatically.
For example, assume a page contains a Map and a Toc control where the Toc control is buddied with the Map. At runtime, a user action on the Map causes a scale change that changes the visibility of a layer in the Map and Toc. When the partial postback response is generated, the CallbackResults collection for the Map (the trigger in this case) includes CallbackResults for the Toc, so both are included in the response. You do not need to copy CallbackResults from the Toc to the Map; the Web ADF architecture does that automatically.
The Web ADF control overview diagram provides a general guide to potential relationships between Web ADF controls. In this scenario, the trigger's CallbackResults collection is registered as a data item with the ScriptManager control and processed using Web ADF JavaScript on the client—no explicit work is required to add a client event handler or register CallbackResults as data items on the server.
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, CallbackResults included in the partial postback are managed for you, so it's relatively easy to incorporate and execute custom code solutions in a Web ADF without explicitly creating or managing client or server side components.
This scenario also includes working with events on Web ADF controls. When a Web ADF control initiates a partial postback, event handlers on Web ADF controls can generate CallbackResults to reflect changes in the control. CallbackResults associated with the Web ADF control that initiated the partial postback when the event occurred are automatically included in the partial postback. Changes to other controls or browser content can be packaged with the partial postback by adding Web ADF control CallbackResults or custom CallbackResults to the Web ADF control acting as the trigger for the postback. The topic How to add custom tool and manage callbackresults from other Web ADF Controls demonstrates this scenario.

Non-Web ADF components initiate the partial postback

The following diagram illustrates how to work with Web ADF controls when a partial postback is generated by non-Web ADF content in the browser:
The following options for updating Web ADF content are available:
  • UpdatePanels
  • Dynamic script blocks
  • Data items
These options are standard patterns available for ASP.NET AJAX solutions.

UpdatePanels

Web ADF controls can reside in UpdatePanels and operate successfully. When the UpdatePanel is updated during a partial postback, its contents are completely rerendered. Since Web ADF controls include a JavaScript application programming interface (API) to synchronize updates between client and server, updating Web ADF controls in an UpdatePanel is unnecessary and inefficient. The only thing necessary to update Web ADF controls on the client are the CallbackResults they generate on the server. CallbackResults are processed via the Web ADF JavaScript ESRI.ADF.System.processCallbackResult() function. CallbackResults can be inserted into the partial postback response as dynamic script blocks or data items.

Dynamic script blocks

The ASP.NET AJAX ScriptManager enables you to register a block of JavaScript, constructed on the server, to be executed on the client. Any valid JavaScript can be included in the script block. For Web ADF controls, the script block calls the ESRI.ADF.System.processCallbackResult() function and passes a collection of Web ADF CallbackResults as an input parameter.
An UpdatePanel must be present on the page to use dynamic script blocks. The UpdatePanel can be empty.
The Following example code is executed on the server during a user action, such as clicking a button or selecting a drop-down list item. The extent for a Web ADF Map control is set, which generates one or more CallbackResults stored by the Map via the CallbackResults property. The ToString() method on Web ADF controls has been overridden to return the respective control's CallbackResults as a JSON serialized string (a call to ToString() is not necessary). Web ADF CallbackResults can be packaged in a single CallbackResult collection before being converted to a string and included in the script block. For example, if a Web ADF control changed during the postback or a custom CallbackResult was created, copy or add the CallbackResults to the Map.
[C#] 
. . . string jsProcessCallbackResult = string.Format(
    "ESRI.ADF.System.processCallbackResult('{0}');", Map1.CallbackResults.ToString()
    .Replace("\\", "\\\\"));
ScriptManager.RegisterClientScriptBlock(Page, sender.GetType(), "changeextent",
    string.Format(jsProcessCallbackResult, Map1.CallbackResults), true);
[VB.NET] 
. . .
Dim jsProcessCallbackResult As String = String.Format("ESRI.ADF.System.processCallbackResult('{0}');",
Map1.CallbackResults.ToString().Replace("\", "\\"))
ScriptManager.RegisterClientScriptBlock(Page, sender.GetType(), "changeextent", String.Format(jsProcessCallbackResult,
Map1.CallbackResults), True)
If you're a server control developer, and you want to create a control that works for both callbacks and partial postbacks, you can check if a ScriptManager is present on the page using the GetCurrent() static method and return an instance. If you are a page developer, you'll know when a ScriptManager is on the page and you'll know its id, so interrogating the page for a ScriptManager is unnecessary.
The previous code example contains a Replace statement to change the escape characters in ADF callback results. This is a limitation of dynamically executed JavaScript, a characteristic of a client script block, and JSON, a format used by callback results. It does not affect strings passed to JavaScript functions on the client, as shown in the next option, data items.
The escape sequence is different for C# and VB.NET.
This technique presents the following benefits:
  • Web controls do not need to be completely rerendered, as is the case with an UpdatePanel
  • No custom client-side code is necessary to process the Web ADF CallbackResults
One potential drawback is that all registered script blocks persist in browser memory. As a result, the amount of content in a script block, the number of script blocks, and the expected duration of a browser session can cause browser memory to reach an unacceptable limit.

Data items

The ASP.NET AJAX ScriptManager enables you to register items of data, packaged as strings on the server and processed on the client. The strings can be formatted using JSON. Since Web ADF CallbackResults are formatted using JSON, they can be packaged as a data item and included in a partial postback response.
The ASP.NET AJAX client API (JavaScript library) includes the ability to manage event handlers on client-side JavaScript objects. One object type, the PageRequestManager class, manages partial page updates in the browser and maintains a pageLoading event, which is raised after the response from the server to an asynchronous postback is received but before any content on the page is updated. The pageLoading event can be used to capture data item content included in a partial postback response for use in the client browser. These two options and some sample code are provided here to illustrate this technique:
  • Register Web ADF CallbackResults as a data item on the server
    During a partial postback on the server, register a data item. The first parameter to the RegisterDataItem() method is the control associated with the item. In this case, the page is used because it provides a generic high-level control by which any Web ADF CallbackResults can be registered. The use of the Page control is arbitrary, any unique string can be used.

    The second parameter is the data item string itself. Web ADF CallbackResults are JSON-formatted strings designed to be processed by the Web ADF JavaScript ESRI.ADF.System.processCallbackResult() function. As a result, the string representation of a CallbackResults collection is provided as the second parameter to the function.

    The third parameter defines whether the data item is JSON serialized. If the data item is a JSON serialized string (true) it's designed to be executed directly in the browser as dynamic JavaScript. If the data item is used as a string, such as passed as a parameter to a function, it will not be a JSON serialized string. In this case, callback results are a JSON-formatted string to be passed to the ESRI.ADF.System.processCallbackResult() function. The topic How to manage callback content for Web ADF control when partial postback is initiated by Non-Web ADF control demonstrates this scenario
See the following code:
[C#] 
ScriptManager1.RegisterDataItem(Page, Map1.CallbackResults.ToString(), false);
  • Add a custom JavaScript function to process the CallbackResults on the client and send them to the processCallbackResults() function
    The JavaScript content can be inserted into a page manually at design time after the form containing the ScriptManager control is loaded or inserted into the page as a startup script using server-side code. In the following code, the JavaScript is inserted into the body of the page after the closing form tag. The code adds a new event handler function for the page loading event and retrieves the data items based on a unique id (in this example, the client id of the page). In this case, the data item is a string representing a callback result collection. It is passed directly to the ESRI.ADF.System.processCallbackResult() function.
[JavaScript] 
 < script > Sys.Application.add_init(onInitFunction);

// Called once during application initialization.
function onInitFunction(){
    Sys.WebForms.PageRequestManager.getInstance().add_pageLoading
        (AsyncResponseHandler);
}

// Called whenever a response to a partial postback is processed on the client.
function AsyncResponseHandler(sender, args){
    var dataItems = args.get_dataItems();
    if (dataItems['__Page'] != null)
        ESRI.ADF.System.processCallbackResult(dataItems['__Page']);
}

 <  / script >
Utilizing data items is a common scenario for developers who want to interact with Web ADF controls when partial postbacks are triggered by non-Web ADF controls on the page.

Interacting with Web ADF controls and capabilities

To interact with Web ADF controls and capabilities via an ASP.NET AJAX partial postback on the server, use the following options:
  • If the Web ADF control triggers the partial postback, use the existing Web ADF toolbar framework or implement your own solution to manage CallbackResults via the collection on the Web ADF control trigger. The topic How to add a custom tool and manage callback results from Web ADF Controls demonstrates this scenario.
  • If a non-Web ADF control triggers the partial postback, provide a mechanism for packaging and directing CallbackResults to the appropriate Web ADF JavaScript function. In addition, you can leverage the Web ADF to update non-Web ADF content on the page without completely rerendering the content (as in an UpdatePanel) or writing custom JavaScript code.


See Also:

AJAX and ASP.NET
AJAX capabilities in the Web ADF