Google Mapplets Developer Guide

Mapplets are mini-applications that run within Google Maps. Hundreds of developers have already created Mapplets that overlay information such as photos, weather conditions, and gas prices on the map. You can find these Mapplets and more in the Google Maps Directory.

Mapplets are new, so if you discover any problems in using them, we'd like to hear your feedback. We encourage you to join the Maps API discussion group to give us feedback.

Audience

This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. Mapplets are a special type of Google Gadget, so you should also consult the Google Gadgets API documentation.

We've recently reorganized the documentation to add more conceptual information and break out discussions into the following key areas:

• Mapplet Programming Basics
• Mapplet Events
• Mapplet Overlays
• Mapplet Services

All new developers should read both this document, which explains how to install and publish Mapplets, and The "Hello" World of Mapplets , which explains how to write them. If you're already familiar with the Google Maps API, then you may want to look at the section on How Mapplets Differ from the Standard Maps API. This guide does not assume that you're already familiar with the Google Gadgets API or the Google Maps API.

What are Mapplets?

A Mapplet is an XML file that wraps a mini-webpage. You can put anything inside this mini-webpage that you can put into a normal webpage, including HTML, Javascript, and Flash. Google provides a Javascript API that allows the Mapplet to communicate with the Google Maps site, fetch content from remote websites, and store user preferences.

When your Mapplet is run by a user, Google will fetch the Mapplet source code from your web server and then serve the mini-webpage within an IFrame on the Google Maps site. For security reasons, the mini-webpage is hosted on gmodules.com.

To reduce the load on your site, gmodules.com will cache the Mapplet source code for several hours. The only way to bypass the caching is to install the Developer Mapplet.

Important Developer Tools

Before you begin writing a Mapplet, you should first go to the Developer Tools section of the Google Maps Directory and add the following tools:

• Developer Mapplet: When this tool is installed, a "Reload" link will be added to each Mapplet you run. This allows you to bypass the automatic caching of your Mapplet source code. Trust us, you will quickly become frustrated if you don't have the Developer Mapplet installed.
• Mapplet Scratch Pad: This tool allows you to interactively write Mapplet code and immediately preview it. You can cut-and-paste all the examples from this guide into the Scratch Pad.

Writing Your Mapplet

Once you've properly set up your development environment, your next order of business is to write the mapplet itself. A Mapplet is simply some JavaScript code placed within a special Google Gadget designed to communicate with the main map on maps.google.com. A detailed walkthrough of writing a first Mapplet is contained within the "Hello World" of Mapplets section in Mapplet Basics.

Publishing Your Mapplet

You need to save your Mapplet on a public website. If you don't have your own, we recommend you try Google Page Creator. However, don't use the WYSIWYG editor. Instead go to the Site Manager and use the upload link on the right. Then click on the filename in the Uploaded stuff section to get the URL of your Mapplet.

Installing and Running Your Mapplet

Before you can run a Mapplet, you need to install it by going to the Google Maps Directory and clicking on the Add by URL link next to the Search Google Maps Content button at the top of the page. Then enter the URL of your Mapplet and click on the Add button. Then Mapplet will appear under the My Maps tab when you return to Google Maps.

Sharing Your Mapplet With Others

Use the following URL to let others run your Mapplet:

http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=< URL of your mapplet>

Users who click on this URL will be brought to a page that prompts them to install the Mapplet. For example, if the source code of your Mapplet is located at http://www.google.com/mapfiles/mapplets/distance/distance.xml then you would share the following URL:

http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=http://www.google.com/mapfiles/mapplets/distance/distance.xml

Submitting Your Mapplet to the Directory

If you would like your Mapplet to be included in the Google Maps Directory, then please use this submission form. Our goal is to fill the directory with high quality Mapplets that are useful and fun for users. While we won't be able to include everything that's submitted, we want to include as many as possible in the directory.

How Mapplets Differ from the Standard Maps API

The API calls for manipulating the map are derived from the standard Google Maps API and most are identical. However, you should be aware of the following subtle differences.

Simpler Initialization

<Require feature="sharedmap"/> automatically initializes the API for you, so you never have to manually load the Javascript library nor pass in an API key. You do not pass a <div> to the GMap2 constructor since it always returns a reference to the main map.

If a user has loaded your Mapplet, then you can safely assume they're using a browser compatible with Google Maps, so the GBrowserIsCompatible check is unnecessary and not supported in a Mapplet.

In the Google Maps API, we must "initialize" the map by positioning it via a setCenter() method. This positioning is not required in Mapplets, as we already have a properly initialized map.

We Disallow Non-standard Behavior

We don't allow Mapplets to change the standard behavior of Google Maps, so we have removed the methods that disable dragging, double click zooming, etc.

Communication with the Map is Asynchronous

Communication between a Mapplet and the Google Maps site is asynchronous. As a result, some methods behave differently than their standard Google Maps API counterparts. For the most part, operations that modify the map (e.g. setCenter(), addOverlay()) are identical to the operations in the Maps API. However, operations that obtain a return value from the map require a callback function. In Mapplets, we appended Async onto the names of all Maps API methods that are affected by this, and their return values are instead passed as an argument to the callback function.

For example, in the Maps API, one would write:

var zoom = map.getZoom();
alert("Current zoom level is " + zoom);
alert("This happens after you see the zoom level message");

Whereas in a Mapplet, this has to be written as:

map.getZoomAsync(function(zoom) {
  alert("Current zoom level is " + zoom);
});  
alert("This might happen before or after you see the zoom level message");

Often, you may need to perform several asynchronous requests at once. Rather than perform them serially or nest these requests within each other, Mapplets provides a GAsync() utility function to make several requests in a single call. To use GAsync(), pass it an object and the methods to call within quotes following that object, with a callback function as the final argument:

GAsync(map, 'getZoom', 'getCenter', function(zoom,center) {
  // code here
}

To perform requests on more than one object, pass additional objects with the methods in quotes immediately following that object:

GAsync(map, 'getZoom', 'getCenter', marker, 'getPoint',
  function(zoom,center,point) {
  // code here
}

Security Concerns and Info Window Sanitation

The Mapplet runs within an iframe that's hosted on gmodules.com so it cannot access Google user cookies or break the Javascript of the Google Maps site. However, the map (and everything displayed on it) is hosted on the maps.google.com domain, so when a Mapplet requests that we display an info window, we sanitize the info window contents before handing it over to the map. We do not allow Javascript inside the info windows, and we only allow a whitelist of HTML tags and CSS.

Furthermore, operations such as adding new map controls and map types currently require third-party Javascript code to be executed inside the map, so we have disallowed them for now.

Requests for Remote Data are Proxied by Google

Mapplets are served from gmodules.com which is located on a server run by Google. The browser's security model does not allow Javascript on gmodules.com to request data from any other domain, so you cannot use GDownloadUrl (nor GXml) inside your Mapplet to fetch data from your server.

Instead, the Google Gadgets API provides the following calls which will fetch content via a proxy running on gmodules.com:

• _IG_FetchContent(url, callback) -- Returns the content at url as text. Use this function to fetch HTML or plain text content.
• _IG_FetchXmlContent(url, callback) -- Returns and operates on the XML content at url as a DOM object. Use this function to fetch XML content which must be parsed.

These methods behave differently than GDownloadUrl and GXml in the following ways:

• The _IG_FetchContent and _IG_FetchXmlContent calls can fetch data from any website on the Internet.
• _IG_FetchXmlContent is stricter than GXml and requires that the XML file begin with <?xml version="1.0" encoding="UTF-8"?>
• The _IG_FetchContent and _IG_FetchXmlContent calls automatically cache the content to reduce the load on your servers. See the Refreshing the Cache section of the Gadgets API documentation for information on how to change the cache duration or disable caching.

How to convert an existing Maps API mashup into a Mapplet

If you already have an existing site built using the Google Maps API, see the article on Converting a Maps API Mashup into a Mapplet.

Continue on to the Mapplet Programming Basics.