AJAX Client Life-Cycle Events
An AJAX-enabled ASP.NET page raises the same server life-cycle events as an ASP.NET 2.0 Web page and in addition raises client life-cycle events. The client events enable you to customize the UI for both postbacks and for asynchronous postbacks (partial-page updates). The client events also help you manage custom script components during the lifetime of the page in the browser.
The client events are raised by classes in the Microsoft AJAX Library. These classes are automatically instantiated when a page contains ASP.NET AJAX server controls. The client classes provide APIs that enable you to bind to events and to provide handlers for those events. Because the Microsoft AJAX Library is browser independent, the code you write for your handlers works the same in all supported browsers.
The key event for initial requests (GET requests) and synchronous postbacks is the load event of the Application instance. When script in a load event handler runs, all scripts and components have been loaded and are available. When partial-page rendering with UpdatePanel controls is enabled, the key client events are the events of the PageRequestManager class. These events enable you to handle many common scenarios. These include the ability to cancel postbacks, to give precedence to one postback over another, and to animate UpdatePanel controls when their content is refreshed.
Client events are useful whether you are creating pages or writing components. If you are a page developer, you can provide custom script that is called when the page loads and unloads in the browser.
For more information about the server life-cycle events, see ASP.NET Page Life Cycle Overview.
Client Classes
The two main Microsoft AJAX Library classes that raise events during the client life cycle of an ASP.NET AJAX Web page are the Application and PageRequestManager classes.
The Application class is instantiated in the browser when the page contains a ScriptManager control. The Application class resembles the Page server control, which derives from the Control class, but provides additional functionality for raising server events. Similarly, the Application class derives from the Sys.Component class, but raises client life-cycle events that you can handle.
If a page contains a ScriptManager control and one or more UpdatePanel controls, the page can perform partial-page updates (if partial-page rendering is enabled and supported in the browser). In that case, an instance of the PageRequestManager class is automatically available in the browser. The PageRequestManager class raises client events that are specific to asynchronous postbacks. For details about partial-page rendering, see Partial-Page Rendering Overview.
Adding Handlers for Client Events
To add or remove handlers for events raised by the Application and PageRequestManager classes, use the add_eventname and remove_eventname methods of those classes. The following example shows how to add a handler named MyLoad to the init event of the Application object.
Sys.Application.add_init(MyInit);
function MyInit(sender) {
}
Sys.Appplication.remove_init(MyInit);
Note
This example shows just the syntax of the add_eventname and remove_eventname methods. Details about what you can do with specific events are provided later in this topic.
Handling the Application Load and Unload Events
To handle the load and unload events of the Application object, you do not have to explicitly bind a handler to the event. Instead, you can create functions that use the reserved names pageLoad and pageUnload. The following example shows how to add a handler for the load event of the Application object by using this approach.
function pageLoad(sender, args) {
}
Events for Other Client Classes
This topic describes only the events that are raised by the Application and PageRequestManager classes. The Microsoft AJAX Library also contains classes for adding, clearing, and removing handlers for DOM element events. These classes include the following:
The Sys.UI.DomEvent.addHandler method or the shortcut $addHandler.
The Sys.UI.DomEvent.clearHandlers method or the shortcut $clearHandlers.
The Sys.UI.DomEvent.removeHandler method or the shortcut $removeHandler.
Events raised by DOM elements are not discussed in this topic.
Client Events of the Application and PageRequestManager Classes
The following table lists client events of the Application and PageRequestManager classes that you can handle in AJAX ASP.NET-enabled pages. The order in which the events are raised is described later in this topic.
Event |
Description |
|---|---|
Raised after all scripts have been loaded but before any objects are created. If you are writing a component, the init event gives you a point in the life cycle to add your component to the page. The component can then be used by other components or by script later in the page life cycle. If you are a page developer, you should use the load event instead of the init event for most scenarios. The init event is raised only one time when the page is first rendered. Subsequent partial-page updates do not raise the init event. |
|
Raised after all scripts have been loaded and all objects in the application that are created by using $create are initialized. The load event is raised for all postbacks to the server, which includes asynchronous postbacks. If you are a page developer, you can create a function that has the name pageLoad, which automatically provides a handler for the load event. The pageLoad handler is called after any handlers that have been added to the load event by the add_load method. The load event takes an eventargs parameter, which is an Sys.ApplicationLoadEventArgs object. You can use the event arguments to determine whether the page is being refreshed as a result of a partial-page update and what components were created since the previous load event was raised. |
|
Raised before all objects are disposed and before the browser window's window.unload event occurs. If you are a page developer, you can create a function that has the name pageUnload, which automatically provides a handler for the unload event. The pageUnload event is called just before the page is unloaded from the browser. During this event, you should free any resources that your code is holding. |
|
Potentially raised when a property of a component changes. This event is raised only if a component developer has called the Sys.Component.raisePropertyChange method in a property set accessor. For more information, see Defining Custom Component Properties and Raising PropertyChanged Events. The propertyChanged event takes an eventargs parameter, which is a Sys.applicationLoadEventArgs object. |
|
Raised when the Application instance is disposed. |
|
Raised before an asynchronous request starts. You can use this event to cancel a postback, such as to give precedence to another asynchronous postback. The initializeRequest event takes an eventargs parameter, which is a Sys.WebForms.InitializeRequestEventArgs object. This object makes available the element that caused the postback and the underlying request object. InitializeRequestEventArgs also exposes a cancel property. If you set cancel to true, the new postback is canceled. |
|
Raised before an asynchronous postback starts and the postback is sent to the server. If there is a postback already processing, it is stopped (by using the abortPostBack method). You can use this event to set request headers or to begin an animation on the page to indicate that the request is in process. The beginRequest event takes an eventargs parameter, which is a Sys.WebForms.BeginRequestEventArgs object. This object makes available the element that caused the postback and the underlying request object. |
|
Raised after the response from the server to an asynchronous postback is received, but before any content on the page is updated. You can use this event to provide a custom transition effect for updated content. The pageLoading event takes an eventargs parameter, which is an Sys.WebForms.PageLoadingEventArgs object. This object makes available information about what panels will be deleted and updated as a result of the most recent asynchronous postback. |
|
Raised after all content on the page is refreshed, as a result of either a synchronous or an asynchronous postback. For synchronous postbacks, panels can only be created, but for asynchronous postbacks, panels can be both created and updated. You can use this event to manage a custom transition effect for updated content. The pageLoaded event takes an eventargs parameter, which is an Sys.WebForms.PageLoadedEventArgs object. This object makes available information about which panels were updated and created in the most recent postback. |
|
Raised after the response for an asynchronous postback is processed and the page is updated, or during the processing of the response if there is an error. If an error occurs, the page is not updated. Use this event to provide customized error notification to users or to log errors. The endRequest event takes an eventargs parameter, which is a Sys.WebForms.EndRequestEventArgs object. This object makes available information about errors that have occurred and whether the error was handled. It also makes available the response object. |
Event Order Example
The following example shows the client events that are raised on a page that includes two UpdatePanel controls, one nested inside the other. You will notice a difference between clicking the button in the parent panel and clicking the button in the nested panel. The button in the parent panel causes the parent panel to be updated and the nested panel to be deleted and recreated. The button in the nested panel causes just the nested panel to be updated.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Client Event Example</title>
<style type="text/css">
#OuterPanel { width: 600px; height: 200px; border: 2px solid blue; }
#NestedPanel { width: 596px; height: 60px; border: 2px solid green;
margin-left:5 px; margin-right:5px; margin-bottom:5px;}
</style>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:ScriptManager ID="ScriptManager1" runat="server">
<Scripts>
<asp:ScriptReference Path="ClientEventTest.js" />
</Scripts>
</asp:ScriptManager>
<asp:UpdatePanel ID="OuterPanel" UpdateMode="Conditional" runat="server">
<ContentTemplate>
Postbacks from inside the outer panel and inner panel are
asynchronous postbacks. PRM = Sys.WebForms.PageRequestManager. APP = Sys.Application.
<br /><br />
<asp:Button ID="OPButton1" Text="Outer Panel Button" runat="server" />
Last updated on
<%= DateTime.Now.ToString() %>
<br /><br />
<asp:UpdatePanel ID="NestedPanel" UpdateMode="Conditional" runat="server">
<ContentTemplate>
<asp:Button ID="NPButton1" Text="Nested Panel 1 Button" runat="server" />
Last updated on
<%= DateTime.Now.ToString() %>
<br />
</ContentTemplate>
</asp:UpdatePanel>
</ContentTemplate>
</asp:UpdatePanel>
<input type="button" onclick="Clear();" value="Clear" />
<asp:Button ID="FullPostBack" runat="server" Text="Full Postback" />
<a href="https://www.microsoft.com">Test Window Unload</a>
<br />
<span id="ClientEvents"></span>
</div>
</form>
</body>
</html>
// Hook up Application event handlers.
var app = Sys.Application;
app.add_load(ApplicationLoad);
app.add_init(ApplicationInit);
app.add_disposing(ApplicationDisposing);
app.add_unload(ApplicationUnload);
// Application event handlers for component developers.
function ApplicationInit(sender) {
var prm = Sys.WebForms.PageRequestManager.getInstance();
if (!prm.get_isInAsyncPostBack())
{
prm.add_initializeRequest(InitializeRequest);
prm.add_beginRequest(BeginRequest);
prm.add_pageLoading(PageLoading);
prm.add_pageLoaded(PageLoaded);
prm.add_endRequest(EndRequest);
}
$get('ClientEvents').innerHTML += "APP:: Application init. <br/>";
}
function ApplicationLoad(sender, args) {
$get('ClientEvents').innerHTML += "APP:: Application load. ";
$get('ClientEvents').innerHTML += "(isPartialLoad = " + args.get_isPartialLoad() + ")<br/>";
}
function ApplicationUnload(sender) {
alert('APP:: Application unload.');
}
function ApplicationDisposing(sender) {
$get('ClientEvents').innerHTML += "APP:: Application disposing. <br/>";
}
// Application event handlers for page developers.
function pageLoad() {
$get('ClientEvents').innerHTML += "PAGE:: Load.<br/>";
}
function pageUnload() {
alert('Page:: Page unload.');
}
// PageRequestManager event handlers.
function InitializeRequest(sender, args) {
$get('ClientEvents').innerHTML += "<hr/>";
$get('ClientEvents').innerHTML += "PRM:: Initializing async request.<br/>";
}
function BeginRequest(sender, args) {
$get('ClientEvents').innerHTML += "PRM:: Begin processing async request.<br/>";
}
function PageLoading(sender, args) {
$get('ClientEvents').innerHTML += "PRM:: Loading results of async request.<br/>";
var updatedPanels = printArray("PanelsUpdating", args.get_panelsUpdating());
var deletedPanels = printArray("PanelsDeleting", args.get_panelsDeleting());
var message = "-->" + updatedPanels + "<br/>-->" + deletedPanels + "<br/>";
document.getElementById("ClientEvents").innerHTML += message;
}
function PageLoaded(sender, args) {
$get('ClientEvents').innerHTML += "PRM:: Finished loading results of async request.<br/>";
var updatedPanels = printArray("PanelsUpdated", args.get_panelsUpdated());
var createdPanels = printArray("PaneslCreated", args.get_panelsCreated());
var message = "-->" + updatedPanels + "<br/>-->" + createdPanels + "<br/>";
document.getElementById("ClientEvents").innerHTML += message;
}
function EndRequest(sender, args) {
$get('ClientEvents').innerHTML += "PRM:: End of async request.<br/>";
}
// Helper functions.
function Clear()
{
$get('ClientEvents').innerHTML = "";
}
function printArray(name, arr)
{
var panels = name + '=' + arr.length;
if(arr.length > 0)
{
panels += "(";
for(var i = 0; i < arr.length; i++)
{
panels += arr[i].id + ',';
}
panels = panels.substring(0, panels.length - 1);
panels += ")";
}
return panels;
}
Event Order for Common Scenarios
The order of events depends on what controls are used on the page and what type of request is made (initial request, postback, or asynchronous postback). This section describes the order of events for several common scenarios.
Initial Request
During the initial request for the page, a limited number of client events are raised. Assume the following scenario for the initial request:
The page contains a ScriptManager control, and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
The request is a GET request.
A response from the server is returned successfully.
The following client events occur, in this order:
The initial request is sent to the server.
The response is received by the client.
The Application instance raises the init event.
The Application instance raises the load event.
The init event of the Application instance is raised only one time for the life of the page in the browser. It is not raised for subsequent asynchronous postbacks. During an initial request, no PageRequestManager events are raised.
Asynchronous Postback
An asynchronous postback sends some page data to the server, receives a response, and updates a part of the page. Assume the following scenario for an asynchronous postback:
The page contains a ScriptManager control, and the control's SupportsPartialRendering and EnablePartialRendering properties are both true.
The page contains an UpdatePanel control, and the control's ChildrenAsTriggers property is true.
A button inside the UpdatePanel control initiates an asynchronous postback.
A response from the server is returned successfully.
The following client events occur, in this order:
The button inside the UpdatePanel is clicked, which initiates an asynchronous postback.
The PageRequestManager instance raises the initializeRequest event.
The PageRequestManager instance raises the beginRequest event.
The request is sent to the server.
The response is received by the client.
The PageRequestManager instance raises the pageLoading event.
The PageRequestManager instance raises the pageLoaded event.
The Application instance raises the load event.
The PageRequestManager instance raises the endRequest event.
For more information, see Working with PageRequestManager Events.
Note that the load event of the Application instance is raised after the PageRequestManager pageLoaded event and before its endRequest event.
Multiple Asynchronous Postbacks
Multiple asynchronous postbacks can occur when users initiate a new request before a previously initiated request has finished processing on the server or in the browser. Assume the following scenario for multiple asynchronous postbacks:
The page contains a ScriptManager control and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
The page contains an UpdatePanel control.
A button inside the UpdatePanel control that initiates an asynchronous postback is clicked two times. The second click occurs while the server is processing the request initiated by the first click.
A response to the first request is returned successfully from the server.
The following client events occur, in this order:
A button inside the UpdatePanel is clicked, which initiates an asynchronous postback.
The PageRequestManager instance raises the initializeRequest event.
The PageRequestManager instance raises the beginRequest event.
The request is sent to the server.
The button is clicked again, which initiates a second asynchronous postback.
The PageRequestManager instance raises the initializeRequest event for the second button click.
The PageRequestManager instance raises the endRequest event for the first button click.
The PageRequestManager instance raises the beginRequest event for the second button click.
The request initiated by the second click is sent to the server.
The response is received for the second click.
The PageRequestManager instance raises the pageLoading event.
The PageRequestManager instance raises the pageLoaded event.
The Application instance raises the load event.
The PageRequestManager instance raises the endRequest event.
The default behavior of asynchronous postbacks is that the most recent asynchronous postback takes precedence. If two asynchronous postbacks occur in sequence, and if the first postback is still being processed in the browser, the first postback is canceled. If the first postback has been sent to the server, the server processes the second request when it arrives and does not return the first request. For information about how to give precedence to a specific asynchronous postback, see Giving Precedence to a Specific Asynchronous Postback.
Browsing Away from a Page
When the user browses away from a page, the current page is unloaded from the browser and you can handle the unload event to free resources. Assume the following scenario for browsing away from a page:
The page contains a ScriptManager control and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
The target page exists.
The following client events are raised, in this order:
The request for new page is initiated.
The response for the new page is received by the browser.
The Application instance raises the unload event.
The new page is displayed.
If there is an error in the request for the new page, the unload event is still raised, but the new page is not displayed.
See Also
Concepts
ASP.NET Page Life Cycle Overview
Defining Custom Component Properties and Raising PropertyChanged Events