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.

 

 

 

 

 

 

 

Skip Navigation Links.
Tutorials
Sample ASP.NET AJAX Application
ASP.NET AJAX and JavaScript
Extending JavaScript with ASP.NET AJAX
Creating Custom Client Script in ASP.NET AJAX
Dynamically Assigning ASP.NET AJAX Script References
Globalizing a Date by Using Client Script
Embedding a JavaScript File as a Resource in an Assembly
Embedding Localized Resources for a JavaScript File
Adding Localized Resources to a JavaScript File
Creating Custom Client Events
The UpdatePanel Control
Introduction to the UpdatePanel Control
Creating a Simple ASP.NET Page with Multiple UpdatePanel Controls
Using the UpdatePanel Control with Data-Bound Controls
Using the UpdatePanel Control with Master Pages
Using the UpdatePanel Control with User Controls
Using the UpdatePanel Control with a Web Service
Customizing Error Handling for UpdatePanel Controls
Animating UpdatePanel Controls
Canceling an Asynchronous Postback
Giving Precedence to a Specific Asynchronous Postback
Working with PageRequestManager Events
The UpdateProgress Control
Introduction to the UpdateProgress Control
Programming UpdateProgress Controls in Client Script
The Timer Control
Introduction to the Timer Control
Using the Timer Control with Multiple UpdatePanel Controls
ASP.NET Application Services
Using Forms Authentication
Using Profile Information
Web Services
Exposing Web Services to Client Script
Calling Web Services from Client Script
ASP.NET AJAX Extensibility
Creating Custom ASP.NET AJAX Non-Visual Client Components
Creating Custom ASP.NET AJAX Client Controls
Creating an Extender Control
Adding Client Capabilities to a Web Server Control
Creating a Client Component Class Using the Prototype Model
Defining Custom Component Properties and Raising PropertyChanged Events
Releasing Component Resources

Working with PageRequestManager Events

Introduction

The PageRequestManager class in the Microsoft AJAX Library coordinates with the ScriptManager and UpdatePanel server controls on an ASP.NET Web page to enable partial-page updating. The PageRequestManager class exposes methods, properties, and events to make client programming easier when page elements are performing asynchronous postbacks. For example, the PageRequestManager class enables you to handle events in the client page life cycle and to provide custom event handlers that are specific to partial-page updates.

To use the PageRequestManager class in client script, you must put a ScriptManager server control on the Web page. The EnablePartialRendering property of the ScriptManager control must be set to true (which is the default). When EnablePartialRendering is set to true, the client-script library that contains the PageRequestManager class is available in the page.

Getting an Instance of the PageRequestManager Class

There is one PageRequestManager instance per page. You do not create an instance of the class. Instead, you get a reference to the current instance by calling the getInstance method, as shown in the following example:

CS

Sys.WebForms.PageRequestManager.getInstance().add_initializeRequest(InitializeRequest);

vb

Sys.WebForms.PageRequestManager.getInstance().add_initializeRequest(InitializeRequest);

When you have the current instance of the PageRequestManager class, you can access all its methods, properties, and events. For example, you can get the isInAsyncPostBack property to determine whether an asynchronous postback is in progress, as shown in the following example:

CS

function InitializeRequest(sender, args)
{
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    if (prm.get_isInAsyncPostBack() & args.get_postBackElement().id == 'CancelPostBack') {
        prm.abortPostBack();
    }    
}

vb

function InitializeRequest(sender, args)
{
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    if (prm.get_isInAsyncPostBack() & args.get_postBackElement().id == 'CancelPostBack') {
        prm.abortPostBack();
    }    
}

If the EnablePartialRendering property of the ScriptManager control is false, you cannot access the isInAsyncPostBack property because there is no PageRequestManager instance.

Client Page Life-cycle Events

During ordinary page processing in the browser, the window.onload DOM event is raised when the page first loads. Similarly, the window.onunload DOM event is raised when the page is refreshed or when the user moves away from the page.

However, these events are not raised during asynchronous postbacks. To help you manage these types of events for asynchronous postbacks, the PageRequestManager class exposes a set of events. These resemble window.load and other DOM events, but they also occur during asynchronous postbacks. For each asynchronous postback, all page events in the PageRequestManager class are raised and any attached event handlers are called.

note

For synchronous postbacks, only the pageLoaded event is raised.

You can write client script to handle events raised by the PageRequestManager class. Different event argument objects are passed to handlers for different events. The following table summarizes the PageRequestManager class events and the corresponding event argument classes. The order of the events in the table is the order of the events for a single asynchronous postback without errors.

initializeRequest

Raised before the request is initialized for an asynchronous postback. Event data is passed to handlers as an InitializeRequestEventArgs object. The object makes available the element that caused the postback and the underlying request object.

beginRequest

Raised just before the asynchronous postback is sent to the server. Event data is passed to handlers as a BeginRequestEventArgs object. The object makes available the element that caused the postback and the underlying request object.

pageLoading

Raised after the response to the most recent asynchronous postback has been received but before any updates to the page have been made. Event data is passed to handlers as a PageLoadingEventArgs object. The object makes available information about what panels will be deleted and updated as a result of the most recent asynchronous postback.

pageLoaded

Raised after page regions are updated after the most recent postback. Event data is passed to handlers as a PageLoadedEventArgs object. The object makes available information about what panels were created or updated. For synchronous postbacks, panels can only be created, but for asynchronous postbacks, panels can be both created and updated.

endRequest

Raised when request processing is finished. Event data is passed to handlers as an EndRequestEventArgs object. The object makes available information about errors that have occurred and whether the error was handled. It also makes available the response object.

If you use the RegisterDataItem method of the ScriptManager control to send extra data during an asynchronous postback, you can access that data from the PageLoadingEventArgs, PageLoadedEventArgs, and EndRequestEventArgs objects.

The sequence of events varies with different scenarios. The order in the previous table is for a single, successful asynchronous postback. Other scenarios include the following:

  • Multiple postbacks where the most recent postback takes precedence, which is the default behavior. Only events for the most recent asynchronous postback are raised.

  • Multiple postbacks where one postback is given precedence, which cancels all subsequent postbacks until it is finished. Only the initializeRequest event is raised for canceled postbacks.

  • An asynchronous postback that is stopped. Depending on when the postback is stopped, some events might not be raised.

  • An initial request (HTTP GET) of a page, or a page refresh. When a page is first loaded or when it is refreshed in the browser, only the pageLoaded event is raised.

Stopping and Canceling Asynchronous Postbacks

Two common tasks are to stop an asynchronous postback that is underway and to cancel a new request before it has begun. To perform these tasks, you do the following:

  • To stop an existing asynchronous postback, you call the abortPostback method of the PageRequestManager class.

  • To cancel a new asynchronous postback, you handle the initializeRequest event of the PageRequestManager class and set the cancel property to true.

Stopping an Asynchronous PostBack

The following example shows how to stop an asynchronous postback. The initializeRequest event handler script checks whether the user has chosen to stop the postback. If so, the code calls the abortPostback method.

For more information, see Canceling an Asynchronous Postback.

Canceling New Asynchronous Postbacks

The following example shows how to give precedence to a specific asynchronous postback. This cancels all subsequent asynchronous postbacks until the current one finishes. (By default, the most recent asynchronous postback takes precedence.) The initializeRequest event handler checks whether the asynchronous postback was initiated by an element on the page that has precedence. If it was, all subsequent postbacks are canceled by setting the cancel property of the InitializeRequestEventArgs object. The InitializeRequestEventArgs event inherits from the CancelEventArgs class, where the cancel property is defined.

For more information, see Giving Precedence to a Specific Asynchronous Postback.

Displaying a Custom Error Message

The following example shows how to display a custom error message when an error occurs during an asynchronous postback. The AsyncPostBackError event of the ScriptManager control is handled in server code, and information about the error is sent to the browser to be displayed.

For more information, see Customizing Error Handling for UpdatePanel Controls.

Animating Panels

The following example shows how to animate an UpdatePanel control to notify the user that the content has changed. When you click the LinkButton controls, a border around the UpdatePanel control is shown briefly.

For more information, see Animating UpdatePanel Controls.