Ajax Page Life Cycle Event Handler Arguments

Introduction

This article is a continuation of the previous article [Ajax Client Page Life Cycle]. This article explains Event Arguments and their usage during asynchronous partial page loads.

The Page Life Cycle Event Handler Arguments

The Event Arguments are themselves an instance of the object respective to their event handlers. Each argument gives reference to other objects, methods and properties which enables us to handle these events in more detail.

Sys.WebForms.InitializeRequestEventArgs Class

The object of this class is used as argument by intializeRequest event of PageRequestManager class. The methods of this object are listed here, where args is the instance of the intializeRequestEventArgs class. The code snippet is also attached below each property for better understanding.

• args.get_postBackElement();
• args.get_request();

//add handler to pageInit event
Sys.Application.add_init(MyInit);

function MyInit()
{
    //alert("MyInit added to page request");
    //add handler to intializeRequest event
    Sys.WebForms.PageRequestManager.getInstance().add_initializeRequest
						(MyIntializeRequest);
    //Sys.WebForms.PageRequestManager.getInstance().remove_initializeRequest
    //(MyIntializeRequest);
}

//sender gives reference to PageRequestManager object
//args gives reference to initializeRequestEventArgs object
function MyIntializeRequest(sender,args)
{
    //assign the reference of element which initiated the postback to a variable
    var ele = args.get_postBackElement();

    //change the property of the postback element
    args.get_postBackElement().disabled = true;

    //sets the display value of postback element
    args.get_postBackElement().value = "Page is getting Loaded...";

    //cancel the postback initiated
    sender.abortPostBack();
}

Sys.WebForms.BeginRequestEventArgs Class

The object of the class is used by BeginRequest event. This object is more similar to the previous one. The object will be instantiated just before the request is sent to the server. The properties and code snippet are listed below:

• args.get_postBackElement();
• args.get_request();

//add this code inside pageInit or pageLoad event
Sys.WebForms.PageRequestManager.getInstance().add_pageLoading(MyPageLoading);
//Sys.WebForms.PageRequestManager.getInstance().remove_pageLoading(MyPageLoading);

//sender gives reference to PageRequestManager object
//args gives reference to BeginRequestEventArgs object
function MyBeginRequest(sender,args)
{
    //we can do all the actions that we did
    //for intializeRequest event.
}

Sys.WebForms.PageLoadingEventArgs Class

The object is used by pageLoading event. This gives reference for the two collections of update panels used in asynchronous postback.

1. Panels deleted during the post, and 
2. Panels going to be updated

We can get the content of the update panels which are not yet updated here. These panels will get updated after the pageLoaded event. The content of the update panel can be changed here, but it will not be reflected in the page when the cycle is finished, because the pageLoaded event will place the new contents in the page. That will be visible to the user at the end.

• args.get_panelsUpdating();
• args.get_panelsDeleting();
• args.get_dataItems();

//this line of code should be inside pageInit or pageLoad event
Sys.WebForms.PageRequestManager.getInstance().add_pageLoading(MyPageLoading);
//Sys.WebForms.PageRequestManager.getInstance().remove_pageLoading(MyPageLoading);

//sender gives reference to PageRequestManager object
//args gives reference to PageLoadingEventArgs object
function MyPageLoading(sender,args)
{
    //the panel collection (going to be updated) count will be displayed.
    alert(args.get_panelsUpdating().length);

    //the content of the first item from panel collections will be assigned to a variable
    var content = args.get_panelsUpdating()[0].innerText;

    //display number of panels is getting deleted during this post back
    alert(args.get_panelsDeleting().length)
}

Sys.WebForms.PageLoadedEventArgs Class

pageLoaded event gives reference to this object. The pageLoading and pageLoaded are more similar. Both events will be triggered after Server Page Render event, but the pageLoading event will be triggered before the content gets updated and pageLoaded after content update. The methods are listed below:

• args.get_panelsUpdated();
• args.get_panelsCreated();
• args.get_dataItems();

//this line of code should be inside pageInit or pageLoad event
Sys.WebForms.PageRequestManager.getInstance().add_pageLoaded(MyPageLoaded);
//Sys.WebForms.PageRequestManager.getInstance().remove_pageLoaded(MyPageLoaded);

//sender gives reference to PageRequestManager object
//args gives reference to PageLoadedEventArgs object
function MyPageLoaded(sender,args)
{
    //the updated panels collection count will be displayed.
    alert(args.get_panelsUpdated().length);

    //the content of the first item from updated panel collections
    //will be assigned to a variable
    var content = args.get_panelsUpdated()[0].innerText;

    //display number of panels created during this postback
    alert(args.get_panelsCreated().length)
}

Sys.WebForms.EndRequestEventArgs Class

Object of EndRequest event, this is the last event in the asnychronous partial post back. This event will be raised after the postback finishes. The response is a member of this object. The special thing about this object is that it enables us to handle errors. The error object will also be a member of this object, if any error occurs during postback otherwise it is null. We can also handle the error and set our own custom values to the error object that will pop up when an error occurs. As we have provision to handle the error, the error can also be suppressed, so that it will not be displayed to user also. This is done by the errorHandled property. If it is set to true, then errors are suppressed. The methods are listed below:

• args.get_dataItems();
• args.get_error();
• args.get_errorHandled();
• args.get_response();

//this line of code should be inside pageInit or pageLoad event
Sys.WebForms.PageRequestManager.getInstance().add_endRequest(MyEndRequest);
//Sys.WebForms.PageRequestManager.getInstance().remove_endRequest(MyEndRequest);

//sender gives reference to PageRequestManager object
//args gives reference to EndRequestEventArgs object
function MyEndRequest(sender, args)
{
    //alert("My Request has end");
    if (args.get_error() != null)
    {
        args.set_errorHandled(true);
    }
}

Sys.WebForms Exceptions

The exception that happens during the asnychronous partial past back is discussed here. The exceptions are dynamically created by Ajax. The exceptions are listed below:

• PageRequestManagerParserErrorException
• PageRequestManagerServerErrorException
• PageRequestManagerTimeoutErrorException

The ParserErrorException happens when an error occurs in processing response. A situation for this is like using Server.Transfer in the partial postback. In this scenario, the request is sent to the server and server transfers the request to some other page, where a client is not aware of this. So the expected page response fails as per the client, so it throws a error. The same situation can be avoided by Response.Redirect, because it makes two round trips to the server, also the client is aware of the page redirection.

The ServerErrorException happens for all the unhandled errors on the server side code. For example, trying to parse a null to int, assigning value to non instanced object, or a similar kind of error raises this exception.

TimeoutException is as the name says. It is thrown when the response is not returned within the specific span of time. The ScriptManager control takes care of these scenarios. We can avoid this by increasing the value of AsyncPostBackTimeout property of ScriptManager.

These errors can be caught in the endRequest event. The get_error() method can be used to retrieve the error object and the name property of the error object gives the full name of the error, and we can handle it accordingly. The below code snippet of endRequest event explains this...

function MyEndRequest(sender, args)
{
    //alert("My Request has end");
    var s = sender;
    var a = args;
    var msg = null;
    if (a._error != null)
    {
        switch (args._error.name)
        {
            case "Sys.WebForms.PageRequestManagerServerErrorException" :
                msg = "PageRequestManagerServerErrorException";
                break;
            case "Sys.WebForms.PageRequestManagerParserErrorException" :
                msg = "PageRequestManagerParserErrorException";
                break;
            case "Sys.WebForms.PageRequestManagerTimeoutException" :
                msg = "PageRequestManagerTimeoutException";
                break;
        }
        args._error.message = "My Custom Error Message " + msg;
        args.set_errorHandled(true);
    }
 }

Additional Information

The handlers can be removed the same way as we are adding it. The commented line below the add custom event handler is the code to remove the added custom event handlers. This note applies for the whole article. I have written it this way just for demonstration purposes.

The objects of Ajax are not having properties, they are methods actually. To remember easily, add prefix get_ and set_ before the actual name of member. Also there are lot of members which are exposed directly to the user, they are not restricted. As the JavaScript doesn't provide that much flexibility towards OOPS, even though it supports to a better extent. These members are similar to the property name with just underscore(_) as prefix to it. We can still have the choice of using it, generally they are not advising it, but if we are able to understand and make changes, it works fine. As you can see, the _error.message is set with a custom value in the code snippet given above.

We still have a lot to discuss about Ajax. Let us look at those in future articles.

History

• 23^rd May, 2008: Initial post