Google Maps API for Flash (Deprecated)

Google Maps API for Flash - Flex SDK Tutorial

Setting Up the Flex SDK Environment

Note: Before proceeding with this tutorial, make sure you've installed the Maps API for Flash SDK and obtained a Maps API key as indicated in Setting Up Your Development Environment.

This tutorial discusses how to obtain and set up the Adobe Flex SDK, how to set up your development environment, and how to program in ActionScript to build your first Google Maps API for Flash map.

Note: if you wish to use the FlexBuilder IDE, consult the FlexBuilder Tutorial instead.

Obtaining and Installing the Adobe Flex SDK

Incorporating Google Maps into a Flex application requires understanding not only ActionScript code but Flex MXML files. The examples in this documentation use the freely available Adobe Flex 3 SDK available at the following URL address:

http://www.adobe.com/products/flex/overview/#section-3

Note: The Flex SDK requires Java 1.4 or 1.5 (depending on the development platform). Full requirements for development with the Flex SDK are available at:

http://www.adobe.com/products/flex/systemreqs/

Once you've downloaded the SDK, unzip it into a working directory and ensure that you can execute the MXML Compiler (mxmlc) from the command line. The mxmlc compiler is located in the Flex SDK's bin directory. Executing the compiler with the -help option should result in the following output.

hostname$ cd flex_sdk/bin
hostname$ ./mxmlc -help
Adobe Flex Compiler (mxmlc)
Version 3.0.0 build 477
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.
...

You may also want to add the flex_sdk/bin directory to your $PATH so that you can execute the compiler from any directory.

Obtaining the Debug Flash Player

Before you begin development, you should first install a Debug version of the Adobe Flash Player. Debug versions of the player are available at the following URL:

http://www.adobe.com/support/flashplayer/downloads.html

You may need to uninstall any non-debug versions of the Flash player and/or shut down your browser to successfully install the debug version.

Setting Up Your Development Directories

New! The Google Maps API for Flash now offers native support for the com.google.maps.Map object within Flex. You no longer need to extend the Map class to define your Map application class, and you can use a Map component directly within Flex.

Flex applications are defined within MXML declarations. Generally, you should provide these MXML files in the root of your source code directory.

# Google recommends that you create a "source" directory in the root of your 
# Application development directory
# "Source" MXML application definitions will go here:
hostname$ cd myflashapp
hostname$ mkdir src

Using Namespaces to Manage Extensions

Components that extend any existing Google Maps API for Flash components should generally be provided as ActionScript libraries within a unique namespace. Google recommends that you use a namespace which you own to prevent collisions with other libraries; this is especially important if you will have many developers working on multiple flash components at the same time. Using namespaces also allows you to bundle your library code into packages, which allow easier sharing of common code.

Packages and namespaces should be defined using your top level domain, your organization domain, and sub-domain. For example, the Google Maps namespace is defined as com.google.maps and an examples package within that namespace would be defined as com.google.maps.examples. You can then use this namespace to implicitly define the directory structure of your application (e.g. com/google/maps/examples/).

# Google recommends that you create a directory structure based on a unique
# namespace for development of application extensions
# Source ActionScript file will go here:
hostname$ cd myflashapp
hostname$ mkdir your_unique_domain (e.g. com/google/maps/examples)

You use this namespace to define a package within your ActionScript code, and to define your application within the MXML declaration. Generally, ActionScript code (*.as files) reside within the bottommost directory of whatever namespace is defined, while the MXML declarations (*.mxml files) reside at the "root" of the directory structure.

Writing the "Hello World" of the Maps API for Flash

The easiest way to start learning about the Google Maps API for Flash is to see a simple example. In this tutorial, we'll create a simple MXML file containing a map using ActionScript code, compile that file into a SWF file using the Flex SDK, include that SWF file in an HTML page, and display it.

MXML Declarations

The MXML declaration defines UI elements within a Flex application, while embedded ActionScript code within the <mx:Script> tag defines actions on those UI elements. In the simplest case, you simply declare a com.google.maps.Map object within MXML and initialize the map with ActionScript code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" key="API_KEY" sensor="true_or_false"/>
<mx:Script>
    <![CDATA[
   
    import com.google.maps.LatLng;
    import com.google.maps.Map;
    import com.google.maps.MapEvent;
    import com.google.maps.MapType;

    private function onMapReady(event:Event):void {
      this.map.setCenter(new LatLng(40.736072,-73.992062), 14, MapType.NORMAL_MAP_TYPE);
    }
    ]]>
</mx:Script>
</mx:Application>

This example is located at gmaps-samples-flash.googlecode.com/svn/trunk/examples/HelloWorld.html. (MXML source is located here.) Note that you'd need to build your own SWF file, with your own API key, for this example to appear on your website.

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

  1. We declare an initial <mx:Application> to hold all of our code, as is required for Flex applications. Within this <mx:Application> object, we declare an xm namespace to reference the standard Flex components.
  2. We declare a Map object as a child of the <mx:Application> and define a maps namespace to reference code from com.google.maps.*. We also define parameters including an id, a mapevent_mapready handler, an API key, and a sensor state. These parameters will be explained later.
  3. We define ActionScript code within a child <mx:Script> object.
  4. Within that ActionScript code, we center the map on a location upon receipt of the mapevent_mapready event.

These steps are explained in more detail below.

Declaring Applications

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

Google Maps Flash applications require not only ActionScript code but also a user interface framework to display the map and any associated UI elements on a web page. Within the Flex framework, these UI components are specified within an MXML declaration. An MXML declaration consists of a configuration file with the .mxml suffix. This MXML file commonly resides in the root of your ActionScript development directory.

To display your Flash map on a webpage, you will need at least one MXML declaration. All MXML declarations require a root <mx:Application> component. Additionally, the <mx:Application> also registers the mx prefix to reference standard Flex components.

Note that MXML declarations can be quite complex, and the layout of UI components within an MXML declaration is beyond the scope of this documentation. For more information, see the provided examples and consult the Flex SDK documentation.

Declaring the Map

<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" key="API_KEY" sensor="true_or_false"/>

The Google Maps API for Flash now includes native support for the Map object defined within the com.google.maps.* package. We add a Map here as a child of the <mx:Application>, define its namespace as maps (linking it to the com.google.maps.* code), set an id which we can reference the map from within the ActionScript code, and define a mapevent_mapready handler. (See Setting Up Event Listeners below.)

The <maps:Map> declaration also specifies width and height parameters to define how the Map will appear within the application. More importantly, the MXML declaration acts as a convenient location to place your unique API key.

Writing the ActionScript Code

<mx:Script>
    <![CDATA[
    
    // ActionScript Code
    
    ]]>
</mx:Script>

Maps within the Google Maps API for Flash are manipulated using ActionScript 3.0 code. This tutorial will not attempt to teach the nuances of ActionScript. Online tutorials on ActionScript are available at the following locations:

The <mx:Script> object is a Flex component that holds a reference to the ActionScript code. Because MXML is a variant of XML, we also need to inform the MXML parser to ignore the ActionScript code within this file through use of the <![CDATA[][ and ]]> delimiters.

Note: you may instead wish to provide your ActionScript within separate ActionScript (*.as) files. If you do so, you can reference the ActionScript file by including a source parameter in the <mx:Script> tag:

<mx:Script source="HelloWorld.as"></mx:Script>

Placing code within separate files often makes sense if you have large or complex applications. However, within this document base, we will show all code inline within MXML declarations for simplicity.

Importing Libraries

    import com.google.maps.LatLng;
    import com.google.maps.Map;
    import com.google.maps.MapEvent;
    import com.google.maps.MapType;

ActionScript libraries are imported with the import declaration. In the sample code above, we import several Google Maps Flash libraries.

You should ensure that you import libraries for types that you need within your sample code. We recommend that you import only those classes you need. In most of the examples within this documentation, we structure our code so that the <mx:Application> does not use Flex UI components. Doing so provides a basic lightweight map. Note that including any Flex libraries may substantially increase the size of your SWF files, even if you only need one particular Flex component (such as a button).

Setting Up Event Listeners

ActionScript, like JavaScript, is an event-driven programming language. User Interactions within Flash objects are handled by registering event listeners on objects for specific events.

In the code snippet in the previous section, the Map declaration added an event listener to the Map object for the MapEvent.MAP_READY event through the use of the special parameter mapevent_mapready. This event handler acts as the "hook" for initialization of the Google Maps API for Flash application. When the map receives that event, it calls the onMapReady function, which is shown below.

function onMapReady(event:MapEvent):void {
  setCenter(new LatLng(40.736072,-73.992062), 14, MapType.NORMAL_MAP_TYPE);
}

This onMapReady() function passes an event parameter of type MapEvent (which is ignored in this case) and then calls setCenter() using the given parameters (which define a location, a zoom level, and the type of map to show).

In general, it is good to "initialize" your map in such a manner by intercepting and handling the MapEvent.MAP_READY event. Events are discussed in more detail within the Map Events section of the Google Maps Flash documentation.

Note: You may also initialize your map by intercepting and handling the MapEvent.MAP_PREINITIALIZE event instead. For information on this event, see the discussion of MapOptions.

Events are discussed in more detail within the Map Events section of the Google Maps Flash documentation.

Compiling Your SWF File

We now have a HelloWorld.mxml within our source's root directory and ActionScript code within that file's <mx:Script> object. We are ready to compile our code into a SWF (Shockwave Flash) file. We do so using the Flex SDK's mxmlc compiler.

The mxmlc compiler requires a target *.mxml file. As well, to use the Google Maps API for Flash, we use the compiler's -library-path parameter to add the location of the Google Maps API for Flash Library (maps_flex_1_7.swc) provided to you. A sample invocation appears below:

# Execute this command from the ROOT of your development directory, not from within 
# the leaf of the namespace (e.g. not in com/google/maps/examples)
#
hostname$:~/src/helloworld$ path_to_flex_sdk/bin/mxmlc HelloWorld.mxml -library-path+=maps_flex_1_7.swc
Loading configuration file /home/src/flex_sdk/frameworks/flex-config.xml
/home/src/helloworld/HelloWorld.swf (22223 bytes)

If you have trouble compiling:

  • Ensure you can execute the mxmlc compiler (you may want to change your path to add the Flex SDK's bin directory.
  • Ensure your MXML and ActionScript files are set up within the proper directory structure to reflect your declared namespace.
  • Ensure you add the library-path parameter using the "plus equals" operator (+=).

Once you have a HelloWorld.swf file, you can then place that file within a web page.

Hosting Your SWF File in a Web Page

Google Maps Flash SWF files, if they are compiled with the API key included, can simply be displayed as standalone files. This is useful for testing, but may not be practical for proper page layout. As a result, you will likely want to set up an HTML page to contain the SWF file. To ensure your SWF file executes within both Internet Explorer and other browsers, you should add the SWF within both object and embed tags.

A simple HTML page that contains our HelloWorld.swf file appears below. For the map to display on a web page, we must reserve a spot for it. We do so in this example by creating a named div element and adding the object element to it.

  <div id="map-canvas" name="map-canvas">
    <object
      classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,29,0"
      width="800px"
      height="600px">
      <param name="movie" value="helloworld.swf">
      <param name="quality" value="high">
      <param name="flashVars" value="key=API_KEY&sensor=true_or_false">
      <embed
        width="800px"
        height="600px"
        src="helloworld.swf"
        quality="high"
        flashVars="key=API_KEY&sensor=true_or_false"
        pluginspage="http://www.macromedia.com/go/getflashplayer"
        type="application/x-shockwave-flash">
      </embed>
    </object>
  </div>

Note that we add the API key and sensor parameters within a flashVars parameter, separated by an & character. This registration method is an alternative to compiling your key and sensor into the SWF file within the MXML declaration. If values are specified here, they override values contained within the SWF file or MXML declaration. Also note that the API key must match the domain where the SWF file is hosted, not the domain where the HTML file may be hosted.

Click here to see the resulting HTML page.

View Source (HelloWorld.mxml)

Congratulations! You've written your first Google Maps Flash application!

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.