Documentation for: ASP.NET Ajax Version 1.0

This documentation is for a previous version. For the current released version, see the ASP.NET Ajax documentation on MSDN.

 

 

 

 

 

 

 

ASP.NET PageRequestManager Class Overview

Introduction

The PageRequestManager class in the Microsoft AJAX Library manages partial-page updates in the browser. When a page contains a ScriptManager control and one or more UpdatePanel controls, the page is automatically enabled for partial-page rendering. The PageRequestManager class exposes properties, methods, and events that enable you to customize partial-page updates with client script. The PageRequestManager class exposes a client page event model that you can use in a way similar to how you use the server page event model.

This topic contains:

Scenarios

You can enable partial-page updates by using the ScriptManager and UpdatePanel Web server controls. Partial-page updates require no client scripting. However, you can use the PageRequestManager class and client script when you want to do the following:

  • Control how multiple asynchronous postbacks are processed. The default behavior is that the last postback takes precedence. The PageRequestManager class enables you to give precedence to a specific postback and cancel others that are underway.

  • Provide visual cues or other notification to mark regions on the page that have been updated or created as a result of the last asynchronous postback. This can improve the user experience, especially in scenarios where multiple UpdatePanel controls are used.

  • Display status messages during asynchronous postbacks. If postbacks take a long time to process, you might want to show a progress indicator such as an animated image. You can also give the user the option to cancel the postback.

  • Provide custom error-message handling for partial-page updates. If an unexpected error occurs during an asynchronous postback, you can handle the error in client script.

  • Access the underlying request and response objects that are used for the asynchronous postback.

Features

Features of partial-page updates in the Microsoft AJAX Library include the following:

  • Client page life-cycle events that are raised at key times during partial-page updates.

  • Information about which UpdatePanel controls were deleted, updated, or created during an asynchronous postback.

  • Properties and methods that enable you to determine in client script whether the page is processing an asynchronous postback. You can also use these methods to stop an asynchronous postback that is underway or to cancel new postbacks.

  • Information about server data that is sent to controls that are not participating in partial-page updates.

Background

During partial-page updates initiated by asynchronous postbacks, the PageRequestManager class coordinates how the page content is incrementally updated in the browser. The UpdatePanel server control and PageRequestManager client class abstract much of the complexity of partial-page updates. When you use client script and members of the PageRequestManager class, you can customize the partial-page update behavior in the browser.

Partial-Page Update Event Handling

During page processing of both postbacks and asynchronous postbacks, you can handle browser document object model (DOM) events to run custom script. For example, you can run script when the browser loads or unloads the page.

However, these DOM events do not enable you to access all relevant information or to control the behavior during asynchronous postbacks and during partial-page updates. Therefore, the PageRequestManager class exposes the following events that enable you to customize partial-page updates:

For more information about these events, see Working with PageRequestManager Events.

Code Examples

The following example shows how to use the pageLoaded event of the PageRequestManager class to animate an UpdatePanel control when the page is updated after an asynchronous postback. In this example, users can select a date and enter an e-mail address into a form to make a ticket request. When an asynchronous postback occurs (triggered by links outside the UpdatePanel control), the panel is animated briefly to notify the user that the date value was entered into the text box. The page contains a pop-up window that displays a Calendar control. The calendar is displayed or hidden using the control's Visible property. The whole page does not have to be refreshed when the calendar is displayed or hidden, or when a date is selected, because the Calendar control is inside an UpdatePanel control.

How-to and Walkthrough Topics

Class Reference

The following table lists the classes that relate to the PageRequestManager class.

Class

Description

PageRequestManager Class

Manages client partial-page updates and exposes members for custom client scripting.

InitializeRequestEventArgs Class

Provides event data for the initializeRequest event, which is raised before the asynchronous request starts.

BeginRequestEventArgs Class

Provides event data for the beginRequest event, which is raised after an asynchronous postback starts and before the postback is sent to the server.

PageLoadingEventArgs Class

Provides event data for the pageLoading event, which is raised after the response to an asynchronous postback is received, but before any content on the page is updated. This event is not raised if the postback is stopped or if an unhandled exception is thrown on the server during processing.

PageLoadedEventArgs Class

Provides event data for the pageLoaded event, which is raised after all content on the page is refreshed, whether as the result of a synchronous postback or an asynchronous postback. This event is not raised if the postback is stopped or if an unhandled exception is thrown on the server during processing.

EndRequestEventArgs Class

Provides event data for the endRequest event, which is raised after an asynchronous postback has finished.