The Web.Maps.VE v2.0 ASP.NET AJAX Virtual Earth Mapping Control allows you to perform all you Map manipulations (moving the map, adding shape, loading driving directions, etc.) from within server-side .NET code. This is all fine when handling the Map’s own events, but what about using Buttons and Hyperlinks to perform manipulations? This tutorial will show you how to utilize the ASP.NET UpdatePanel control to be able to manipulate the Map during Server Control Events (such as OnClick).

Prerequisites

This tutorial assumes that you already have a basic understanding of how to place a Map on a Page within your ASP.NET Website or Web Application Project.

If you need to get an overview of how to place a Map on the Page, then I recommend you go check out the “Getting Started with Web.Maps.VE v2.0” tutorial.

Add Pushpin to the Map when user clicks on an ASP.NET Button or LinkButton Control

Once you have a Map control place on the page, you can then create an ASP.NET Button or LinkButton control and manipulate the Map during its OnClick Event. You can perform many different Map manipulations, including (but definitely not limited to) Adding Pushpins, Zooming In and Loading Driving Directions.

You would define an ASP.NET Button like this:

<asp:Button runat="server" ID="Button1"
    Text="Do Something" OnClick="Button1_Click" />

And, you would manipulate the Map during the Buttons OnClick event like this:

protected void Button1_Click(object sender, EventArgs e)
{
    // Zoom In
    Map1.Zoom++;

    // Change to Hybrid Map Style
    Map1.MapStyle = MapStyle.Hybrid;

    // Add Pushpin
    Map1.AddShape(new Shape(Map1.LatLong));
}

If you run the above example, you’ll notice that every time the user clicks the ASP.NET Button control the entire Page reloads and the Map is completely redrawn. Next we will link up the Buttons OnClick event to an ASP.NET UpdatePanel to cause it to manipulate the Map using an Asynchronous Postback without reloading the entire Page.

Manipulate the Map without reloading the Page

Now that we’re manipulating the Map during the OnClick event of an ASP.NET Button Control, it sure would be nice if we could manipulate the Map without reloading the entire Page and loosing all the current state of the Map (position, zoom level, currently plotted Shapes). This is where the ASP.NET UpdatePanel control comes in.

All we need to do is add an ASP.NET UpdatePanel control to the Page and add an AsyncPostBackTrigger for the Button Control’s Click Event. Also, since we aren’t using the UpdatePanel to update any visible html content, we will just leave it’s ContentTemplate “blank.”

To do this, just add the following code to the .aspx page that contains the Button control we created above:

<asp:UpdatePanel runat="server" ID="up1">
    <ContentTemplate></ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger
            ControlID="Button1"
            EventName="Click" />
    </Triggers>
</asp:UpdatePanel>

Now the Buttons Click event will be raised using an Asynchronous Postback, and any Map manipulations we perform within the Event Handler will be passed down to the Client and implemented on Map already being displayed to the user.

Why leave the UpdatePanel’s ContentTemplate “blank”?

The reason we leave the ASP.NET UpdatePanel’s ContentTemplate “blank” in the above example is because we don’t want it to update any of the Page’s content.

But we do want it to update the Map on the Page, don’t we? Yes, that is correct. Except this UpdatePanel with the “blank” ContentTemplate isn’t actually the one that’s updating the Map. The Map updates are actually performed by a “hidden” UpdatePanel that is part of the Map control itself. This is described below.

How does the UpdatePanel do this?

The Web.Maps.VE v2.0 Map control actually contains a “hidden” ASP.NET UpdatePanel control that it adds to the Page behind the scenes. This “hidden” UpdatePanel is caused to reload when ever any other UpdatePanel on the Page generates an Asynchronous Postback.

The “hidden” UpdatePanel also passes the current Map state (zoom level, center location, map style, map mode, currently plotted shapes, etc.) back up to the server every time other UpdatePanels on the Page generate Asynchronous Postbacks.

This automatic communication via the “hidden” UpdatePanel is what allows the Map control to automatically transfer it’s state back and forth between the client and server as needed, and is what enables this rich ajax functionality to work.

Can I place Content/Controls within the UpdatePanel’s ContentTemplate

Yes, of course. If you have any content (other than the Map) that you want to update on Asynchronous Postbacks you can definitely place that content within the UpdatePanel’s ContentTemplate.

For example you could display the Maps current Center Location on the Page by placing an ASP.NET Labal control within the ContentTemplate and setting it’s Text within the Button’s Click Event Handler.

To do this, just add the following line to the Button’s Click Event Handler:

lblCenterLocation.Text = Map1.LatLong.ToString();

And, add an ASP.NET Label control to the UpdatePanel’s ContentTemplate:

<asp:UpdatePanel runat="server" ID="up1">
    <ContentTemplate>
        <asp:Label runat="server"
            ID="lblCenterLocation">
        </asp:Label>
    </ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger
            ControlID="Button1"
            EventName="Click" />
    </Triggers>
</asp:UpdatePanel>

Some Tips on using the UpdatePanel Control

Here are a few things to note/remember when using ASP.NET UpdatePanel controls on the Page along with the Web.Maps.VE v2.0 Map control:

• Do not place the Map control within an UpdatePanel! It will cause the control to not function properly, and is not supported.
• If you have multiple Button, LinkButton or other server controls that will be raising Asynchronous Postbacks to Update the Map, then you’ll want to use only a single UpdatePanel with a “blank” ContentTemplate and add all the necessary AsyncPostBackTriggers to it.
• If you aren’t updating the Button, LinkButton or other Server Control that is firing the Asynchronous Postback, then don’t place it within the UpdatePanel’s ContentTemplate. This would just generate extra overhead and could affect the overall performance of the Page.

If you want to read some more Tips and Tricks on using the UpdatePanel control in general, then I recommend you read the “UpdatePanel Tips and Tricks” article by Jeff Prosise on MSDN. You may also be interested in the “Some ASP.NET AJAX Tips and Tricks” article I wrote a while back.

Conclusion

As you can see it’s fairly simple and straight forward to update the Map during an Asynchronous Postback. And, it can be done from any Server Control’s Event that can be wired up to an UpdatePanel using an AsyncPostBackTrigger.

One of the nice User Interface features to implement when using a Map to insert/edit location data within an application is the ability to allow the user to reposition a pushpin or shape by dragging it with the mouse. Neither Web.Maps.VE or Virtual Earth directly implement this functionality. However, the Virtual Earth Toolkit (VEToolkit) contains a DragShapeExtender component that allows for this functionality to easily be implemented using the Web.Maps.VE server control. This tutorial will cover the basics of hooking up the VEToolkit DragShapeExtender to the Web.Maps.VE Map to allow your users reposition shapes by dragging them with the mouse.

Prerequisites

This tutorial assumes that you already have a basic understanding of how to place a Map on a Page using Web.Maps.VE within an ASP.NET Website or Web Application Project. If you need an overview of how to place a Map on a page, then I recommend you go check out the Getting Started Tutorial.

It is also assumed that you have a basic understanding of JavaScript programming, but don’t worry only a tiny bit is needed for this tutorial.

Before you continue, you’ll want to go download the latest JavaScript release of the Virtual Earth Toolkit (VEToolkit) open source project.

Download VEToolkit Here: http://vetoolkit.codeplex.com/

Allow User to Create/Delete Shapes using the Mouse

First, you’ll need to create an empty ASP.NET Website or Web Application Project and add a Map to it’s Default.aspx page.

Before we hook up the VEToolkit DragShapeExtender to our Map to allow “draggable” shapes, we need to plot some shape on the Map. To do this we’ll use the following code within the Maps OnClick event handler to Plot New Shapes using the Left Mouse Button and Delete Existing Shapes using the Right Mouse Button.

protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
    if (e.leftMouseButton && e.Shape == null)
    {
        // If the user clicked on the Map using the Left Mouse Button and
        // they didn't click on an existing Shape, then Add a New Pushpin
        // Shape to the Map.
        Map1.AddShape(new Shape(e.latlong));
    }
    else if (e.rightMouseButton && e.Shape != null)
    {
        // If the user clicked on an existing Shape using thr Right Mouse
        // Button, then Delete that Shape from the Map.
        Map1.DeleteShape(e.Shape);
    }
}

Attach the above method to the Map.Click event using the following:

<Simplovation:Map runat="server" ID="Map1"
    OnClick="Map1_Click">
</Simplovation:Map>

If you need an overview of handling the Map.Click (“OnClick”) event, please read the “Basics of the Click Event” Tutorial.

Now that we have a mechanism that allows the user to dynamically add/remove pushpin shapes from the Map, we can go ahead and hook up the VEToolkit DragShapeExtender component.

Enable “Draggable” Shapes

To enable “draggable” Shapes, we need to incorporate the VEToolkit DragShapeExtender component into our example.

1. Copy the following two JavaScript files from the VEToolkit into your project.
   
   VEToolkit.Core.js
   VEToolkit.DragShapeExtender.js
   
   The VEToolkit.Core.js file contains the “core” functionality provided by the VEToolkit. I’m not going to go into what it all contains here, but it is required by the VEToolkit.DragShapeExtender.js; which contains the DragShapeExtender component.
   
2. Add <script> references to the Page Header to include the above two scripts:

<head runat="server">
    <title></title>
    <script src="scripts/VEToolkit.Core.js"></script>
    <script src="scripts/VEToolkit.DragShapeExtender.js"></script>
</head>

3. Declare a JavaScript method to be called once the Map has finished loading in the Page.

<script type="text/javascript">
    function Map1_ClientMapLoaded(map) {
        // The "map" variable will contain a reference to the client-side
        // Web.Maps.VE object instance.
    }
</script>

4. Set the above JavaScript Methods Name to the Map.OnClientMapLoaded property so it gets fired appropriately.

<Simplovation:Map runat="server" ID="Map1"
    OnClientMapLoaded="Map1_ClientMapLoaded">
</Simplovation:Map>

5. Now we need to create an instance of the VEToolkit.DragShapeExtender component within our OnClientMapLoaded JavaScript Event Handler, and hook it up to the Map to allow for Shapes to be “draggable.” To do this, copy the below <script> block into the page replacing the one we just created to add the Map1_ClientMapLoaded method.

<script type="text/javascript">
    // Global variable to hold a reference to the VEToolkit.DragShapeExtender.
    var dragShapeExtender = null;

    // This Method is called once the Web.Maps.VE Map Control has finished
    // loading on the Page.
    function Map1_ClientMapLoaded(map) {
        // The "map" variable will contain a reference to the client-side
        // Web.Maps.VE object instance.

        // Obtain a reference to the VEMap instance within the Web.Maps.VE
        // Map Control.
        var vemap = map.get_Map();
    
        // Create a new instance of the VEToolkit.DragShapeExtender and
        // attach it to the VEMap instance.
        dragShapeExtender = new VEToolkit.DragShapeExtender(vemap);
        
        // Set the DragShapeExtender to only allow Shapes to be dragged
        // using the Left Mouse Button
        dragShapeExtender.DragLeftMouseButton = true;
        dragShapeExtender.DragRightMouseButton = false;
    }
</script>

Conclusion

Event though this functionality isn’t built directly into Web.Maps.VE (or the MS Virtual Earth API) it’s extremely easy to implement with only a few lines of code. Now you have a nice example of how to allow users of your application to dynamically plot and reposition location data using a Map and their Mouse.

April 1st, 2009, Chris Pietschmann was awarded the 2009 Microsoft MVP (Most Valuable Professional) Award in the Windows Live Platform category for his contributions to the Microsoft Development Community over the past year.

View Chris Pietschmann's MVP Profile on Microsoft.com

Microsoft is pleased to recognize and award its Most Valuable Professionals (MVPs). We present the MVP Award to thank individuals for their exceptional contributions to technical communities worldwide. When a community participant sees an MVP in a technical community, whether in a newsgroup, as a user group host, a conference speaker, or a respondent in forums, that community participant can be confident that the information shared by the MVP will be of the highest caliber and will help every user make the most of the technology.

Overview of the Microsoft MVP Program