That is the exploration that awaits you! Not mapping stars and studying nebula, but charting the unknown possibilities of existence. - Leonard Nimoy
In Part 1, I provided an overview of the MapQuest Platform, and provided instructions on how to obtain your own developer key. The developer key is required to integrate MapQuest into your application through the JavaScript API.
About Map It!
In Part 2 and 3 of building the Map It! Application, I will be creating the Mac OS X Dashboard widget shown in Figure 1.
Figure 1
Users enter an address in the search box at the top of the widget, and that point is automatically plotted and zoomed in on the map below. Users can switch between map, satellite, and hybrid views. They can also use the controls on the left to navigate and move around the map.
I've discussed building Mac OS X Dashboard widgets previously on my AOL Developer Network blog, here and here. For the Map It! Dashboard widget - I used Apple's Dashcode to jumpstart my development. Even though I used Dashcode - the techniques to integrate the MapQuest Platform, I'll review here can be utilized however you develop Dashboard Widgets.
It's important to understand that Dashboard Widgets are mini Web 2.0 applications - with their programmatic interface coming from JavaScript - so the JavaScript API is almost (I explain why it's almost in Part 3) perfect fit! All of the techniques I review in building Map It! can be used by Web 2.0 developers as well!
Adding the MapQuest JavaScript Library
In the main widget HTML page you'll need to include the following SCRIPT tag to import the JavaScript library:
<script src="http://btilelog.access.mapquest.com/tilelog/transaction?transaction=script&key=**YOUR-KEY**ipr=true&itk=true&v=5.2.0" type="text/javascript"></script>
You need to replace **YOUR-KEY** with the key that was provided in the email when you signed up for the MapQuest Platform, as discussed in Part 1.
Creating the User Interface
To place the map on the widget - you'll need to create a DIV to hold the map. In the Map It! application I created the following DIV tag.
<div id="myMap" style="width: 550px; height: 300px;"></div>
Now that you have a place to display the map, the next step is to get the map displayed in the DIV. This is simply done by create a new MQTileMap object and associating with the DIV, as shown here:
// Create a MQTileMap object and display it in the myMap DIV
myMap = new MQTileMap(document.getElementById('myMap'));
The final step is to add the Large Zoom and view controls. These controls allow the user to zoom in and out of the map, and select the type of map that is displayed (road, satellite, or hybrid). This is accomplished with the following code:
// create a new Large Zoom Control
var myLZControl = new MQLargeZoomControl(myMap);
// add it to the map at the specified offset from the Top Left corner
myMap.addControl(myLZControl, new MQMapCornerPlacement(MQMapCorner.TOP_LEFT, new MQSize(1,1)));
// create a new View Control
var myVControl = new MQViewControl(myMap);
// add it to the map at the specified offset from the Top Right corner
myMap.addControl(myVControl, new MQMapCornerPlacement(MQMapCorner.TOP_RIGHT, new MQSize(20,20)));
That's all that you need to add a map!
Referrers
While Dashboard widgets function just like typical Web 2.0 applications, they have two shortcomings that need to be overcome when working with the MapQuest Platform. First, when including the JavaScript library, your key maps back to the information provided when you signed up for developer access. Since Dashboard widgets run locally from your desktop they will not have a referrer. As shown in Figure 2, you'll need to add the referrer * and enable blank referrers. It's important to understand the risks of enabling blank referrers so read the Warning not carefully. Since we're not running the Dashboard widget from a web server - as all widgets are accessed locally - blank referrers are required. I'll discuss the second shortcoming with Geocoding and Mac OS X Dashboard widgets in the Part 3.
Figure 2
Conclusion
In Part 3 I'll show you how to add Geocoding to the widget to plot a point of interest based on the address entered in the search box. For your reference, here are some references to the MapQuest Platform:
