Web.Maps.VE v2.0 – Using the MiniMapExtender

by Chris Pietschmann 27. March 2009 20:14

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.

MiniMapExtender

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.
  3. <%@ Register Assembly="Simplovation.Web.Maps.VE"
        Namespace="Simplovation.Web.Maps.VE.Extenders"
        TagPrefix="MapExtenders" %>
  4. 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
  5. <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" />

MiniMapExtender_Offset10Pixels

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.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Tags: , ,

Web.Maps.VE v2.0 | Tutorials

Comments are closed