The "VEMap.AddCustomLayer" method in the Bing Maps JavaScript Map Control can be used to add a DIV element to the Map, and have that same DIV element scroll/pan around the Map automatically. Even though Web.Maps.VE doesn't support using the "AddCustomLayer" method from within server-side code, you can still use a little bit of JavaScript on your page to hook into Web.Maps.VE to add any Custom Layers you need.

I've had a few requests for sample code on how to use the "VEMap.AddCustomLayer" method with Web.Maps.VE, so here's a full example that adds a custom layer, and a couple "custom" pushpins. Just copy the below code into an ".aspx" page and hit Run.

Conclusion

This is yet again one of the many ways that you can use JavaScript to enhance the already powerful Web.Maps.VE control to customize it to fit the exact needs of your application.

If you have any questions about using Web.Maps.VE, please post them to the Support Forums.

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.

The Web.Maps.VE v2.0 ASP.NET AJAX Virtual Earth Mapping Control comes with a couple of extender controls. These are additional controls contained within the controls Dll that basically add/extend the main Map control with additional functionality that’s not built-in. This tutorial is going to give you an overview of how to use the MiniMapExtender control to easily add a Mini Map to your Maps.

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 – Display a Virtual Earth Map on a Page” tutorial.

What is the MiniMapExtender?

The MiniMapExtender allows a Mini Map to easily be added to the Virtual Earth Map, and allows the Mini Map to easily be aligned to any side and/or corner of the Map automatically. The control is contained within the “Simplovation.Web.Maps.VE.Extenders” namespace.

Any time the Map is resized, or the user changes the size of the Mini Map; the MiniMapExtender will automatically adjust the positioning of the Mini Map to show according to its’ specified settings.

Below is a screenshot of the MiniMapExtender in action. The Mini Map is being automatically aligned to the Top Right corner of the Map.

Attach a MiniMapExtender to a Map

1. Open up the .aspx page with the Map on it, and select “Source” view.
2. Add the following Register directive to the top of the Page. This will include the Simplovation.Web.Maps.VE.Extenders namespace in the page, allowing you to place a MiniMapExtender control on the Page.

<%@ Register Assembly="Simplovation.Web.Maps.VE"
    Namespace="Simplovation.Web.Maps.VE.Extenders"
    TagPrefix="MapExtenders" %>

3. Add a MiniMapExtender to the Page and set its’ TargetControlID property equal to the ID of the Map. This tells the MiniMapExtender to attach itself to the specified Map control

<Simplovation:Map runat="server" id="Map1" Width="800" Height="600"></Simplovation:Map>

<MapExtenders:MiniMapExtender runat="server" ID="MiniMapExtender1" TargetControlID="Map1" />

It is important when declaring a MiniMapControl on a Page that you place its’ declaration AFTER the Map controls declaration. This is required since the Map control needs to be added to the Page’s control hierarchy before the MiniMapExtender is instantiated and tries to attach itself to the Map control. If you don’t do this you may get an exception, or the Mini Map simply will not be displayed.

By default, the MiniMapExtender will display the Mini Map in the Top Right Corner of the Map, and it’s size will be set to Small.

Set the Horizontal Alignment of the Mini Map

The MiniMapExtender.HorizontalSide property allows you to specify which horizontal side to automatically align the Mini Map. By default this property is set to align the Mini Map to the Right Side of the Map.

The HorizontalSide property accepts one of the following MiniMapHorizontalAlignment enumerations:

• Left – Aligns the Mini Map to the Left side of the Map.
• Center – Aligns the Mini Map to the Center of the Map.
• Right – Aligns the Mini Map to the Right side of the Map.

Here’s an example of setting the Mini Map to be automatically aligned to the Left Side of the Map:

<MapExtenders:MiniMapExtender runat="server" ID="MiniMapExtender1"
    TargetControlID="Map1"
    HorizontalSide="Left" />

Set the Vertical Alignment of the Mini Map

The MiniMapExtender.VerticalSide property allows you to specify which vertical side to automatically align the Mini Map. By default this property is set to align the Mini Map to the Top of the Map.

The VerticalSide property accepts one of the following MiniMapVerticalAlignment enumerations:

• Top – Aligns the Mini Map to the Top of the Map.
• Middle – Aligns the Mini Map to the Middle of the Map.
• Bottom – Aligns the Mini Map to the Bottom of the Map.

Here’s an example of setting the Mini Map to be automatically aligned to the Bottom of the Map:

<MapExtenders:MiniMapExtender runat="server" ID="MiniMapExtender1"
    TargetControlID="Map1"
    VerticalSide="Bottom" />

Set the Vertical and Horizontal Offset

The MiniMapExtender has a couple of Offset properties that allow you to specify the number of pixels to offset the automatic alignment of the Mini Map. This allows you to add “padding” to space the Mini Map away from the edge of the Map, vertically or horizontally.

The Offset properties are:

• HorizontalOffset – An Integer value that specifies the distance (in pixels) to space the Mini Map from the HorizontalSide edge of the Map. The default value is 0 pixels.
• VerticalOffset – An Integer value that specifies the distance (in pixels) to space the Mini Map from the VerticalSide edge of the Map. The default value is 0 pixels.

Here’s an example that spaces the Mini Map both vertically and horizontally from the edge of the Map by 10 pixels:

<MapExtenders:MiniMapExtender runat="server" ID="MiniMapExtender1"
    TargetControlID="Map1"
    VerticalOffset="10" HorizontalOffset="10" />

Manipulate the MiniMapExtender using JavaScript

The MiniMapExtender also includes a small JavaScript API that allows you to manipulate the display of the Mini Map from within client-side code after the Page has loaded.

The JavaScript API provides the following methods:

• ShowMiniMap – This method is used to make the Mini Map visible to the user. If the Mini Map is already visible then it does nothing.
• HideMiniMap – This method is used to Hide the Mini Map from view to the user. If the Mini Map is already hidden then it does nothing.
• SetMiniMapSize – This method is used to Set the Size of the Mini Map. You pass in the size via passing in a VEMiniMapSize enumeration value.
• SetHorizontalSide – This method is used to Set the Horizontal Side to automatically align the Mini Map. You pass in the horizontal side via passing in a Simplovation.Web.Maps.VE.Extenders.MiniMapHorizontalAlignment enumeration value.
• SetVerticalSide – This method is used to Set the Vertical Side to automatically align the Mini Map. You pass in the vertical side via passing in a Simplovation.Web.Maps.VE.Extenders.MiniMapVerticalAlignment enumeration value.

Before you can call the above MiniMapExtender JavaScript API methods, you need to obtain a reference to the MiniMapExtender itself. To do this you need to pass the MiniMapExtender.ClientID property from the server-side down to the client, then pass that value to the “$find” JavaScript method.

Here’s an example of what to place within your ASP.NET Page to get a reference to the MiniMapExtender on the client-side using JavaScript:

<script type="text/javascript">
    function getMiniMapExtenderReference() {
        return $find("<%=MiniMapExtender1.ClientID %>");
    }
</script>

Here are some samples of calling the MiniMapExtender JavaScript API methods using the above method that retrieves the MiniMapExtender’s Client-Side JavaScript Object:

<script type="text/javascript">
    function SetMiniMapPropertiesDemo() {
        // Get a Reference to the MiniMapExtender's JavaScript Object
        var miniMapExtender = getMiniMapExtenderReference();

        // Show the Mini Map
        miniMapExtender.ShowMiniMap();

        // Hide the Mini Map
        miniMapExtender.HideMiniMap();

        // Set the Mini Map Size to Small
        miniMapExtender.SetMiniMapSize(VEMiniMapSize.Small);

        // Set the Mini Map Size to Large
        miniMapExtender.SetMiniMapSize(VEMiniMapSize.Large);

        // Set the Horizontal Alignment to Left
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapHorizontalAlignment.Left
        );

        // Set the Horizontal Alignment to Center
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapHorizontalAlignment.Center
        );

        // Set the Horizontal Alignment to Right
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapHorizontalAlignment.Right
        );

        // Set the Vertical Alignment to Top
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapVerticalAlignment.Top
        );

        // Set the Vertical Alignment to Middle
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapVerticalAlignment.Middle
        );

        // Set the Vertical Alignment to Bottom
        miniMapExtender.SetHorizontalSide(
            Simplovation.Web.Maps.VE.Extenders.MiniMapVerticalAlignment.Bottom
        );
    }
</script>

There are also a couple of “undocumented” JavaScript methods (as of v2.00.03) contained within the MiniMapExtender’s JavaScript API. It is safe to call these methods, as they will not change in the future.

The two “undocumented” JavaScript methods are:

• set_HorizontalOffset – Sets the distance (in pixels) to space the Mini Map from the HorizontalSide edge of the Map.
• set_VerticalOffset – Sets the distance (in pixels) to space the Mini Map from the VerticalSide edge of the Map.

Here’s some examples of calling these methods using the previously mentioned method of obtaining a reference to the MiniMapExtender’s JavaScript Object:

<script type="text/javascript">
    function CallUndocumentedMethods() {
        var miniMapExtender = getMiniMapExtenderReference();

        // Set the Horizontal Offset to 10px
        miniMapExtender.set_HorizontalOffset(10);
            
        // Set the Vertical Offset to 10px
        miniMapExtender.set_VerticalOffset(10);
    }
</script>

Future Feature: The v2.00.04 update and later will contain the addition of official “SetHorizontalOffset” and “SetVerticalOffset” MiniMapExtender JavaScript API methods. Until this future update comes out, you’ll need to use the above mentioned “undocumented” methods to use JavaScript code to modify the MiniMapExtender’s Offset properties.

If you are looking for an additional reference on using the MiniMapExtender, please see the MiniMapExtender example within the Web.Maps.VE v2.0 Sample Website that is part of the Trial Edition Installer.

Conclusion

The MiniMapExtender control allows you to very easily Show and position a Mini Map on your Maps, and keep it automatically aligned to that position.

The other extender controls will be covered in additional tutorials.

The Web.Maps.VE v2.0 ASP.NET AJAX Virtual Earth Mapping control Raises a few of the Client-Side Virtual Earth Events up to Server-Side ASP.NET Code. One of these events is the Map.Click Event. The Map.Click Event gets raised each time the user clicks on the Map using the Mouse. This tutorial is going to give you an overview of how to handle the Map.Click event, and use it to add/remove pushpins, re-center the map and change the map zoom level.

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 – Display a Virtual Earth Map on a Page” tutorial.

Attaching an Event Handler to the Map.Click Event

In order to handle the “OnClick” event, we must first attach an Event Handler to the Map.Click Event. This is done exactly the same as attaching an event handler to any other event in .NET.

It can be done declaratively within markup like this:

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

Or, within code like this:

Map1.Click += new Map.AsyncMapEventHandler(Map1_Click);

If you decide to attach the event within code, then it is recommended that you attach it within the Page.OnLoad Event Handler. Also, the Map.Click event handler must be attached on the initial page load, and can not be attached during an Asynchronous Postback.

Once we have the event handler attached, we must declare our actual “Map1_Click” event handler method stub that we will place our “OnClick” event handling code within.

protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
}

The Map.Click Event Handler accepts two arguments. The first is of type Object, and is a reference to the Map object that fired the event. The second is of type AsyncMapEventArgs, and contains information about the client-side map event that just fired the event.

AsyncMapEventArgs Properties

The AsyncMapEventArgs objects properties are mostly a mirror of the client-side vemap event object propertieswith a couple exceptions/additions.

These are the AsyncMapEventArgs properties that are most relavent when handling the Map.Click event:

• altkey – A boolean value representing whether the ALT key was held down when the event was raised. Note: This is not supported in 3D mode.
• ctrlKey – A boolean value representing whether the CTRL key was held down when the event was raised. Note: This is not supported in 3D mode.
• latlong – A LatLong object that contains the Lat/Long Coordinates of the Clicked Location.
• leftMouseButton – A boolean value representing whether the Left Mouse Button was Clicked.
• MapView – A LatLongRectangle object that represents the current viewable area of the Map.
• middleMouseButton – A boolean value representing whether the Middle Mouse Button was Clicked.
• rightMouseButton – A boolean value representing whether the Right Mouse Button was Clicked.
• Shape – If a Shape was Clicked, then this will contain a reference to that Shape object.
• shiftKey – A boolean value representing whether the SHIFT key was held down when the event was raised. Note: This is not supported in 3D mode.
• zoomLevel – The current Zoom Level of the Map.

Add a Pushpin Shape at the Clicked Locations

To add a Shape (of Type Pushpin) to the Map during the Click event you just need to follow these steps within your Map.Click Event Handler:

1. Create a New Shape of Type Pushpin and set it’s Location to the value that’s contained within the AsyncMapEventArgs.latlong property.
2. Cast the “sender” method argument to type Map.
3. Invoke the Map.AddShape method, passing in the Shape that was just created.

This is fairly simple to do, and the resulting code is as follows:

protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
    // Create Pushpin at the Clicked Location
    var pushpinShape = new Shape(e.latlong);

    // Set the Pushpins Title and Description
    pushpinShape.Title = "Clicked Location";
    pushpinShape.Description = "A Description for the Clicked Location";

    // Cast "sender" as Map
    var map = (Map)sender;

    // Add the Shape to the Map
    map.AddShape(pushpinShape);
}

Center the Map on the Clicked Pushpin

To center the Map on the Clicked Shape (pushpin in this case) all you need to do is to check whether the AsyncMapEventArgs.Shape property is Null. If it’s not null, then the user clicked on an existing Shape. Then set the Maps Center Lat/Long equal to the center of the Pushpin Shape.

To do this, follow these steps:

1. Check if the AsyncMapEventArgs.Shape property is Null
2. If AsyncMapEventArgs.Shape is Not Null, then Center the Map on the Shape by setting the Map.LatLong property equal to the AsyncMapEventArgs.Shape.LatLong property

Here’s the code from above modified to center on the clicked pushpin, and to add a new pushpin when the user clicks anywhere else on the Map:

protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
    // Cast "sender" as Map
    var map = (Map)sender;

    // Check if a Shape was Clicked
    if (e.Shape != null)
    {
        // Shape was clicked, so center the Map on it

        // Set the Maps Center Location equal to the Pushpins Location
        map.LatLong = e.Shape.LatLong;
    }
    else
    {
        // Shape was not clicked, so add a new Shape at that Location

        // Create Pushpin at the Clicked Location
        var pushpinShape = new Shape(e.latlong);

        // Set the Pushpins Title and Description
        pushpinShape.Title = "Clicked Location";
        pushpinShape.Description = "A Description for the Clicked Location";

        // Add the Shape to the Map
        map.AddShape(pushpinShape);
    }
}

Zoom In on the Clicked Shape when the Shift Key is Held Down

To Zoom In the Map one zoom level at the same time you Center the Map on the Clicked Pushpin, all you need to do is increment the Map.Zoom property by 1 within the same Map.Click Event Handler.

To do this just add this line of code:

map.Zoom = map.Zoom + 1;

Remove the Clicked Shape on Right Mouse Click

To Remove the Clicked Pushpin when the user clicks on it using the Right Mouse Button, all you need to do is check if the AsyncMapEventArgs.rightMouseButton property is True and the AsyncMapEventArgs.Shape property is not null. Then if both those requirements are met, then just pass in the AsyncMapEventArgs.Shape properties value to the Map.DeleteShape method. The Map.DeleteShape method will remove/delete the passed in Shape from the Map.

Here’s the basic code that does this:

if (e.rightMouseButton && e.Shape != null)
{
    map.DeleteShape(e.Shape);
}

Complete Code Written Throughout This Tutorial

Here’s the complete code for the resulting Map.Click Event Handler from this entire tutorial:

protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
    // Cast "sender" as Map
    var map = (Map)sender;

    // Check if the Right Mouse Button was Clicked
    if (e.rightMouseButton && e.Shape != null)
    {
        // Delete/Remove the Clicked Shape from the Map
        map.DeleteShape(e.Shape);
    }
    else
    {
        // The Right Mouse Button was NOT Clicked

        // Check if a Shape was Clicked
        if (e.Shape != null)
        {
            // Shape was clicked, so center the Map on it

            // Set the Maps Center Location equal to the Pushpins Location
            map.LatLong = e.Shape.LatLong;

            // Zoom In one zoom level
            map.Zoom = map.Zoom + 1;
        }
        else
        {
            // Shape was not clicked, so add a new Shape at that Location

            // Create Pushpin at the Clicked Location
            var pushpinShape = new Shape(e.latlong);

            // Set the Pushpins Title and Description
            pushpinShape.Title = "Clicked Location";
            pushpinShape.Description = "A Description for the Clicked Location";

            // Add the Shape to the Map
            map.AddShape(pushpinShape);
        }
    }
}

Conclusion

As you can see the Web.Maps.VE v2.0 control makes it extremely simple to handle the Client-Side Virtual Earth Map Event from within Server-Side .NET Code; along with making it extremely simple to add shapes and/or manipulate the Map from within Server-Side .NET code.

Further details on adding Shapes (Pushpins, Polygons and Polylines) will be explained in an additional tutorial.

In this article we will go over the basics of implementing MS Virtual Earth mapping capabilities in ASP.NET 3.5 Web Applications using the Web.Maps.VE v2.0 ASP.NET AJAX Virtual Earth Mapping Server Control. This article also shows code examples in C#, but this are exactly the same if you are using VB.NET.

Prerequisites

This article assumes you have already downloaded/installed the following onto your development workstation:

• Microsoft Visual Studio 2008 or Visual Web Developer 2008 Express Edition
• Simplovation Web.Maps.VE v2.0

Create Website that is ready for Mapping

1. Run Visual Studio 2008 and create a New Web Site or ASP.NET Web Application Project.
   
   
   
2. Add a Reference to Simplovation.Web.Maps.VE.dll
   Right-Clicking the “Website Project” and select “Add Reference…”
   
    
   
3. Within the “Add Reference” dialog, Select the “Browse” tab and navigate to the folder where Web.Maps.VE is installed, and select “Simplovation.Web.Maps.VE.dll”.
   
   Note: By Default Web.Maps.VE is installed in this folder: “C:\Program Files (x86)\Simplovation LLC\Simplovation Web.Maps.VE v2.00.03”
   
   

Display a Map on the Page

1. Open the Default.aspx page, and select “Source” view.
2. Add the following Register directive to the top of the Page. This will include the Simplovation.Web.Maps.VE namespace in the page, allowing you to place a Map control on the Page.

   <%@ Register assembly="Simplovation.Web.Maps.VE"
       namespace="Simplovation.Web.Maps.VE"
       tagprefix="Simplovation" %>

3. Add an ASP.NET ScriptManager control to the top of the Page. This must be added to the Page above the Web.Maps.VE Map object that we’ll add later.

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

4. Add a Web.Maps.VE Map object to the Page so we can display a MS Virtual Earth Map.

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

Plot a Pushpin on the Map and Center on the Pushpin

1. Open the Code File (Default.aspx.cs) for the Page.
   
   In this example we’ll just place the Pushpin creation code within the Page Load event handler. You could just as easily use the Click event of an ASP.NET Button; this will be covered in an additional tutorial that will show how to manipulate the Map from server-side code during an Asynchronous Postback using the ASP.NET UpdatePanel control.
   
   
2. Create a Simplovation.Web.Maps.VE.LatLong object that will represent the Map Location that the Map will be centered on and the Pushpin will be located.

   var myLatLong = new Simplovation.Web.Maps.VE.LatLong(44.4023, –100.6347); 

3. Create a Simplovation.Web.Maps.VE.Shape object, set it’s Location to the above LatLong object, and give it a Title and Description for its InfoBox.

   var myShape = new Simplovation.Web.Maps.VE.Shape(myLatLong); 
   myShape.Title = "The Shape Title"; 
   myShape.Description = "Some description of the shape."; 

4. Add the Pushpin (aka Shape) to the Map by invoking the Map.AddShape method.

   Map1.AddShape(myShape); 

   This will add the Shape to the “Default” Shape Layer of the Map. Working with Shape Layers will be covered in more detail an an additional tutorial.
   
   
5. Center the Map on the specified location by setting the Map.LatLong property to the LatLong object we created with the code above.

Map1.LatLong = myLatLong; 

6. Now Run the Website by pressing F5 or selecting “Start Debugging” within the “Debug” Menu. You will see a Map on the Page that is centered on the Pushpin Shape we added using the above code.
   
    

Setting the Map Center Location (Lat/Long) using ASP.NET Markup

In addition to setting the Map’s Center Location using Code, you can also set it’s Center Location just as easily using markup. To do this, you just set the Map objects Latitude and Longitude properties to the location you want to center on.

<Simplovation:Map ID="Map1" runat="server" 
    Latitude="44.4023" Longitude="-100.6347"> 
</Simplovation:Map>

Setting the Map Zoom Level

The Maps Zoom Level can also be changed by setting the Map objects Zoom property. The Default Zoom Level of the Map is 4, and it accepts a range of 1 through 19.

To zoom a little closer to the Pushpin we added above, we can set it to a value of 6.

To do this in code:

Map1.Zoom = 6;

To do this in markup:

<Simplovation:Map ID="Map1" runat="server" 
    Zoom="6"> 
</Simplovation:Map>

Conclusion

As you can see it’s very simple to add a basic Virtual Earth Map to a Page, set it’s Location (Lat/Long and Zoom) and add a Pushpin to it.

In additional articles we will cover working with Web.Maps.VE in more depth; including some of the following topics:

• Manipulating the Map from Server-Side code leveraging ASP.NET UpdatePanel controls
• Handle Client-Side Map Events (such as: click, onchangeview, onendpan, onendzoom, etc.) from Server-Side code
• Working with Shape Layers
• Loading Driving Directions
• Extending the Map using JavaScript

As you can see this is just the beginning in a series of tutorials that will help you dive deep into the workings of Adding/Manipulating/Displaying MS Virtual Earth Maps using the Simplovation Web.Maps.VE ASP.NET AJAX Virtual Earth Server Control