AJAX Client Life-Cycle Events

Introduction

A Microsoft ASP.NET AJAX page raises the same server life-cycle events as an ASP.NET 2.0 Web page and also 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.

CS
Sys.Application.add_init(MyInit);
function MyInit(sender) {
}
Sys.Appplication.remove_init(MyInit);

VB
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.

CS
function pageLoad(sender, args) {
}

VB
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.


init Event

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.


load 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.


unload Event

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.


propertyChanged Event

Potentially raised when a property of a component changes. The Application object inherits this event from the Component class. 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.


disposing Event

Raised when the Application instance is disposed. The Application object inherits this event from the Component class.


initializeRequest Event

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.


beginRequest Event

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.


pageLoading Event

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.


pageLoaded Event

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.


endRequest Event

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.