Since both Web.Maps.VE v2.0 and the AjaxControlToolkit are both built on top of ASP.NET AJAX, they compliment each other very well when used together to easily create some very dynamic user experiences. One of the requests we've gotten a few times is to give an example of how to show a Popup over the Map when a user clicks on a specific pushpin. This example demonstrates just such an example using both Web.Maps.VE v2.0 and the AjaxControlToolkit's ModalPopupExtender control.

Download Source Code: WebMapsVE_2.0_PopupWindowDemo.zip (753.58 kb)

This demo website also allows you to easily manipulate the Pushpins/Shapes on the Map in the following ways:

1. Left Click an Existing Pushpin to Edit it's Title and Description using a Popup Dialog
   
2. Left Click to Add a New Pushpin and enter the Pushpins Title and Description using a Popup Dialog 
3. Hold the Control (Ctrl) Key while Left Clicking on an Existing Pushpin to Delete it from the Map

The total source code for this example is pretty short, and it demonstrates how to perform the above mentioned actions all from within Server-Side .NET code. There is actually No JavaScript written to wire everything up with this example.

Also, once you download this demo website, you'll need to do the following 2 things before you can Hit Run within Visual Studio:

1. Download Web.Maps.VE v2.0 from http://simplovation.com/download
2. Copy the "Simplovation.Web.Maps.VE.dll" file into the "Bin"
   folder within this demo website.
   

 

Yesterday, Microsoft announced that its Live Search, Live Search Maps and Virtual Earth products will be rebranded to be under the "Bing" product name / branding. Live Search Maps will now be called Bing Maps, and Microsoft Virtual Earth will now be called "Bing Maps for Enterprise."

How does this relate to Simplovation and Web.Maps.VE?

Simply put, the transition from "Virtual Earth" to "Bing Maps for Enterprise" will be seamless. You will not need to download any updates from us to keep your maps working after the branding has changed. The Bing Maps for Enteprise JavaScript API will be downloaded from the existing URL that it is toda; the only difference is they will be changing the logo displayed on the map from "Virtual Earth" to say "Bing Maps" or "Bing Maps for Enterprise".

Also, we will not be making any breaking changes to Web.Maps.VE like changing the namespaces or product name. Web.Maps.VE v1.0 and v2.0 will remain "Web.Maps.VE" and the namespace will remain "Simplovation.Web.Maps.VE."

More Information:

Rebranding Microsoft Virtual Earth To...

Today we released the Web.Maps.VE v2.00.04 update release. This release includes a few new features that have been asked for by our customers, along with a couple of bug fixes.

Download Here

Here's a list of changes made in this update release:

New Features:

• MiniMapExtender Control JavaScript API - Added "SetHorizontalOffset" and "SetVerticalOffset" methods to the MiniMapExtender Control's Client-Side JavaScript API. Their usage is mentioned in the "Using the MiniMapExtender" Tutorial.
• Easily Resize the Map from Server-Side .NET or Client-Side JavaScript code - Added the capability for the Map controls Height and Width to get passed to/from the client and server during an asynchronous postback. Now when you change the Height or Width it will get reflected in the Map on the client. This release also added the "GetWidth" and "GetHeight" JavaScript API methods and fixed the "Resize" method so you can eaily and correctly resize the Map from within JavaScript. Both Server-Side and Client-Side examples have been added to the Sample Website.
• Color.FromHtml Method - The FromHtml static/shared method has been added to the Simplovation.Web.Maps.VE.Color object to allow for simple conversion from an HTML Color representation to the equivalent Simplovation.Web.Maps.VE.Color representation.
  

Fixes:

• Removing Multiple ShapeLayers during Async Postback - An issue with using the Map.Layers.Remove(), Map.Layers.RemoveAt() and Map.Layers.RemoveAll() methods to remove multiple shape layers during the same asynchronous postback was fixed.
• Rare Exception Thrown During Map.OnPreRender during Asynchronous Postbacks - Added an extra check that will reload the License file in case it happens to be Null during the OnPreRender method. Added some extra checks that will throw an exception with a meaningful message if the Page.Header happens to be Null.

You can view more details on each update release in the Web.Maps.VE v2.0 Product Roadmap.

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

Today we released the Web.Maps.VE v2.00.03 update release. This releae includes a few new features that have been asked for by our customers. One of these features is a .CHM Help File with full namespace/class documentation.

Download Here

Also, beware that there is a small change to the LatLong object that may be breaking, but the change was necessary. A description of this change is below.

Here's a list of changes made in this update release:

New Features:

• .CHM Help File - This is the first release that also includes a .CHM Help File with full Namespace/Class documentation for the Simplovation.Web.Maps.VE.dll library.
  
• Map.EnableBirdseye Property - A Boolean value that specifies whether or not to enable the Birdseye map style in the map control. The default value is True.
• Map.EnableDashboardLabels Property - A Boolean value that specifies whether or not lables appear on the map when a user clicks the Aerial or Birdseye map style buttons on the map control dashboard. The default value is True.
• Map.LoadBaseTiles Property - A Boolean value indicating whether or not to load the base map tiles. The default value is True.
• Map.BirdseyeOrientation Property and Orientation Enumeration - A Orientation Enumeration value indicating the orientation of the bird's eye map. The default value is Orientation.North.
• Map.UseVirtualEarthStagingUrl Property - A Boolean value that specifies whether to use the MS Virtual Earth Staging Url for pulling in the Virtual Earth JavaScript API. The default value is False.
  

Possible Breaking Changes:

• LatLong.Latitude and LatLong.Longitude properties have been changed to the Nullable Double type, from just a regular Double that they were in previous releases. Most code should work correctly with this change, but be aware of it in case it causes exceptions when upgrading to this update release. This change was made so that more compatible support for Birdseye Map Style could be implemented.

You can view more details on each update release in the Web.Maps.VE v2.0 Product Roadmap.

Today we released the Web.Maps.VE v2.00.02 Update Release.

Download Here

Here's a list of changes made in this update release:

New Features:

• Added Map.GetShapeByTag(tag) Method to JavaScript API - This method allows you to retrieve the VEShape object using JavaScript that has its' Tag ("SimplovationTag") property set to the value passed in.
• Added LocationLink.ShapeTag and LocationButton.ShapeTag Properties - The ShapeTag property allows you to set the Tag value of the Shape you want to center the map on.
• Added example within the Dynamic Search example in the Sample Website that demonstrates how to show a Shape's InfoBox when you click on the Item in the List below the Map.
  

Enhancements/Changes:

• Fix JSON Serialization issue caused by running on .NET 3.5 SP1.
  
• Fixed Serialization issue involving LatLong object and the Map.GetDirections method.
• Fixed OnClick Cast to Double Exception when in Birdseye Map Style
• Fixed Deserialization Error when Deserializing AsyncMapData - The "value '51.5' cannot be parsed as type 'Int32'" error sometimes occured, so this fix uses the JavaScript parseInt method on the client-side prior to posting the data back to the server to prevent this error. This error applied to the AsyncMapData.EventArgs.mapX, AsyncMapData.EventArgs.mapY, AsyncMapData.EventArgs.clientX, and AsyncMapData.EventArgs.clientY properties. - link to info about it: http://simplovation.com/forums/thread.aspx?id=53f14ffe-48ec-4ede-a7ca-6e68e11757fc
• Remove "Shape Not Found" prompt - This caused issues when clearing the shapes from the map in some cases, where it would show this prompt for each shape it couldn't find, which could be all shapes plotted before the Asynch Postback was raised. Removing this prompt will suppress it and not cause any adverse effects to the control.
• Pulls in the New Virtual Earth v6.2 Map Control API to be able to take advantage of any bug fixes made to the Virtual Earth in the latest release.
  

You can view more details on each update release in the Web.Maps.VE v2.0 Product Roadmap.