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

We have just launched a new Simplovation Company Blog, and it will replace the existing blog. The new blog utilizes the awesome BlogEngine.NET open source blogging engine software, and will allow us to better provide news, content and other support related articles to our customers.

New Url: http://blog.simplovation.com

Rss Feed: http://feeds2.feedburner.com/simplovation