Working with Partial-Page Rendering Events
The PageRequestManager class in the Microsoft Ajax Library coordinates with the ScriptManager and UpdatePanel server controls on an AJAX-enabled 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.
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:
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:
If the EnablePartialRendering property of the ScriptManager control is false, you cannot access the isInAsyncPostBack property because there is no PageRequestManager instance.
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.
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.
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.
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.
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.
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 ASP.NET UpdatePanel Controls.
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 Walkthrough: Animating ASP.NET UpdatePanel Controls.
Note