Update panels don't really have a client-side JavaScript
representation and will just be available as a DIV or SPAN element in the
document. ScriptManager, on the other
hand, as a global manager object for all things related to partial
updates, finds an interesting client-side alter-ego in PageRequestManager. PageRequestManager is the object that is
responsible client-side for managing the lifecycle and events related to
UpdatePanel controls. The current
instance of PageRequestManager for the
page can be obtained like this:
var prm = Sys.WebForms.PageRequestManager.getInstance();
It is this object for example that will enable your client-side code to determine if a partial update is currently pending, by looking at its isInAsyncPostBack property:
if (prm.get_isInAsyncPostBack()) { //...PageRequestManager also enables
you to cancel a partial update:
prm.abortPostBack();
Calling this method unfortunately can't stop the information that is already on its way to the server, it can just instruct the client to ignore the results when they come back. This means that any side effects like database updates won't be cancelled.
The most interesting aspect of PageRequestManger is certainly all the events it
exposes that enable client-side code to modify the default behavior of
UpdatePanel and that we'll detail in
the following section.
All events on PageRequestManager are built using the ASP.NET
Ajax pattern for component events. In other words, you can add a handler
for one of the events, for example "beginRequest", by calling the add accessor
it exposes:
prm.add_beginRequest(handlerFunction);
An event handler is a function that has the typical .NET signature (sender, args).
Here's the list of events on PageRequestManager, in the chronological order
they would happen during a partial update:
The initializeRequest event
is raised at the very beginning of the partial update lifecycle. The
arguments for this event inherit CancelEventArgs, which means that a partial
update can easily be cancelled by just setting the cancel property to
true (args.set_cancel(true);). The arguments also
provide a reference to the DOM element that triggered the partial
update through the postBackElement
property. Finally, the request property gives a reference to the
WebRequest object that will be used to perform the update, which can
be used to add headers to the request for example.
This event is raised every time a new partial update request is
about to be sent to the server. The arguments for this event have two
properties, postBackElement which
is a reference to the element that triggered the postback, and
request, which is the WebRequest
object that will be used for this update. This event can be used to
start a progress animation.
pageLoading is raised when
the data from a partial update came back from the server but before
the page has been updated with that data. For example, this is one of
the events to handle if you want to implement a transition between the
old contents and the new contents. The event exposes properties on its
arguments give references to all deleting panels (panelsDeleting) and all updating panels
(panelsUpdating). Using those
properties, the handler can clone the DOMs of each of the panels and
hold on to those copies to use them in the pageLoaded event and do the actual
transition.
This event is raised just after the page has been updated with
the new contents. In the same way that pageLoading exposed collections
of previous versions of panels before their modification, pageLoaded exposes collections
of new versions of existing panels (panelsUpdated) and also of newly created
panels (panelsCreated). This is the
first time in the lifecycle when you have all the data to transition
between the old and the new version of the page.
A full implementation of this can be found on Nikhil Kothari's blog: http://www.nikhilk.net/UpdateControls.aspx
The ASP.NET Ajax documentation also contains an example of that: http://ajax.asp.net/docs/tutorials/AnimateUpdatePanels.aspx
This is raised at the end of the partial update lifecycle and is
used primarily to add feedback, typically about server exceptions. The
arguments for this event have four properties (they are properties,
not fields, so remember to use get_
and set_ accessors):
dataItemsis a data structure that the server can optionally send down to the client during a partial update, in addition to the HTML. This is detailed in the next section, Sending structured data to the client.errorwill contain anErrorobject if an unhandled exception was thrown from the server-side during the partial update request.errorHandledis true only if there was an error and it hasn't been handled yet. If the endRequest handler handles that error and wants to suppress any further treatment of it, it should set this property to true.Responseis the raw response object from the server and will not commonly be used.
While the most common use of UpdatePanel will be to send new HTML down to
the client, partial updates can also be used to send raw data along with
the update. That data can then be used by JavaScript code in the
pageLoaded event for example to
perform direct modifications on the client-side. There are two reasons
why one would want to use that feature despite the need to write
JavaScript. First, HTML is not the most compact way to transport data,
and second it is sometimes useful to have the raw data to be able to
present the same thing under different forms. For example, the same data
could be used to create a summary view and a detailed view.
This feature should probably be used to complement HTML updates
though: if you're ready to write JavaScript code and handle data on the
client-side, you may want to directly use WebRequest objects and use only pure data. The
traffic with the server will be minimized this way.
See http://ajax.asp.net/docs/mref/M_System_Web_UI_ScriptManager_RegisterDataItem_3_22ee3056.aspx for more details.