In usability we trust

In the first article in this series we discussed how to create a simple Map with Google Maps API 3. In this article we will explore the available properties when creating a map and see how we can change the look and behaviour of the map with the help of them.

The required properties

As we saw in the last article there are 3 required properties when creating a map. These are:

• center
  Takes a coordinate in the form of a google.maps.LatLng that defines the center of the map
• zoom
  Sets the initial zoom level of the map. It have to be an integer between 0 and 19 where 0 is fully zoomed out and 19 is fully zoomed in.
• mapTypeId
  Takes a constant of type google.maps.MapTypeId that defines what the initial map type would be

It’s pretty obvious how the two first properties work, but the last one, mapTypeId, requires a brief explanation. What it does is to tell the map what kind of map to display by providing it with a constant. There are a few map types to choose from and they are all contained in the namespace google.maps.MapTypeId. These are:

• ROADMAP
  A normal map
• SATELLITE
  Satellite images
• HYBRID
  Displays satellite images with roads and labels overlayed on it
• TERRAIN
  Displays a map with physical features such as terrain and vegetation

So for example, constructing a simple map with the maptype SATTELITE is done like this:

// Creating an object literal containing the properties we want to pass to the map
var options = {
  zoom: 6,
  center: new google.maps.LatLng(57.8, 14.0),
  mapTypeId: google.maps.MapTypeId.SATTELITE
};
// Calling the constructor, thereby initializing the map
var map = new google.maps.Map(document.getElementById('map'), options);

That code would produce a map that looks something like this.

Controlling the UI

Note that some user controls are displayed on the map by default. In the old API you had to explicitly define which controls that would show but in version 3 it works the other way around, you have to explicitly define which controls not to show.

diableDefaultUI [boolean]

Default value is false. By setting this to true you will disable the default UI. That is: the default zoom control and the map type chooser will not be displayed, much as the default behavior in the old API. You can however also enable or disable these controls individually.

mapTypeControl [boolean]

With this property you control whether the mapTypeControl will be displayed or not. The mapTypeControl is the control positioned in the upper right corner of the map from which you can choose what map type to show. Set it to true to display it and to false to hide it. The default value is true.

mapTypeControlOption

With this property you control how the mapTypeControl will be displayed. It can have one of the following values which all resides in the google.maps.MapTypeControlStyle namespace.

• DEFAULT
  The DEFAULT value will vary the look of the mapTypeControl depending of the size of the window and possibly other factors.
• HORIZONTAL_BAR
  This option will display the standard bar.
  
• DROPDOWN_MENU
  This will display the control as a drop-down list. It can be handy if the map is small or you want it to take as little space as possible for some other reason. It currently looks a little weird since the arrow is positioned over the text, but I suspect that it’s a temporary glitch that will be fixed in future releases.
  

If for example you want this control to display like a drop-down menu you define it like this:

var options = {
  zoom: 6,
  center: new google.maps.LatLng(57.8, 14.0),
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  mapTypeControlOptions: {
    style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
  }
};

Note that its parameter is an object literal with one property, style, which takes one of the constants in google.maps.MapTypeControlStyle as its value. This design might seem a little cumbersome at first but is actually pretty smart. It makes it easy to add more settings for the map type control in future releases of the API.

navigationControl [boolean]

This property displays or hides the navigation control. That is the control that typically resides in the upper left part of the map with which you can zoom and sometimes pan the map. Its appearance has changed a bit since the old version of the API but essentially works the same way. The major difference being that in the old API the large control had a “reset” button that reset the map to its initial state. This feature has been dropped in the new API for unknown reasons.

navigationControlOptions

The style of the navgationControl comes in 4 flavors that all resides in the google.maps.NavigationControlStyle namespace. These are:

• DEFAULT
  If set to this value, the control will vary according the map size and other factors. As of now that means that it will either display the small or the large control but that might change in future releases.
• SMALL
  This is the small control that only lets you to zoom the map.
  
• ANDROID
  This control looks like the SMALL one, but is supposed to be specifically tailored for the Android mobile platform.
• ZOOM_PAN
  This is the large control that lets you to both zoom and pan the map.
  

Here’s some example code on how to display the large control (zoom_pan).

var options = {
  zoom: 6,
  center: new google.maps.LatLng(57.8, 14.0),
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  navigationControlOptions: {
    style: google.maps.NavigationControlStyle.ZOOM_PAN
  }
};

scaleControl [boolean]

This property determines whether the scale control will be displayed or not. Set it to true to display the control and false to hide it. This control is not displayed by default, so if you want it to show you have to explicitly set this property to true.

The scale control is typically positioned in the lower left corner of the map and are used to get a sense of the scale of the map. It looks like this:

scaleControlOptions

You can control how the scale control will be displayed with the help of this property. It currently only has one option which is STANDARD so there’s really not much you can do, but this might change in future releases.

keyboardShortcuts [boolean]

There are some keyboard shortcuts for controlling the map. These are the arrowkeys for panning and +/- for zooming.

Default value is true. If set to false it will disable the keyboard shortcuts.

Map div behavior

The Map div is the HTML element that contains the map. Typically it’s a <div> with id="map" or something similar. There are some properties that controls the behavior of this.

noClear [boolean]

The default setting of this is false, and what it does is to clear the content of the div that contains the map. If set to true it will not clear the initial content of it.

backgroundColor [string]

This property also affects the map div. It sets the color of the div’s background which shows when you pan the map and before the map tiles have been loaded.

noResize [boolean]

Default value is false. If set to true it prevents the map from doing automatic resize checking.

Cursor behavior

Finally there are a couple of properties to control how the cursor will look like. These are:

draggableCursor

Sets the name or URL of the cursor that is displayed on a draggable object.

draggingCursor

Sets the name or URL of the cursor that is displayed when an object is dragged.

Note: As of the time of writing these properties doesn’t seem to work properly. This will hopefully be fixed in a near future.

Live Demo

I’ve put together a Live Demo where you can try out some of the properties of the map and see how they affect it.

Conclusion

In this article we’ve examined the properties available when initializing a map in Google Maps API 3. These properties affect the look and behavior of the map. There are additional methods that can be used to alter these properties, but they will be covered in a future article. In the next article we will look at how to work with markers in the new API.

This article was published on Wednesday, June 24th, 2009 in Articles.