Well, its been a couple of days since we had a tutorial come out of the doors here, which we apologize for, but hopefully as a big project we are working on finishes up the tutorials will start pouring out again. This tutorial is going to go over how to use the brand new Yahoo Maps API. The API is very easy to use and should be a lot of fun to make applications to mash up different services. Yahoo provides a bunch of examples for using the maps here.

The application we are going to build here is going to be a very simple local search example. Ok, play around with it below. It is initialized to search New York for "italian". The application is built using just a couple flex components. You can view the source here.

Grabbing the Component

The first item of business is going and getting the Yahoo Map component and installing the swc file. This is fairly easy to do. You can get the component from Yahoo here. Once you have downloaded the component, you need to get a application api key. You can get this here, fill out the information and you will get your api key. This will be used to create the map component. To install the swc file following the below directions, which are taken from the Yahoo Map page.

1. Find your project in the Flex Navigator.
2. Right-click on the project and choose Properties or open the Project menu and choose Properties.
3. In the project properties dialog, choose Flex Build Path.
4. Select the Library path tab, and press the Add SWC... button.
5. Enter the location of the component SWC. It should be in
   [download location]/Build/YahooMap.swc.
6. Press OK in the Add SWC dialog.
7. Press OK to close the project properties.
8. The YahooMap component is now available in your project.

Basic Interface

Once we have our component added to our application we can get started building the example. The example has a very simple interface that we are going to build. It has the basic application with a couple parameters. The major changes to the application are the layout which we change to vertical and got rid of all the padding. Inside the application we have two big containers - one is a HBox and one is an UIComponent.

The HBox will hold the simple set of controls for local search. We have a label, text input, and button in the box for inputting the search terms and searching. The second UIComponent is actually for adding the Yahoo Map component. This may sound a little bit different than normal, but we need a component that can hold a Sprite as a child (YahooMap component extends Sprite). This means Container components are out. Yahoo probably went this route to keep the component as small as possible.

Adding Yahoo Map Component

Next we will add the map component to our application. To do this we are going to add a little bit of Script to our application. We start with adding an event to our Application for creation complete. This event will call initApp which initializes the Yahoo Map component. The following code shows our new Application tag.


Now we add a Script tag for the all the Actionscript code. We first add a private variable that is a YahooMap called ymap. Inside our script tag we add a function for initApp. Our function starts off by setting ymap equal to a new YahooMap. The constructor for the Yahoo Map takes four items: application id (what we registered for earlier), width, height, and optional local (defaults to "en"). Once we have created the map we do a couple items. First we add an event listener to listen for when the map has been initialized; this will call the function initializeMap. We tell the map to include a couple pieces which include the zoom buttons, types ("Map", "Satellite", and "Hybrid"), and panning - click and drag. The last thing to do is add the map to our map container (the UIComponent we added earlier). We can see this code below.


To finish up the initialization of the Map we need to add the initializeMap function to our script. We put this right below initApp. During this function we do two thing initially, set the initial zoom and the initial location. For the zoom I set it to 3, which is a city close up, and also set a center point to the latitude and longitude of New York city. You can examine this code below.


That is all that is takes to get a map to show up. Pretty simple ehh?

Adding Local Search

To make this example even better we are going to show how to build in very simple local search functionality. The first thing we are going to do is add two events to our interface. The first event we are going to add is for the TextInput - to which we are going to add a keydown event listener. For our Button component we will add a click event listener. Code for the text input and button follows.


Next we add a function for the button click to actually do the local search. First we need to add another private variable of type LocalSearch. So we add a function to our script which will use the Yahoo API to do a local search. This function, named doLocalSearch, will first create a new LocalSearch, then add an event listener for when the search completes, and finally do the actual search. This code is below.


Now we need to handle the results that we get back from Yahoo. This is done in the function, named handleSearchResults, spelled out below. We first remove all the Markers on the map; next we grab the results from the event and put this info into an array. Lastly we loop through these results and add each one to the markers map individually.


And this gives us a working search. To make this slightly more complete we are going to do two things. First we add a quick function call to our initializeMap function which initializes the map to have some markers on it. Finally we add the function for the keyDown event for our text input. This function checks to see if the key pressed was the "Enter" key and if so then simply calls the local search function. Both pieces of code are below.