Ever wanted to create one of those fancy map mashups, and build it exclusively using Flex 2/Actionscript 3?

If so, then check out the Flex 2 Yahoo Maps API.

It is easy to use and the cost is free!

A Flex Yahoo Maps API has been around for a few years now. The original API was written for Flex version 1.5, Actionscript 2 development. Fortunately, in early 2007 an F2/AS3 version was created. The new version allows a developer to use F2/AS3 to manipulate the API by using an AS3 wrapper that executes legacy AS2 code.

Let us look at an example on how this API works..

San Francisco Public Library Map Example

Click on the link below and take a look at our application.

My Library Map Application.

How was this application created?

1. We start off by taking info from the San Francisco Public Library
    website and creating an XML file..

     We create a record for each branch. An example appears below.
   

<branch name="Anza"> <contact address="550 37th Ave" zip="94121" phone="415-355-5717" cross="(near Anza)" link="http://sfpl.org/librarylocations/branches/anza.htm" /> <pictures building=http://sfpl.org/librarylocations/branches/images/anza.jpg map="http://sfpl.org/librarylocations/branches/images/anz.gif" /> <options wheelchair="no" wifi="yes" /> <languages english="yes" chineseCantonese="yes" spanish="yes" vietnamese="yes" /> <hoursopen> <sunday hours="1p-5p" /> <monday hours="10a-6p" /> <tuesday hours="10a-9p" /> <wednesday hours="10a-9p" /> <thursday hours="10a-6p" /> <friday hours="1p-6p" /> <saturday hours="10a-6p" /> </hoursopen> <notes comment="Extended hours during the Richmond Branch closure." /> </branch>

2. Using the above file, a filtered ArrayCollection is created by applying user entered criteria.. The selected branch
    records are then applied to the map using the "addCustomPOIMarker" method of the "MapController" class.

So far so good. Now let's dig into the details.

Getting the Yahoo Map API Up and Running

On the Yahoo API Developers website, there is a good description about working with the API and running the examples downloaded with it. Download the API and take a look at the examples.

We can learn a lot by playing around with the “howtoMapsASExAllFuntionality” Flex application found in the “map” folder. The nice thing about this application is that it includes an example of almost all of the mapping features you would want to use.

We will need a Yahoo Application ID to run the API. This is a special key that you get from Yahoo. It’s free and gives you access to their suite of API’s while at the same time allowing them to control usage. Register for a Yahoo Application ID.

Here are some important, but not so obvious points to remember.

• Set a path to the downloaded Actionscript 3 files before compiling our application. A detailed description can be found on the Yahoo API Developer Site mentioned earlier.
• Code in our Yahoo Application ID in the application before accessing the API.
• In our HTML wrapper, the object ID must match the Object reference in your application code. We will examine this in greater detail later in this article.

Taking a Look at the Code

As mentioned before, let's take a look at the “howtoMapsASExAllFuntionality” Flex application, especially the actionscript it performs. It is chock full of good examples on how to work the API.

The SF Library Map example includes a modified version of the same functions found in the “howtoMapsASExAllFuntionality” Flex application. We will find that being able to reference back to what actually worked will help us get past any problems that may occur running the application.

Our application will not work until a Yahoo Application ID is entered in the "actionscript/yahooMap.as" actionscript code and the resulting HTML wrapper is changed to reflect the Object ID.

The source code for this project can be viewed here.

Summary of Actionscript Code

• Import the Yahoo Map API Components.
• Set the Zoom Level . A value of "1" is the closest, "17" is the furthest out. Our example has the level set to"6".
• Enter a Yahoo Application Key ID.
• The "onMapLoaded" function loads up the all of the widgets and fun stuff needed for this application. The functions that were not needed were removed. But, if we want to use additional features, we should check out the "howtoMapsASExAllFuntionality" Flex application discussed earlier.
• The custom part of the application, the code that creates the markers, can be found in the "setMarkerByAddress" function.
  
  There are three steps involved.
  

  First of all, exiting markers are removed using the "removeAllMarkers" method of the "MapController" Class.
  Second, we loop through the ArrayCollection and add markers using the "addCustomPOIMarker" of the "MapController" Class.
  Third, we center the map and zoom in using the "setCenterByAddressAndZoom" of the "MapController" Class.

Summary of Flex Code

In our Flex Application, we import the above actionscript code, set the appropiate namespace for the API and layout the map component.

Also, we add a "loading" state that displays a progress bar while the map is loading.

• Set the application "onCreationComplete" event to execute the "onCreationComplete();" function found in the above Actionscript code.
• Set the Yahoo API Namespace to: xmlns:yahoo="com.yahoo.webapis.maps.*"
• Import the above actionscript code. Make the change to point to your own unique library path.

Here is the Flex code created for our application.

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="horizontal" creationComplete="init();onCreationComplete();" currentState="loading" xmlns:yahoo="com.yahoo.webapis.maps.*" paddingTop="5" paddingBottom="5" paddingLeft="5" paddingRight="5"> <mx:Script> <![CDATA[ include "actionscript/yahooMap.as"; ]]> </mx:Script>

Layout the Yahoo API Component within a Container (Panel, HBox, VBox, etc)

<yahoo:YahooMapService id="myAS2Map" UUID="{UNIQUEID}" swfDomId="{SWFDOMID}" apiId="{YAHOOAPIKEY}" mapURL = "{MAPSWF}" scaleContent="false" width="100%" height="100%" />

Include a "loading" state showing a progress bar while the initial map is loading.

<mx:states> <mx:State name="loading"> <mx:AddChild relativeTo="{mapPanel}" position="lastChild"> <mx:Spacer height="50" /> <mx:ProgressBar labelPlacement="bottom" id="progressBar" indeterminate="true" enabled="true" label="Please wait, loading map..." verticalCenter="0" horizontalCenter="0"/> </mx:AddChild> <mx:SetStyle name="horizontalAlign" value="center" /> <mx:SetStyle name="verticalAlign" value="middle" /> <mx:SetProperty target="{myAS2Map}" name="includeInLayout" value="false" /> </mx:State> </mx:states>

Additional Housecleaning Issues

The following files need to be present in our folder where your run the map application is run in order for it to work.

• as2map (SWF). This Flash file is included in the API download.
• The HTML wrapper created when flex application is compiled. We need to modify it to reflect the object name referenced to in our application. The default object name is the name of our MXML file, but we need to change the object name to the name specified in our actionscript. In our application, the object was named "SFlibraryMap". If we search the HTML below for these words, we will see the 3 places where changes need to be made. Without this change, our application will not work.

Here is the HTML wrapper created when we compile our Flex Application. It has been manually altered to reflect the object name "SFLibraryMap" matching the object reference in our actionscript code.

<!-- saved from url=(0014)about:internet --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title></title> <script src="AC_OETags.js" language="javascript"></script> <style> body { margin: 0px; overflow:hidden } </style> <script language="JavaScript" type="text/javascript"> <!-- // ----------------------------------------------------------------------------- // Globals // Major version of Flash required var requiredMajorVersion = 9; // Minor version of Flash required var requiredMinorVersion = 0; // Minor version of Flash required var requiredRevision = 0; // ----------------------------------------------------------------------------- // --> </script> </head> <script language="JavaScript" type="text/javascript" src="history.js"></script> <script language="JavaScript" type="text/javascript"> <!-- // Version check for the Flash Player that has the ability to start Player Product Install (6.0r65) var hasProductInstall = DetectFlashVer(6, 0, 65); // Version check based upon the values defined in globals var hasRequestedVersion = DetectFlashVer(requiredMajorVersion, requiredMinorVersion, requiredRevision); // Check to see if a player with Flash Product Install is available and the version does not meet the requirements for playback if ( hasProductInstall && !hasRequestedVersion ) { // MMdoctitle is the stored document.title value used by the installation process to close the window that started the process // This is necessary in order to close browser windows that are still utilizing the older version of the player after installation has completed // DO NOT MODIFY THE FOLLOWING FOUR LINES // Location visited after installation is complete if installation is required var MMPlayerType = (isIE == true) ? "ActiveX" : "PlugIn"; var MMredirectURL = window.location; document.title = document.title.slice(0, 47) + " - Flash Player Installation"; var MMdoctitle = document.title; AC_FL_RunContent( "src", "playerProductInstall", "FlashVars", "MMredirectURL="+MMredirectURL+'&MMplayerType='+MMPlayerType+'&MMdoctitle='+MMdoctitle+"", "width", "100%", "height", "100%", "align", "middle", "id", "SFlibraryMap", "quality", "high", "bgcolor", "#869ca7", "name", "main", "allowScriptAccess","sameDomain", "type", "application/x-shockwave-flash", "pluginspage", "http://www.adobe.com/go/getflashplayer" ); } else if (hasRequestedVersion) { // if we've detected an acceptable version // embed the Flash Content SWF when all tests are passed AC_FL_RunContent( "src", "main", "width", "100%", "height", "100%", "align", "middle", "id", "SFlibraryMap", "quality", "high", "bgcolor", "#869ca7", "name", "main", "flashvars",'historyUrl=history.htm%3F&lconid=' + lc_id + '', "allowScriptAccess","sameDomain", "type", "application/x-shockwave-flash", "pluginspage", "http://www.adobe.com/go/getflashplayer" ); } else { // flash is too old or we can't detect the plugin var alternateContent = 'Alternate HTML content should be placed here. ' + 'This content requires the Adobe Flash Player. ' + '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>'; document.write(alternateContent); // insert non-flash content } // --> </script> <noscript> <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="SFlibraryMap" width="100%" height="100%" codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab"> <param name="movie" value="main.swf" /> <param name="quality" value="high" /> <param name="bgcolor" value="#869ca7" /> <param name="allowScriptAccess" value="sameDomain" /> <embed src="main.swf" quality="high" bgcolor="#869ca7" width="100%" height="100%" name="main" align="middle" play="true" loop="false" allowScriptAccess="sameDomain" type="application/x-shockwave-flash" pluginspage="http://www.adobe.com/go/getflashplayer"> </embed> </object> </noscript> <iframe name="_history" src="history.htm" frameborder="0" scrolling="no" width="22" height="0"></iframe>

In Conclusion

As recently as the middle of August 2007, it was a little frustrating running the examples that came with the API.

That has changed since a new team at Yahoo took over the project.

If we want to dig deeper into the API, we can check out the helpful dictionary of Classes that is included with the download.

Hopefully, there are enough tips in this article to help us build bigger and better map applications using the Yahoo Map API.

Happy Mapping!

Come see us in person!

If you are in (or have plans to be in) San Francisco on Tuesday, September 25th, 20007, we invite you to come see us at the Bay Area Application Developer Adobe User Group. I will be presenting a session on this Yahoo Maps application. Satori Canton will be there presenting on his upcomming article about how to create near-perfect code through unit testing with FlexUnit. And Mark Altenbernd will be giving a presentation on the use of validators in Flex. We welcome you to come out and join the discussion!