Getting Started With Flex Based Yahoo! Maps

To use the Yahoo! Maps AS3 Component you'll need your own Yahoo! Developer Network Application ID. If you have one already, then you're all set. If not, click on the "Get an App ID" link on the component page to obtain one.

Once you have an App ID, you'll need to download the Flex component itself. There is a download link in the middle of the component page, download the ZIP file, and expand it in a local folder somewhere. There are lots of files in the ZIP file, but the really important file is the YahooMap.swc file. Make sure you know the path to this file, you'll need it when you create your Flex project.

Then create a new Project in Flex Builder. You can define a Server Technology if needed, although for tinkering the first time you may want to keep the Project as simple as possible. In the 3rd screen in the New Flex Project wizard you can specify Source Paths and Library Paths. Select the "Library path" tab as you'll need to add the YahooMap.swc. Click the "Add SWC" button, and then browse to the YahooMap.swc file and click "OK". You should see the YahooMap.swc listed in the "Build path libraries" list. You can then finish creating the Project.

Now let's create the basic UI. This example will display the map in a large box on the right, and the left will contain simple text boxes, one to enter the map location, and the other to specify map searches. Here's the MXML code:

The code is pretty simple, and the only really interesting item is the <mx:UIComponent> which will be used to display the map. Paste this code into your app, and compile and run it, just to make sure all is working.

Next we'll add basic mapping. Here is the updated code:

Let's take a look at the above code. The big change is the <mx:Script> block. First come a series of import statements, and then two variables are defined. The first, appID, contains your Yahoo! Developer Network ID, replace the placeholder text in quotes with your own ID. The second defines the YahooMap itself.

The initApp() function (called on creationComplete) first creates a new YahooMap instance, and then defines the handler that will be called upon map initialization. It then initializes the map, passing the appID, along with the desired height and width (using the height and width of the mapUI UIComponent). Next a series of options are set, turning on panning, the scale bar, the map type widget, and the zoom control (you can omit these, or add other options if desired). And then finally, addChild() is used to add the yahooMap object to the mapUI UIComponent.

The code also contains two other functions. yahooMapInitialize() is called once the map is initialized (in response to a YahooMapEvent.MAP_INITIALIZE event). It sets the default zoom level and initial map location, and also specifies a resize handler. This is important, without a resize handler the displayed map would not resize if the app were resized. The resize handler function itself, yahooMapResize(), is called whenever the app is resized (in response to a ResizeEvent.RESIZE event), and it simply resets the map size (again using the height and width of the mapUI UIComponent).

You can paste this code into your app, and run it. You'll have a fully functioning map, allowing zooming and panning, and supporting multiple display types (Map, Satellite, and Hybrid).

Next we'll add code to allow users to enter a map location. Here's the updated code:

Not a lot of changes here. First, we've added some more needed import statements. We've also added a variable of type Address (to store the set map location). Two functions have been added to the code. setMapLocation() accepts a string (whatever the user typed in the txtLocation box) and then creates an Address object for the passed string. As you are probably noticing, the Yahoo! Maps component is used asynchronously and is thus highly event driven. setMapLocation() sets an event handler that will be called when the Address object has been successfully geocoded, and then it perform the geocode. The geocode operation does not do anything to the map, rather it locates matches and converts them into map locations. The event handler, yahooGeocodeSuccess(), first obtains any results generated by the geocode operation. It is possible for a geocode operation to return multiple results, but this code ignores all but the first match, and then uses that first match to set the map zoom level and location. And finally, setMapLocation() was added to the first <mx:TextInput> and <mx:Button> to the enter and click events respectively.

Save these changes, and then run the app. Now you can type in a country name, or a city and state, or a US zipcode, and the map will be repositioned to display the best match.

Now for the final change, this time allowing you to search for matches within the displayed map. Here's the code one last time:

Once again, more import statements have been added. We've also added a variable of type LocalSearch to perform local searches (searches within the displayed map). The second <mx:TextInput> and <mx:Button> controls now invoke a function named mapSearch(). This function first removes any map markers (left from a previous search, there will obviously be none the first time this function is invoked), and then performs a local search specifying the search text, map zoom level and location, and search radius (in miles). This search is also asynchronous, and the yahooSearchSuccess() function is invoked when the search completes. (This event handler is added in the initApp() function above). yahooSearchSuccess() obtains the results and then loops through them, creating a LocalSearchItem for each and then using that to create a SearchMarker, and then adding that marker to the map.

Save this code, and then run the app. Type in a location, and then do a search for "ATM" or "pizza" or anything else. You can try setting the map location to "San Jose, CA" and then find "Adobe Systems, Inc.".

Pretty cool, and not a lot of code either. And that's just the start of it. Yahoo! has posted lots of great examples, so check those out. And the component also supports distance, traffic data, and much more, so be sure to browse the API documentation. And once you have the basics down, adding integration to backend data (perhaps pulling addresses from a backend ColdFusion app to map them) is just as easy.

Have fun with this, and if you create anything cool and public facing, please share the URL.