Using ASP.NET AJAX with the Web ADF

Bryan Baker of the .NET SDK team wrote this great article on integration ASP.NET AJAX with the Web ADF.   

Microsoft's new ASP.NET AJAX enables developers to refresh portions of a Web page in a relatively simple way. To enable a control to use AJAX, the developer can put the control inside an UpdatePanel. Then any events on the control are automatically handled via AJAX, and updates are passed back without refreshing the entire page. For example, a page might have two drop-down lists. The first lists types of features, such as Cities and Countries. When the user picks a value in the first drop-down, the second list is populated with new values corresponding to the first list's value, such as a list of cities.

Web ADF developers might want to use this approach to update the Map or other ADF controls. For example, when the user selects a city in the second drop-down list, the Map would zoom to the selected city. The problem is that ASP.NET AJAX was released after the 9.2 version of the Web ADF, and these new features were not available to be incorporated. Putting Web ADF controls inside an UpdatePanel will not work correctly, and is not supported. At 9.3 ESRI does plan to support Web ADF controls with ASP.NET AJAX.

You can have both Web ADF and ASP.NET AJAX controls on the page. The challenge is doing something like the example above, where controls in an UpdatePanel communicate with Web ADF controls. This post shows one approach for this. It turns out that it takes less than a dozen lines of code beyond what would have been needed had the Map been inside the UpdatePanel! You can follow along if you have installed Visual Studio 2005, the Web ADF, and the ASP.NET AJAX 1.0 extensions.

Note that the use of ASP.NET AJAX is not supported by ESRI for version 9.2 of the Web ADF. If you use ASP.NET AJAX, you must be prepared to resolve any issues you encounter with using the Web ADF. You may find help at the ESRI Forums, but ESRI Support will not be able to assist with development issues.

Add the controls

I first created a new website using the "ASP.NET AJAX-Enabled Web Site" template in Visual Studio. This creates a website and adds some extra items to support AJAX into both the Default.aspx page and the web.config file. You'll notice the ScriptManager control already added to the Default.aspx page, which is a non-visual control that handles the AJAX functionality. If you wanted to add ASP.NET AJAX into an existing page or website, you'd need to add these same items that the template adds in. See the ASP.NET AJAX documentation for details.

On the Default.aspx page, I added an UpdatePanel from the AJAX Extensions toolbox tab. I dragged two standard DropDownList controls into the UpdatePanel. The first DropDownList will display a list of layers. We could obtain these from the Web ADF controls on page startup, but I just added them manually for now to the Items property. I added two items: Cities and Countries. I also set the AutoPostBack property for both DropDownList controls to True. We need to do this to trigger a postback (actually a "partial postback" as ASP.NET AJAX calls it) when the user changes the selection.

Next I added a Map control and a MapResourceManager control from the ArcGIS Web Controls. Tip: having a drop-down list just above the map inteferes with the drop-down's functioning, so I put the map above the drop-down lists for this demo. I set the MapResourceManager property of the Map, and I added a resource item (map service) to the MapResourceManager as required to enable the map to display the service. In my case I used a world map with cities and countries. My simple page looks like the example here.

Update DropDownList items with ASP.NET AJAX

When the user changes the first drop-down list, the second list should display a list of cities or countries. Using ASP.NET AJAX allows us to treat this like a standard postback event. Behind the scenes, ASP.NET AJAX handles the request using AJAX methods rather than a full postback. Fortunately we don't have to deal with those details here.

I double-clicked on the DropDownList1 on the design page, which creates the method to handle the user selection in the code-behind page. We need to also fill the second DropDownList at startup, so we'll create a separate method and call it from both the drop-down's change method and the Page load method (which we can create by double-clicking on the design page). The UpdatePlaceList method fills the second DropDownList with locations and coordinates that we'll use later for zooming the map. The code below is in VB; both C# and VB versions are available in the download link at the end of this post.

Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load

    If Not Page.IsPostBack Then

        UpdatePlaceList()

    End If

End Sub





Protected Sub DropDownList1_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs)

    UpdatePlaceList()

End Sub



Sub UpdatePlaceList()

    DropDownList2.Items.Clear()

    If DropDownList1.SelectedValue = "Cities" Then

        DropDownList2.Items.Add(New ListItem("Cape Town", "17|-36|21|-32"))

        DropDownList2.Items.Add(New ListItem("Oslo", "9|58|13|62"))

        DropDownList2.Items.Add(New ListItem("Washington", "-79|37|-75|41"))

    ElseIf DropDownList1.SelectedValue = "Countries" Then

        DropDownList2.Items.Add(New ListItem("Australia", "112|-43|157|-10"))

        DropDownList2.Items.Add(New ListItem("Brazil", "-73|-33|-31|6"))

        DropDownList2.Items.Add(New ListItem("China", "75|16|136|55"))

    End If



End Sub



    

Zoom the Map when user selects a place

When the user selects a place in the second DropDownList, we need to zoom the map to the coordinates of that place. The challenge is to have the map's new extent be communicated to the client. Since the Map control cannot be in the UpdatePanel, we have to use another approach to communicate the results of the extent change to the Map.

The user selection in DropDownList2 triggers another partial postback. To set up the code for this, I double-clicked on DropDownList2 in design mode to create the method to handle the selected-index change. Inside this new method, I obtained the coordinates to zoom to from the DropDownList2.SelectedValue property. I parsed this value into an array of coordinate values, created a new envelope, and set the envelope's extent to these coordinates. I then set the Map's extent to this new envelope. This changes the map extent on the server. However, the client won't be aware of the change and won't obtain a new map unless we tell it to.

To get the client to update the map, we use a feature in ASP.NET AJAX to pass information to the client. The ScriptManager.RegisterDataItem method adds information that will be passed back and evaluated on the client.

The Map's CallbackResults will have the information required to update the map on the client. We pass this information to the client using the RegisterDataItem method. We'll see shortly how the client uses this information to update the map.

The code below obtains the callback results and registers them with the ASP.NET AJAX RegisterDataItem method. The ScriptManager1.IsInAsyncPostBack property ensures that we're doing an AJAX partial postback rather than a full page postback.

Protected Sub DropDownList2_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs)



    Dim zoomString As String = DropDownList2.SelectedValue

    Dim coordArr() As String = zoomString.Split("|")



    Dim new_extent As New ESRI.ArcGIS.ADF.Web.Geometry.Envelope

    new_extent.XMin = Double.Parse(coordArr(0))

    new_extent.YMin = Double.Parse(coordArr(1))

    new_extent.XMax = Double.Parse(coordArr(2))

    new_extent.YMax = Double.Parse(coordArr(3))

    Map1.Extent = new_extent



    If ScriptManager1.IsInAsyncPostBack Then

        Dim callbackString As String = Map1.CallbackResults.ToString()

        ScriptManager1.RegisterDataItem(Map1, callbackString)

    End If



End Sub



    

Handle the results on the client

The results that we just registered with ScriptManager need to be handled on the client. ASP.NET AJAX has a handler approach to process items passed back to the client. I inserted the code below into the .aspx page, at a point below the asp:ScriptManager tag. This code registers a client-side handler, the PageLoadingHandler function, that will run when the page loads. This handler obtains the items registered on the server with RegisterDataItem, and checks whether any items for the map control are present.  Since our server-side code added an item for the map, the code runs the next line.

This next line calls processCallbackResult and passes it the callback results we registered on the server. The processCallbackResult function is part of the Web ADF JavaScript library, which is automatically downloaded when the page uses Web ADF controls. The processCallbackResult function applies the callback results on the client by retrieving a new map. One caveat: the objects and methods in the client-side library can change, so this method could change with future versions of the Web ADF.

<asp:ScriptManager ID="ScriptManager1" runat="server" />



<script type="text/javascript" language="javascript">



    Sys.WebForms.PageRequestManager.getInstance().add_pageLoading(PageLoadingHandler);





    function PageLoadingHandler(sender, args) {

        var dataItems = args.get_dataItems();

        if (dataItems['Map1'] != null)

            processCallbackResult(dataItems['Map1'], 'Map1');

    }



</script>

With this code in place, when the user selects an item in the places drop-down list, the server sets the map extent to that place, and the map on the client gets notified to retrieve a new map.

Tip: be careful about dragging controls around the page in Design mode when script blocks are within the page body. Doing so caused Visual Studio to remove my script block, which disabled the map update since no handler was available on the client!

Conclusion

We've seen how you can use controls in an ASP.NET AJAX UpdatePanel to control a Map in the Web ADF. Although it takes more work than if the Web ADF controls were embedded in the UpdatePanel, it is possible to do these tasks now. In our case it required less than a dozen lines of additional code compared to when the controls are all inside the UpdatePanel.

Download the code for this demo (includes C# and VB)

Try it out here.