Yahoo! Maps Web Services - ActionScript®-Flash® API Getting Started Guide

Introduction and Prerequisites

The CustomSWFOverlay feature in the Yahoo! Maps API gives you the ability to display all sorts of graphics and data over the map. Similar to CustomSWFMarker, the overlay spans the whole map and can display anything from land parcel data to a custom polyline overlay. In this tutorial we will be creating a user-drawn polyline overlay using the built in Flash drawing tools.

To create and test applications using the Yahoo! Maps AS-Flash API, you'll need Macromedia® Flash MX 2004® or higher and a browser with Flash Player 7 or higher. You will also need to download the Yahoo! Maps MXP (Macromedia® eXtensions Package) file that will install the appropriate classes onto your machine. An application ID is required to use the AS-Flash API. You can get an application ID here.

For best results, you should launch your web pages from a web server. However, it's possible to run applications directly from your hard drive by double-clicking on them. If you run them from your hard drive, you may see a warning from the Flash Player that your application is trying to access data from a third-party server (Yahoo!). You can remove this warning by adjusting your Flash Player settings.

Displaying a Yahoo! Map using ActionScript and Flash

Once you have agreed to the terms and downloaded the Yahoo! Maps MXP file, double click on it to launch the Macromedia Extension Manager and automatically install the extension. Please make sure that you have the latest version of the Extension Manager installed. You will need to restart the Flash IDE if you have it open in order for the classes to be available. After the extension is loaded, open the Components panel and expand the Yahoo tree where you should now see com.yahoo.maps.api.flash.YahooMap. To use the component, drag com.yahoo.maps.api.flash.YahooMap from the Components panel onto the stage. Resize the component with the Transform tool or Property inspector and test your movie to see the map. To interact with the map you will need to give the component an instance name. For the examples below, myMap is the instance name.

When adding the Map component to the stage, you should specify what the map will display by default as well as enter your Yahoo! application ID. With the component selected, click on the Parameters tab in the Properties inspector. Here you can specify the starting location, default zoom level, and Yahoo! application ID for your map. The starting location can either be an address, taking advantage of our built-in geocoding, or a latitude and longitude. The zoom level can be any integer from 1 to 17. If no zoom level is specified, the map will default to a zoom level of 14 over the specified location. If no location is specified, the map will default to the center of the United States at the specified zoom level.

Creating the Overlay SWF

With a working map, our next step will be to create the overlay. This will be a seperate SWF file that the map will load as a CustomSWFOverlay. It will also be solely based on ActionScript.

Open a new flash document, you may leave the default stage size as is.
Create a new layer, entitled ‘actions’ and add this code to its 1st frame.

We will be drawing the overlay in a new movie clip entited 'boundRect', so our first step here will be to create it. We will also initialize a new pen inside that function.

var boundsRect:MovieClip;

function createNewPen() {
	this.boundsRect = this.createEmptyMovieClip("boundsRect", getNextHighestDepth() );
	this.boundsRect.lineStyle(8, 0x0000CC, 50);
	this.boundsRect.moveTo( 0,0 );
}

Next, we will need a function that will be called from the map to draw a new line. This will draw based on the position of the mouse on the SWF.

function draw() {
	this.boundsRect.lineTo(_xmouse, _ymouse);
}

This is all the necessary code for the overlay. Next we will go back to the map to add the overlay and track user clicks on the map.

Back to the Map: Adding the Overlay

The first step in creating the map will be to import the necessary classes and also creating two event listeners. These two will listen for the EVENT_INITIALIZE event when the map is created, and also the EVENT_CUSTOM_OVERLAY_LOADED event, fired when the overlay is successfully added to the map.
```
import com.yahoo.maps.tools.PanTool;
import com.yahoo.maps.overlays.CustomSWFOverlay;

myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_INITIALIZE, onInitMap);
myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_CUSTOM_OVERLAY_LOADED, onOverLoad);
```
Next, we will need to create two new variables.
```
var overlay:Object;
var polyOverlay:CustomSWFOverlay;
```
The variable 'overlay' will store the event data passed from the EVENT_CUSTOM_OVERLAY_LOADED event, and 'polyOverlay' will be the reference to the overlay itself.

Next, create the 'onInitMap' function that will be fired from the EVENT_INITIALIZE event listener.

function onInitMap(eventData) {
	myMap.addTool(new PanTool(), true);
	polyOverlay = new CustomSWFOverlay("overlay.swf");
	myMap.addOverlay(polyOverlay);
}

At this point, if you compile the map, the overlay has been added, though not visible yet. Now, we will create the 'onOverLoad' function so that we can manage the overlay. When this function is fired, we will be using an event that is new to API 3.04. EVENT_ONCLICK is fired everytime the user clicks on the map (single clicks and double clicks).
Also, we will be using the data passed from the event to reference the overlay, and call functions inside it.

function onOverLoad(eventData) {
	overlay = eventData.overlay;
	overlay.createNewPen();
	myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_ONCLICK, onMapClick);
}

Note that we have attached the funtion onMapClick to the event listener, to be called everytime the event fires. Next, we will add this function. When the EVENT_ONCLICK event is fired, it contains an action string within the object that defines the type of click that occured. You may check this and filter out either type of click action if necessary.

function onMapClick(eventData) {
	if( eventData.action == "doubleClick")
		overlay.draw();
}

Save your file, and test the movie.

CustomSWFOverlay has much more power than what is shown here. Using more of the features available in the Flash API you have the ability to create rich, dynamic map applications.

The finished code:

Map

import com.yahoo.maps.tools.PanTool;
import com.yahoo.maps.overlays.CustomSWFOverlay;

var overlay:Object;
var polyOverlay:CustomSWFOverlay;


myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_INITIALIZE, onInitMap);
myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_CUSTOM_OVERLAY_LOADED, onOverLoad);


function onInitMap(eventData) {
	myMap.addTool(new PanTool(), true);
	polyOverlay = new CustomSWFOverlay("overlay.swf");
	myMap.addOverlay(polyOverlay);
}

function onOverLoad(eventData) {
	_isEnabled = true;
	overlay = eventData.overlay;
	overlay.createNewPen();
	myMap.addEventListener(com.yahoo.maps.api.flash.YahooMap.EVENT_ONCLICK, onMapClick);
}

function onMapClick(eventData) {
	if( eventData.action == "doubleClick")
		overlay.draw();
}

Overlay:

var boundsRect:MovieClip;

function createNewPen() {
	this.boundsRect = this.createEmptyMovieClip("boundsRect", getNextHighestDepth() );
	this.boundsRect.lineStyle(8, 0x0000CC, 50);
	this.boundsRect.moveTo( 0,0 );
}
function draw() {
	this.boundsRect.lineTo(_xmouse, _ymouse);
}

Yahoo! Maps Web Services - ActionScript®-Flash® API Getting Started Guide

Version 3.5 - Beta Yahoo! Maps AS-Flash API - CustomSWFOverlay Tutorial

Introduction and Prerequisites

Displaying a Yahoo! Map using ActionScript and Flash

Creating the Overlay SWF

Back to the Map: Adding the Overlay