Includes enterprise licensing and support
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.
This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. Mapplets are a special type of gadget, so you should also consult the gadgets API documentation.
We've recently reorganized the documentation to add more conceptual information and break out discussions into the following key areas:
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 gadgets API or the Google Maps API.
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.
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:
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 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.
You need to save your Mapplet on a public website so that you can refer to it when publishing to the Google Mapplet directory. If you don't have your own website, you may use any of a number of file hosting options, including:
Additionally, you can use the Google Gadget Editor to create and store your Mapplet. Within the Google Gadget Editor, you can save your gadget and obtain a URL to the saved gadget data.
Note: Some file hosting options, such as Google Project
Hosting, may require you to set your XML file's MIME type explicitly to text/xml.
Within Google Project Hosting you can accomplish this by using the svn propset
command as shown below:
command$ svn propset svn:mime-type text/xml filename.xml
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.
The simplest way to share your Mapplet, is to use the following URL which lets others run it immediately:
|
http://maps.google.com/maps/mpl&url=<URL of your
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/maps/mpl?moduleurl=http://www.google.com/mapfiles/mapplets/distance/distance.xml
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.
Once you have submitted your Mapplet to this directory, you can use the following URL to let others add your Mapplet to their 'My Maps' panel directly:
http://maps.google.com/gadgets/directory?synd=mpl&url=< 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/gadgets/directory?synd=mpl&url=http://www.google.com/mapfiles/mapplets/distance/distance.xml
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.
<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 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 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
}
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.
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 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:
_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"?>_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.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.