Tuesday, March 2, 2010

Developing with Online Mapping APIs - Part 2: Adding Controls to a Map

We've cleared the first hurdle. We have a page that is displaying a map and the map is zoomed and centered on the location we want. This might be useful when the site user has no need to manipulate the map, but in many cases the user will want to pan the map around, change the zoom level, or even view a different type of map. To allow the user to do these things we need to add controls to our map.

All four mapping services support a basic set of controls that allow the user to do the following:

  • Pan the map
  • Zoom the map (in or out)
  • Set the map type (road, satellite, topographical, etc.)

Panning the map is the act of moving the current map view North, East, South, or West. Zooming controls change the area that is visible within the map, as well as the level of detail. Map types allow for viewing simple road maps, topographical maps, satellite views, oblique aerial views, and much more.

These controls are available in various sizes and styles to best suite your display, whether it is small and simple controls for a mobile device or large 3D controls for a desktop scenario. Let's take a look at the controls for our four service providers.


Map Control Style: Normal Small Tiny None
Show Scale Legend
Show Mini Map
Show Map Type:

By default, the Bing map will display a road map with controls that allow for panning and zooming, as well as selecting from the available map types (Road, Aerial, and Bird's Eye). The controls are called the Dashboard, and are displayed and hidden via the ShowDashboard and HideDashboard methods on the VEMap instance.

Bing offers five types of maps to display.

  • VEMapStyle.Road // Road map
  • VEMapStyle.Shaded // Road map with shaded contours
  • VEMapStyle.Aerial // Satellite view
  • VEMapStyle.Hybrid // Satellite view with road map overlay
  • VEMapStyle.Oblique // Low altitude flight photo view
  • VEMapStyle.Birdseye // Same as Oblique
  • VEMapStyle.BirdseyeHybrid // An oblique view with a road map overlay

The map style is set via the VEMap.SetMapStyle method. In the sample map shown above, the onchange event of the select box calls a setMapType function, which sets the map type to display.

function setMapType()
 var bingMapTypeSelect = document.getElementById('bingMapTypeSelect');
 if ( bingMapTypeSelect.value == 'VEMapStyle.Road' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.Shaded' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.Aerial' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.Hybrid' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.Oblique' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.Birdseye' )
 if ( bingMapTypeSelect.value == 'VEMapStyle.BirdseyeHybrid' )

Bing offers three sizes of controls to display.

  • VEDashboardSize.Normal
  • VEDashboardSize.Small
  • VEDashboardSize.Tiny

The normal control style is the default, and includes controls for changing the map type, panning the map, and zooming. This is the best control to display for regular desktop viewing. The small control style is better suited to mobile devices with less screen real estate. Here the panning controls are missing, displaying only a small set of zoom controls and map type selectors. The tiny control style is the most terse, with only the zoom controls available. This mode is best for very small map display, such or low resolution mobile devices. The control style must be set before the map is loaded. Any attempt to change the map style after it is loaded will be ignored. The map controls can be hidden and shown after the map is loaded. The scale legend can also be hidden or displayed after the map has been loaded. The important control methods to know are:

  • VEMap.SetDashboardSize(VEDashboardSize); // Set the size of the controls (call before calling VEMap.LoadMap)
  • VEMap.ShowDashboard(); // Show the map controls
  • VEMap.HideDashboard(); // Hide the map controls
  • VEMap.ShowScalebar(); // Show the scale legend
  • VEMap.HideScalebar(); // Hide the scale legend

Bing also offers some features outside of the typical panning, scaling, and map type controls. One of these features is the inset map. The inset map displays the port of the map currently in the view and allows for easier panning. When the user pans within the inset map the current view is moved to where the inset map was panned to. The inset map may either display a road or aerial view, and can be positioned anywhere within the mapping frame.

  • VEMap.ShowMiniMap(xoffset, yoffset, VEMiniMapSize)
  • VEMiniMapSize.Large
  • VEMiniMapSize.Small

The offset and size parameters are optional. If not specified, a small inset map is displayed just below and to the right of where the map controls are displayed. The unfortunate drawback here is that it can be very difficult to properly place the inset map (for instance, if you wanted to anchor it in the bottom right corner) as the pixel dimensions of the inset map are not specified. In addition, inset map can be positioned on top of the regular controls, making them impossible to use.

If your users will be using Internet Explore, the 3D map type is available. This map type utilizes a control that the user must install. This map style allows for 3D exploration of the map, including 3D building representations. In my opinion, the 3D map offers little practical use, and the requirement for installation of an embedded control coupled with the limitation to the Internet Explorer browser only makes this a feature I would not immediately target. I have not included examples on how to use the 3D map for this reason.


Map Control Style: Large 3D Large Small None
Zoom Control Style: Small 3D Small None
Map Type Control Style: Standard Menu Hierarchical None
Show scale legend
Show Overview Map
Show Navigation Label Control
Show Map Type:

By default, the Google map does not display any controls. The user can still pan the map by clicking and dragging, and can zoom via the mouse wheel, but there are no dedicated controls on the screen. The Google Maps API provides a helper function on the GMap2 object to initialize the controls to the 'default' options that appear when using Google Maps on a desktop. These default controls include a panning control, zooming controls including a zoom scale bar, a map scale legend, and map type selector.

Google offers fifteen types of maps to display.

  • G_NORMAL_MAP // Road map
  • G_SATELLITE_MAP // Satellite view
  • G_AERIAL_MAP // Low altitude flight photo view
  • G_HYBRID_MAP // Satellite view with road map overlay
  • G_AERIAL_HYBRID_MAP // Low altitude flight photo view with road map overlay
  • G_PHYSICAL_MAP // Topographical map
  • G_MAPMAKER_NORMAL_MAP // Street map created using Google Mapmaker
  • G_MAPMAKER_HYBRID_MAP // Transparent overlay of major streets created in Google Mapmaker
  • G_MOON_ELEVATION_MAP // Terrain map of the lunar surface
  • G_MOON_VISIBLE_MAP // Photographic map of the lunar surface
  • G_MARS_ELEVATION_MAP // Terrain map of the martian surface
  • G_MARS_VISIBLE_MAP // Photographic map of the martian surface
  • G_MARS_INFRARED_MAP // Infrared map of the martian surface
  • G_SKY_VISIBLE_MAP // Map of the sky, displaying the celestial sphere
  • G_SATELLITE_3D_MAP // Utilizes Google Earth plug-in to display 3D model

While the moon, Mars, and Sky views are fun, for the purpose of this introduction I am going to concentrate on the typical road and satellite views. When the aerial view is unavailable the map will either display satellite imagery, or display empty tiles. In order to display aerial imagery the enableRotation method must be called on the map as well. The Mapmaker map types are composed of tiles submitted to Google Mapmaker from around the world. This map type can be useful when viewing areas of the world with poor map coverage through the standard mapping types. The map type can be set via code using the GMap2.setMapType method.

function setGoogleMapType()
 var googleMapTypeSelect = document.getElementById('googleMapTypeSelect');
 if ( googleMapTypeSelect.value == 'G_NORMAL_MAP' )
 if ( googleMapTypeSelect.value == 'G_SATELLITE_MAP' )
 if ( googleMapTypeSelect.value == 'G_AERIAL_MAP' )
 if ( googleMapTypeSelect.value == 'G_HYBRID_MAP' )
 if ( googleMapTypeSelect.value == 'G_AERIAL_HYBRID_MAP' )
 if ( googleMapTypeSelect.value == 'G_PHYSICAL_MAP' )
 if ( googleMapTypeSelect.value == 'G_MAPMAKER_NORMAL_MAP' )
 if ( googleMapTypeSelect.value == 'G_MAPMAKER_HYBRID_MAP' )
 if ( googleMapTypeSelect.value == 'G_MOON_ELEVATION_MAP' )
 if ( googleMapTypeSelect.value == 'G_MOON_VISIBLE_MAP' )
 if ( googleMapTypeSelect.value == 'G_MARS_ELEVATION_MAP' )
 if ( googleMapTypeSelect.value == 'G_MARS_VISIBLE_MAP' )
 if ( googleMapTypeSelect.value == 'G_MARS_INFRARED_MAP' )
 if ( googleMapTypeSelect.value == 'G_SKY_VISIBLE_MAP' )

Controls are added and removed from the Google map using GMap2.addControl(GControl) and GMap2.removeControl(GControl) respectively. The API supports a variety of pre-defined controls. There are three primary categories of controls: Panning and Zooming Controls, Zooming Only Controls, and Map Type Controls.

  • Panning and Zooming Controls
    • GLargeMapControl3D
    • GLargeMapControl
    • GSmallMapControl
  • Zooming Only Controls
    • GSmallZoomControl3D
    • GSmallZoomControl
  • Map Type Controls
    • GMapTypeControl
    • GMenuMapTypeControl
    • GHierarchicalMapTypeControl

The combined panning and zooming controls are useful for desktop browsing. The small version of the combined control is a good fit for small sidebar maps or mobile devices. The independent zoom control is useful for small screen resolutions and mobile devices as well. With both Bing and Google maps it is possible to create custom controls that facilitate any of these actions. However, it is useful to note that the Bing mapping API default controls do not allow for independent display of the map type control from the panning and zooming controls.

The Google map API also provides an inset map and a scale legend control. The inset map is called the Overview map. In addition, there is a control type called the Navigation Label Control. This is a "breadcrumbs" type control which will display a list of location names corresponding to zoom levels.

  • GOverviewMapControl
  • GScaleControl
  • GNavLabelControl

As with the Bing map, the Google map controls may be placed anywhere on the display aread by using the optional x and y offset parameters to the addControl method. By default, the panning and zooming controls appear in the upper left, the map type controls in the upper right, the scale legend in the lower left, and the inset map in the lower right. The navigation label control is also in the upper right by default and will compete with the map type controls for visibility.

Just as Bing maps offers a plug-in based view using the Bing Maps 3D plug-in, Google also permits the use of the Google Earth Plug-In. This map type utilizes the Google Earth Plug-In which the user must install. This map style allows for 3D exploration of the map, including 3D building representations. I will not be including any examples specific to the Google Earth Plug-In for the same reason that I do not reference the Bing Maps 3D plug-in.


Show Panning Control
Show Map Type Control
Show Scale Legend
Zoom Control Style: Long Short None
Show Map Type:

By default, the Yahoo map does not display any controls. The user can still pan the map by clicking and dragging, and can zoom with double-click, but there are no controls on the screen to facilitate this. The only default control is the map scale legend.

Yahoo offers three types of maps to display.

  • YAHOO_MAP_REG // Road map
  • YAHOO_MAP_SAT // Satellite view
  • YAHOO_MAP_HYB // Satellite view with road map overlay

The map type can be set via code using the YMap.setMapType method.

function setYahooMapType(mapTypeName)
 if (mapTypeName == 'YAHOO_MAP_REG')
 if (mapTypeName == 'YAHOO_MAP_SAT')
 if (mapTypeName == 'YAHOO_MAP_HYB')

Controls are added and removed from the Yahoo map using helper functions on the YMap instance.

  • Panning Controls
    • YMap.addPanControl()
    • YMap.removePanControl()
  • Zooming Controls
    • YMap.addZoomLong()
    • YMap.addZoomShort()
    • YMap.removeZoomControl()
  • Map Type Controls
    • YMap.addTypeControl()

Compared to the Bing and Google mapping API's, the methods for exposing controls on a Yahoo map are fairly terse. The position of the controls is not settable. Only the Zoom control has a style option, and this is to choose between a slider type zoom control and simple zoom in / zoom out controls. When switching between these styles you must first remove the existing style by calling the removeZoomControl method. The map type control can be added to the map, but is not removable.

Where both Bing and Google offer different sizes of controls, the Yahoo maps API has just one size. Fortunately the size of the controls is adequate to fit both a desktop and a mobile display.

The Yahoo map API also provides a scale legend control.

  • YMap.addZoomScale()
  • YMap.removeZoomScale()

The Yahoo map API does not include an inset map or 'breadcrump' navigation label feature. It also does not include any type of plug-in type display integration. These may sound like drawbacks, but they could also be considered a simplification of the API and display.


Show Panning Control
Show Map Type Control
Show Traffic Control
Zoom Control Style Large Small None
Show Map Type:

By default, the MapQuest map does not display any controls. The user can still pan the map by clicking and dragging, but there are no controls on the screen to facilitate this.

MapQuest offers three types of maps to display.

  • map // Road map
  • sat // Satellite view
  • hyb // Satellite view with road map overlay

The map type can be set via code using the MQA.TileMap.setMapType method. Keep in mind that the map types listed above are strings, not constants.

Show Map Type: <select id="mapquestMapTypeSelect" onchange="setMapquestMapType(this.value);">
  <option value="map">Road</option>
  <option value="sat">Satellite</option>
  <option value="hyb">Hybrid</option>
function setMapquestMapType(mapType)

Controls are added and removed from the MapQuest map using the MQA.TileMap.addControl and MQA.TileMap.removeControl methods. The addControl method takes a reference to the control to add, as well as an optional MQA.MapCornerPlacement instance for custom placement on the map. One thing to remember is that the reference to the MapQuest JavaScript API in our header had some extra parameters that we did not see with Bing, Google, or Yahoo. One of those parameters was the ipkg parameter, which indicates which optional JavaScript packages are available. If you remember, we included the 'controls1' and 'traffic' packages in this parameter. The 'controls1' package is required for displaying any controls on the map, so if you find that you are getting strange results when attempting to add controls, make sure this package is included.

  • Panning Controls
    • MQA.PanControl
  • Zooming Controls
    • MQA.ZoomControl
    • MQA.LargeZoomControl
  • Map Type Controls
    • MQA.ViewControl

The MapQuest controls are like the Yahoo controls in that there are only a few pre-defined control types, and they only come in one size. However, unlike the Yahoo controls, the MapQuest controls may be placed anywhere on the map. You may notice in playing with the map above that the LargeZoomControl includes a panning control. When using the LargeZoomControl it is not necessary to also add a PanControl.

The MapQuest map API will always display a scale legend. In addition, the MapQuest API also has an available Traffic control. Be sure that the JavaScript API reference includes 'traffic' in the list of included optional packages and this control will be available for display.

  • MQA.TrafficControl

The traffic control allows the user to overlay a traffic congestion heat map onto the displayed map type.

The MapQuest map API does not include an inset map or 'breadcrumb' navigation label feature. It also does not include any type of plug-in type display integration. These may sound like drawbacks, but they could also be considered a simplification of the API and display.

Is That It?

In the first post of the series we conquered simply putting the map on the page. Now we've added some controls that allow our site user to move around the map, change the map type, change the zoom level, and other types of navigation. In the next post we'll take a look at putting points of interest on the map. Until then, if you would like to read more about each API you can check out the following resources.

No comments:

Post a Comment