CoverStory
LANGUAGES: C#
ASP.NET VERSIONS: 2.0
Putting AJAX on the Map
AJAX-enable ASP.NET Applications with the UpdatePanel
By Dan Wahlin
Microsoft s ASP.NET AJAX framework provides numerous features that can be used to enhance the overall experience of the end user. While many AJAX frameworks exist, ASP.NET AJAX provides a simple, yet full-featured platform for adding AJAX concepts into an ASP.NET application without having to be an expert in JavaScript, XmlHttp, or Web services. I originally wrote about using ASP.NET AJAX in Leverage the Web (when the framework was still called Atlas ). Since then, many changes have been made to the API and script library so if you re just starting to ride the AJAX wave, you re hitting it at the right time.
In this article you ll see how to add AJAX capabilities into an ASP.NET page to provide a richer experience for the end user, where page postbacks don t occur each time a button is clicked. The application that you ll see revisits the one I wrote about back in the Atlas days, although it s been upgraded to take advantage of the new features, controls, and events. It allows users to select customers based on country or customer ID, and displays them using a GridView control. In addition to showing ASP.NET AJAX features, the application also demonstrates how to tie into Microsoft s Virtual Earth API to display customer data. Let s get started by looking at the ASP.NET AJAX UpdatePanel and asynchronous postback operations.
Asynchronous Postbacks with the UpdatePanel
ASP.NET AJAX provides several ways to AJAX-enable a page. If you have experience with JavaScript, you can write scripts that hit Web services or other data sources to dynamically update data in a page without re-loading the entire page. While writing JavaScript (which is really what AJAX is all about) provides complete control over how data is selected and displayed in a page, the ASP.NET AJAX UpdatePanel control can greatly simplify the development process and minimize the amount of code you write.
The UpdatePanel is a server-side control built into the ASP.NET AJAX Extensions (http://ajax.asp.net) that can intercept postback requests made in a page and turn them into asynchronous XmlHttp calls. If you re unfamiliar with XmlHttp calls, they rely on an XmlHttpRequest object that is built into modern browsers to communicate directly from the browser to the server without causing a postback operation. By using the UpdatePanel control, you can update parts of a page dynamically by making XmlHttp requests behind the scenes. All of this can be done with little or no JavaScript.
Once you ve installed the ASP.NET AJAX Extensions, you can use Visual Studio .NET 2005 to create a page capable of using an UpdatePanel control. When creating a new Web site, you ll have the option to create an ASP.NET AJAX-enabled Web site. Choosing this Web site template will automatically add to the Web site a web.config file with all the necessary settings, as well as a Default.aspx page that contains a ScriptManager control. The ScriptManager control is responsible for dynamically loading ASP.NET AJAX library scripts used by different browsers.
Once a ScriptManager is available in a page, you can wrap sections that need to be updated asynchronously with an UpdatePanel. Figure 1 shows an example of using the UpdatePanel to add AJAX capabilities to a GridView control. As the GridView control is updated, only the content within the UpdatePanel s ContentTemplate will be refreshed on the screen. Other sections of the page will remain untouched. This can make the end-user experience much better, as they don t have to wait for the entire page to render and can see results more quickly.
GridLines="none" ShowHeader="false"
AutoGenerateColumns="false">
Figure 1: Using the UpdatePanel control.
While the code shown in Figure 1 will render a GridView control when the page is first loaded, how would you tell the UpdatePanel to refresh itself based on end-user actions? While a Button or LinkButton could be added into the UpdatePanel to cause an asynchronous postback operation, there may be times when you need to refresh the UpdatePanel content when a control defined outside the UpdatePanel is clicked or selected. Fortunately, this type of task is easily accomplished by using UpdatePanel triggers. A trigger represents a way to notify the UpdatePanel when an XmlHttp call needs to be made to update the content.
You define triggers that refresh an UpdatePanel by using its Triggers property. Two types of triggers can be defined, including postback triggers and asynchronous triggers. Postback triggers force the entire page to be refreshed through a postback operation; asynchronous triggers use XmlHttp requests and only update the content within the UpdatePanel. When defining an asynchronous trigger you must specify the id of the control that should cause an update, as well as the type of event it exposes. For example, if a button triggers an UpdatePanel to refresh, you would need to define the id of the button as well as the event that it raises (the click event for a button). Figure 2 shows an example of defining two external triggers for an UpdatePanel control.
GridLines="none" ShowHeader="false"
AutoGenerateColumns="false">
Figure 2: Defining UpdatePanel triggers.
The AsyncPostBackTrigger controls shown in Figure 2 tie the respective button click events to the UpdatePanel. When btnSubmit or btnSubmit2 are clicked, an XmlHttp request will be made and the UpdatePanel s content will be refreshed automatically. No JavaScript code has to be written for this interaction between controls to happen. In cases where a control should trigger a regular postback operation that reloads the entire page, the PostBackTrigger control can be used instead of the AsyncPostBackTrigger control. PostBackTrigger only exposes a ControlID property.
Using the PageRequestManager with the UpdatePanel
The UpdatePanel provides a straightforward way to AJAX-enable ASP.NET pages and perform asynchronous postback operations without writing JavaScript code. However, there may be situations where you need to know when an UpdatePanel is starting to load or when it has finished loading. Knowing how to handle these events can allow you to perform additional actions, such as notifying the end user that updated data is available.
ASP.NET AJAX provides a client-side class named PageRequestManager that allows you to tie into the life-cycle of a page. Using the PageRequestManager you can automatically be notified when an UpdatePanel s content has been refreshed and take appropriate action. Notifications are done through client-side events and event handlers.
The sample application available with this article s downloadable code demonstrates how to tie an UpdatePanel to Virtual Earth maps (see end of article for download details). As an UpdatePanel is refreshed with customer data, an event is fired on the client-side by the PageRequestManager. An event handler then determines in which country the customers currently being displayed live and passes the value to a JavaScript routine that pans the map to the correct country. Figure 3 shows how to access the ASP.NET AJAX library s PageRequestManager instance and hook the endRequest event to an event handler.
Sys.WebForms.PageRequestManager.getInstance().add_endRequest(
endRequestHandler);
function endRequestHandler(sender, eventArgs)
{
if (eventArgs.get_error() != undefined &&
eventArgs.get_error().httpStatusCode == '500')
{
var errorMessage = eventArgs.get_error().message;
eventArgs.set_errorHandled(true);
alert(errorMessage);
} else
{
//alert($get("hidField").value);
GetMap($get("hidField").value);
}
}
Figure 3: Using the PageRequestManager.
The PageRequestManager is accessed by calling its getInstance function. Once the object instance is accessed, the add_endRequest function is called, which accepts the name of the callback function that should be run after the UpdatePanel request completes.
The endRequestHandler function accepts two parameters, including the sender of the event data, as well as an eventArgs variable. endRequestHandler uses the eventArgs variable to determine if any errors occurred during the UpdatePanel request. If no errors occurred, it calls another function named GetMap and passes the value of a hidden field named hidField. The hidden field contains the country for all the customers in the GridView.
The PageRequestManager can also be used to notify end users when a request is starting. This is done by calling its add_beginRequest function. This can be useful when you know requests may take awhile and you d like to call a JavaScript function that polls a back-end Web service to monitor the progress of the request. An example of using the add_beginRequest function is shown here:
Sys.WebForms.PageRequestManager.getInstance.add_beginRequest(
callback);
More information about the PageRequestManager s events can be found at http://ajax.asp.net/docs/ClientReference/Sys.WebForms/PageRequestManagerClass/default.aspx.
Using Virtual Earth Map
In the previous section you saw how the PageRequestManager could be used to detect when an UpdatePanel s request completed. This is useful for many tasks, including displaying a Virtual Earth map to show where customers are from. To use Microsoft s Virtual Earth map technology you must first embed a call to a mapping API script. You ll normally add this script reference within the head section of a page, as shown in Figure 4.
Figure 4: Referencing the Virtual Earth script.
Once the page containing the Virtual Earth script reference loads, a new VEMap object needs to be created, as shown in Figure 5. This map object is stored in a global variable named _map so that it can be accessed by other functions used in the page.
var id = 0;
var _country = null;
var _map = null;
var _desc = null;
function onLoad(sender,eventArgs)
{
_map = new VEMap('map');
_map.LoadMap();
}
Figure 5: Creating a Virtual Earth map object.
As the UpdatePanel refreshes, the PageRequestManager fires the endRequest event, which is used to grab the current country to display on the map. The country is passed to the GetMap function shown in Figure 6. GetMap handles updating a span tag on the page with the current country name and also calls a Web service to get the country s longitude and latitude. When the Web service call returns, the OnWSMapRequestComplete function writes out the returned longitude and latitude to the page and calls a LoadMap function. Although Web service calls are beyond the scope of this article, you ll find more information in the downloadable code.
function GetMap(country) {
_country = country;
$get("lblCountry").innerText = _country;
InterfaceTraining.CustomersService.GetCountryLongLat(
country, OnWSMapRequestComplete);
}
function OnWSMapRequestComplete(results) {
if (results != null)
{
var lat = $get("spanLat");
var lon = $get("spanLong");
lat.innerHTML = results.Lat;
lon.innerHTML = results.Long;
LoadMap(results.Lat,results.Long);
}
}
function LoadMap(lat,lon)
{
var latLon = new VELatLong(lat,lon);
_map.PanToLatLong(latLon);
var pin = new VEPushpin(id++,
latLon,
null,
_country,
_desc
);
_map.AddPushpin(pin);
}
Figure 6: Locating a customer s country using Virtual Earth.
LoadMap is responsible for creating a new VELatLong object representing the selected country s longitude and latitude. It then pans the map to the proper location and adds a VEPushpin object on the country. This is done by creating a new VEPushpin object and giving it the VELatLong object, as well as the name of the country to show as the title of the pushpin. Other data can be passed to the VEPushpin constructor, such as a custom pushpin image path and a description that appears when a user mouses over the pushpin. Figure 7 shows what the sample application looks like in action.
Figure 7: Using ASP.NET AJAX
and Virtual Earth.
Conclusion
Microsoft s ASP.NET AJAX Extensions make it quick and easy to add AJAX functionality into new or existing ASP.NET pages by using the UpdatePanel control. While custom JavaScript code can be written to handle a variety of AJAX features, the UpdatePanel shields you from having to write JavaScript in many cases, and automatically handles making asynchronous XmlHttp requests.
In this article you ve seen how to use the UpdatePanel and triggers to cause asynchronous messages to be sent from the browser to the server. You ve also seen how to tie in to the client s page life-cycle by using the PageRequestManager class. Finally, you ve seen how to tie ASP.NET AJAX into the Virtual Earth map API to display maps and add pushpins. By learning the different features available in the ASP.NET AJAX framework, you can develop applications that provide end users with a more pleasant experience.
The source code accompanying this article is available for download.
Dan Wahlin (Microsoft Most Valuable Professional for ASP.NET and XML Web services) is a .NET development instructor at Interface Technical Training (http://www.interfacetraining.com). Dan founded the XML for ASP.NET Developers Web site (http://www.XMLforASP.NET), which focuses on using XML, ADO.NET, ASP.NET, AJAX, and Web services in Microsoft s .NET platform. He s also on the INETA Speaker s Bureau and speaks at several conferences. Dan co-authored/authored several books on .NET, including ASP.NET 2.0 MVP Hacks (Wrox), Professional ASP.NET AJAX (Wrox), and XML for ASP.NET Developers (SAMS). When he s not writing code, articles, or books, Dan enjoys writing and recording music and playing golf and basketball with his wife and kids. Dan blogs at http://weblogs.asp.net/dwahlin and http://blogs.interfacett.com/dan-wahlins-blog.
