Accessibility

Table of Contents

  1. Introduction
  2. An Overview of the API
  3. Putting It All Together

Introducing Yahoo! Maps JS-Flash API: Creating Web Applications Using Scriptable Flash Objects

An Overview of the API

The Yahoo! Maps JS-Flash API lets you create dynamic maps for websites and web applications. Scriptable SWF containers hold the map contents for you while you use JavaScript to make the maps come alive. In this tutorial, I'll introduce the basic features of the JS-Flash API and then create a simple, yet powerful, web application using the Overlay object.

Introduction to the API and Getting a Yahoo! Application ID

The API has a fair number of classes that you can use to create and manipulate your maps. Yahoo!'s online reference manual outlines them. You might want to bookmark the manual for quick reference: http://developer.yahoo.net/maps/flash/V2/flashReference.html.

To use the JS-Flash API in your applications, you need to obtain a Yahoo! Application ID. The IDs are free and you can get one here: http://api.search.yahoo.com/webservices/register_application.

Setting Up Your Web Page

All the JavaScript API classes and methods necessary to interact with Yahoo! Maps are available to your application when you include the apiloader.js file in your web page.

http://api.maps.yahoo.com/v2.0/fl/javascript/apiloader.js

When your JavaScript application includes this file, the generic SWF container to hold your map is made available to your application.

You'll need to create at least one div tag with an ID to hold your map. I'll call it mapContainer. By default, the map will expand to fit the size of the div container. You should provide a height and width for mapContainer or else the map may not size as expected. So, by specifying a height of 400 pixels and a width of 400 pixels, the maps will automatically be sized to those dimensions on the screen. Add the script tag, and you're ready to start making maps!

<html>
<head>

<script type="text/javascript" src="http://api.maps.yahoo.com/v2.0/fl/javascript/apiloader.js"></script>

<style type="text/css">
#mapContainer { 
    height: 400px; 
    width: 400px; 
} 
</style>

</head>
<body>

<div id="mapContainer"></div>
...

</body>
</html>

Creating A Map

To create and display a map, you create a Map object at a location and give it a zoom level. The Map object automatically brings in the SWF container, places the map inside, and displays it. You can use either latitude and longitude coordinates or a street address for the location. I'll use a street address, which also demonstrates the behind-the-scenes geocoding (translation from address to latitude/longitude) done by Flash. Add your Yahoo! application ID to the constructor (replace the dummy ID “YahooDemo” with your ID). This one line of JavaScript creates a map centered at 2000 S. Congress Avenue, in Austin, Texas, places the map inside the div tag that has an id set to “mapContainer”, and sets the zoom magnification at “3”:

var map = new Map("mapContainer", "YahooDemo", "2000 S. Congress Ave, Austin, TX", 3 );

If you don't set the zoom level (“3” in this case, but it can be any integer from 1 to 17), the map will default to a high-level view of the United States. I'll also make the map draggable by adding the panning tool to the map using the addTool method.

map.addTool( new PanTool(), true );

So, with just two lines of JavaScript, I've created and displayed a draggable map centered at an address.

<html>
<head>
<script type="text/javascript" src="http://api.maps.yahoo.com/v2.0/fl/javascript/apiloader.js?appid=YahooDemo"></script>

<style type="text/css">
#mapContainer { 
    height: 400px; 
    width: 400px; 
} 
</style> 

</head>
<body>

<div id="mapContainer"></div>

<script type="text/javascript">
    // Create and display Map object at the address and with zoom level 3 
  var map = new Map("mapContainer", "YahooDemo", "2000 S. Congress Ave, Austin, TX", 3);  
    // Make the map draggable 
  map.addTool( new PanTool(), true ); 
</script> 

</body>
</html>
The map displayed in Firefox

Figure 1. The map displayed in Firefox

Adding Markers To A Map

A marker is a labeled point on a map. You can use the CustomImageMarker, CustomPOIMarker, CustomSWFMarker, and WaypointMarker classes to create markers.

CustomPOIMarker creates a POI (Point Of Interest) marker, A POI marker is a special type of marker that expands when you click it to reveal more information about the location. WaypointMarker creates a waypoint marker, which is a simple marker that is automatically indexed when placed on the map -- you can use JavaScript to cycle through Waypoint markers like an array. If you're feeling more creative, you can define your own graphic images and then use CustomImageMarker to place the image on your map. If you're a Flash programmer, use CustomSWFMarker to create your own SWF markers.

Markers are added to the map and displayed using the Map.addMarkerByAddress() or Map.addMarkerByLatLon() methods. The two lines of code below add a single POI marker to our map. The marker is created, but not displayed, by the first line, and then displayed using the addMarkerByAddress() method.

marker1 = new CustomPOIMarker( 'MY HOME', 'Simple  Map  Example', 'South Austin, Texas Rocks!', '0xFF0000', '0xFFFFFF' );
map.addMarkerByAddress( marker1, "511 E. Mary St, Austin, TX");
A POI (Point Of Interest) Marker

Figure 2. A POI (Point Of Interest) Marker

By default, the marker responds to two mouse events. When a user rolls over the marker, the balloon will expand to display “Simple Map Example”. When a user clicks on the balloon, it will expand further to also display “South Austin, Texas Rocks!”. Note that those display strings, as well as the hex-encoded marker colors 0xFF0000 and 0xFFFFFF are all passed in the marker call.

Adding An Overlay To A Map

Overlays are sets of data points that are displayed on maps. You can quickly create very rich maps by using overlays. Currently, Yahoo! offers a number of powerful overlay classes: LocalSearchOverlay, TrafficOverlay, CustomSWFOverlay, and GeoRSSOverlay.

LocalSearchOverlay takes a text string as input and uses the Yahoo! Local Web Service to plot the location of nearby businesses based on the results of the search. TrafficOverlay uses Yahoo! Traffic Web Service to plot nearby real-time traffic incidents. CustomSWFOverlay lets Flash programmers create markers using Flash SWF files. GeoRSSOverlay plots the locations defined by a GeoRSS feed.

Here, I use LocalSearchOverlay to show all the Mexican food restaurants on the map. It also demonstrates the use of events. In this case, the event is EVENT_INITIALIZE. I use the addEventListener method to wait for the map to fully load and for the overlay to initialize. If the map is not fully loaded, the LocalSearchOverlay may fail or give unpredictable results.

After the map initializes, I create a new LocalSearchOverlay object, wait for it to initialize, and then use the search method to search for a text string. I use the addOverlay method to display the results on the map.

<script type="text/javascript">
      // Create and display Map object at the address and with zoom level 3 
    var map = new Map("mapContainer", "YahooDemo", "2000 S. Congress Ave, Austin, TX",     3);
      // Create global overlay variable
    var overlay = null;
      // Wait for the map to initialize and then call onInitialize     
    map.addEventListener(Map.EVENT_INITIALIZE, onInitialize);

      // Search for nearby Mexican food restaurants 
    function onOverlayInit( oEvent ) { 
      overlay.search('Mexican food', map.getCenter(), 1, 10); 
    }

    function onInitialize( oEvent ) { 
        // Make the map draggable 
      map.addTool( new PanTool(), true );
        // Create an overlay object
      overlay = new LocalSearchOverlay();           
        // Wait for the overlay object to initialize, then call onOverlayInit 
      overlay.addEventListener( Overlay.EVENT_INITIALIZE,   onOverlayInit, this ); 
        // Add the overlay to the map and display it
      map.addOverlay(overlay);
     } 
</script>
A LocalSearchOverlay search plotted on a map

Figure 3. A LocalSearchOverlay search plotted on a map

(+) View larger

Adding Navigation Tools

The JS-Flash API lets you add navigation widgets, or your own custom-designed map tools, to any map. The NavigatorWidget and CustomSWFTool classes let you add either a predefined navigation tool or your own SWF tools to the map. There is also a predefined tool dock, the ToolBarWidget class, that provides a convenient docking location for all the tools that you add to a map. To add the built-in navigation widget to a map, create a Navigator Widget object and then use the addWidget() method to add it to an existing map.

navWidget = new NavigatorWidget(); 
map.addWidget(navWidget);

The built-in navigation widget provides zoom and panning in one convenient control.

The built-in Navigation Widget

Figure 4. The built-in Navigation Widget

Note that in the Creating a Map section, I added the Panning Tool to the map. The Panning Tool simply makes the map draggable. It is not a visible widget.

Ptool = new PanTool();
map.addTool( Ptool, true );

Handling Events

Events occur when certain classes are initialized or when user-created actions, such as mouse clicks, occur. You use the addEventListener() method to monitor these events. For example, in the Adding an Overlay to a Map section, I waited for the map to initialize using this statement:

map.addEventListener(Map.EVENT_INITIALIZE, onInitialize, this);

The use of “this” defines the scope of the listening. In this case, I'm listening for events within this specific map.

There are other events, defined in the reference manual, that you can monitor, such as the success, or failure, of the LocalSearchOverlay() search method. These two lines of JavaScript will branch to the onSuccess function if the search succeeds, or the onFailure function if the search fails:

Overlay.addEventListener(LocalSearchOverlay.EVENT_SEARCH_SUCCESS, onSuccess, this);
Overlay.addEventListener(LocalSearchOverlay.EVENT_SEARCH_FAILURE, onFailure, this);
Page 2 of 3
Previous Page
Next Page