Mapplet Basics

The "Hello World" of Mapplets

The fundamental element in any Google Mapplet is the map itself, which is of course the map hosted on maps.google.com. This section discusses how to obtain a reference to the fundamental GMap2 object and the basics of map operations.

Mapplets are Gadgets

A Mapplet is a special type of gadget so we start by writing a gadget spec, which is just some XML with metadata. The HTML that's displayed to the user lives inside the <Content> tag — you can put anything inside it that you can put into a normal webpage.

The following example will display "Hello World!" in the left panel.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Hello World" 
             description="Displays a Hello World message in the left panel"
             author="Your name"
             author_email="your-email@gmail.com"
             height="150">
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

]]></Content>
</Module>

Run this example (hello-gadget.xml)

A Mapplet looks similar but contains Mapplets Javascript code, and some extra XML data that designates the gadget as a mapplet. The following example zooms out to a world view and adds a marker to the map with a "Hello World!" balloon.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="The Hello World of Mapplets" 
             description="Displays a Hello World message on the map!"
             author="Your name"
             author_email="your-email@gmail.com"
             height="150">
  <Require feature="sharedmap"/>
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

<script>
  // Center the map in the Mediterranean and zoom out to a world view
  var map = new GMap2();
  var point = new GLatLng(37.71859, 6.679688);
  map.setCenter(point, 2);

  // Add a marker to the center of the map
  var marker = new GMarker(point);
  map.addOverlay(marker);

  // Open a "Hello World" info window
  var message = "Hello World!";
  marker.openInfoWindowHtml(message);
</script>

]]></Content>
</Module>

Run this example (map-simple.xml)

Even in this simple example, there are three things to note:

1. We include <Require feature="sharedmap"/> in the mapplet.
2. We write some JavaScript to create a reference to the "map" object.
3. We center the map on a given geographic point.

These steps are explained below.

Loading the Google Mapplets API

<Require feature="sharedmap"/>

Adding <Require feature="sharedmap"/> within the <ModulePrefs> tag instructs the gadget to load the Mapplets Javascript API that allows it to communicate with the map. Inside the <Content> tag, we then add some Javascript code that talks to this API.

GMap2 - the Elementary Object

The JavaScript Mapplets class that represents the map is the GMap2 class. We create a new instance of this class using the JavaScript new operator. The Mapplet will automatically obtain a reference to the main map using this object.

var map = new GMap2();
var point = new GLatLng(37.71859, 6.679688);
map.setCenter(point, 2);

This code defines a variable (named map) and assigns that variable to a new GMap2 object. The function GMap2() is known as a constructor and its definition (from the Google Mapplets API Reference) is shown below:

Note that once we obtain the reference to the map, we then call the map's setCenter() method. The setCenter() method requires a GLatLng coordinate and a zoom level. Note that this positioning is not required in Mapplets, though it is required in the Google Maps API to initialize the map properly. In Mapplets, we already have an initialized map.

Basic Map Operations

Now that we know how to create a mapplet and initialize the mapplet code, we need a way to refer to locations on the map and perform basic operations. This section covers how to perform basic operations on the map using the Mapplets API.

Latitudes and Longitudes

The GLatLng object provides a way to reference locations within the Mapplet. You construct a GLatLng object, passing its parameters in the order { latitude, longitude } :

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

Note: the process of turning an address into a geographic point is known as geocoding and is discussed in detail in the Mapplets API Services section. Please consult that section for details on converting your addresses into geographic coordinates.

Just as it is useful to easily refer to a geographic point, it is also useful to define the geographic bounds of an object. For example, a map displays a current "window" of the entire world within what is known as a viewport. This viewport can be defined by the rectangular points at its corners. The GLatLngBounds object provides this functionality, defining a rectangular region using two GLatLng objects representing the southwest and northeast corners of the bounding box, respectively.

GLatLng objects have many uses within the Google Maps API. The GMarker object takes a GLatLng in its constructor, for example, and places a marker overlay on the map at the given geographic location.

The following example uses getBounds() to return the current viewport, and then randomly places 10 markers on the map within those bounds:

  var map = new GMap2();
  map.setCenter(new GLatLng(37.4419, -122.1419), 13);

  // Add 10 markers to the map at random locations
  var bounds = map.getBoundsAsync(function(bounds) {
    var southWest = bounds.getSouthWest();
    var northEast = bounds.getNorthEast();
    var lngSpan = northEast.lng() - southWest.lng();
    var latSpan = northEast.lat() - southWest.lat();
    for (var i = 0; i < 10; i++) {
      var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
        southWest.lng() + lngSpan * Math.random());
      map.addOverlay(new GMarker(point));
    }
  });

Run this example (map-markers.xml)

Note: more information on GMarker objects may be found within the Overlays section.

Map Attributes

By default, maps show up within the Google Maps API using standard "painted" tiles. However, the Google Maps API also supports other maps types. The following map types are standard:

• G_NORMAL_MAP- the default view
• G_SATELLITE_MAP - showing Google Earth satellite images
• G_HYBRID_MAP - showing a mixture of normal and satellite views
• G_DEFAULT_MAP_TYPES - an array of these three types, useful for iterative processing

You can set the map type using the GMap2 object's setMapType() method. For example, the following code sets the map to use the satellite view from Google Earth:

  var map = new GMap2();
  map.setMapType(G_SATELLITE_MAP);

A map also contains a number of attributes that are useful to ascertain. For example, to find the dimensions of the current viewport, use the GMap2 object's getBounds() method to return a GLatLngBounds value.

Each map also contains a zoom level, which defines the resolution of the current view. Zoom levels between 0 (the lowest zoom level, in which the entire world can be seen on one map) to 19 (the highest zoom level, down to individual buildings) are possible within the normal maps view. Zoom levels vary depending on where in the world you're looking, as data in some parts of the globe is more defined than in others. Zoom levels up to 20 are possible within satellite view.

You can retrieve the current zoom level in use by the map by using the GMap2 object's getZoomAsync() method.

Map Interactions

Mapplets should not be passive: you will want to interact with the map. The GMap2 object supports a number of methods that alter the map state programmatically. For example, the setCenter(), panTo(), and zoomIn() methods operate on the map, rather than through user interaction.

The following example jumps to Palo Alto, waits two seconds, and then pans to a new center point. The panTo method centers the map at a given point. If the specified point is in the visible part of the map (known as the viewport), then the map pans smoothly to the point; if not, the map jumps to the point.

var map = new GMap2();
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
window.setTimeout(function() {
  map.panTo(new GLatLng(37.4569, -122.1569));
}, 2000);

Run this example (map-animation.xml)

Opening an Info Window

Each map within the Google Maps API may show a single "info window", which displays HTML content in a floating window above the map. The info window looks a little like a comic-book word balloon; it has a content area and a tapered stem, where the tip of the stem is at a specified point on the map. You can see the info window in action by clicking a marker in Google Maps.

An info window is automatically attached to the map when you create the reference to the map with the GMap2() constructor. You can't show more than one info window at a time for a given map, but you can move the info window and change its contents as needed.

The GMap2 object provides an openInfoWindow() method, which takes a point and an HTML DOM element as arguments. The HTML DOM element is inserted into the info window container, and the info window tip is anchored to the given point.

To open an info window, call the openInfoWindow method, passing it a location and a DOM element to display. The following example code displays an info window anchored to the center of the map with a simple "Hello, world" message.

var map = new GMap2();
map.getCenterAsync(function(center) {
  map.openInfoWindowHtml(center, "Hello World");
});

Run this example (infowindow.xml)

Continue on to the Mapplet Event Model.