MapQuest Developer Blog

Archives for John Fronckowiak

  • Map It! - Building a MapQuest Mac OS X Dashboard Widget - Part 2

    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:

  • Map It! - Building a MapQuest Mac OS X Dashboard Widget - Part 1

    A civilized nation can have no enemies, and one cannot draw a line across a map, a line that doesn't even exist in nature and say that the ugly enemy lives on the one side, and good friends live on the other. - Thor Heyerdahl

    The MapQuest Platform has become the preferred way for developers to integrate rich cartography into their applications. Using the MapQuest Platform, developers can provide street and satellite views. In addition points of interest, navigation, geocoding (converting an address to map coordinates), and routing are all supported. In this series of blogs - I will show developers how to build a Mac OS X Dashboard widget that will eventually provide mapping, point-to-point directions, and integration with the built-in Address book application - all powered by the MapQuest Platform.

    Development Platforms

    The MapQuest Platform APIs are accessible from a wide variety of development platforms and protocols. From the server side this includes: Java, .NET, and C++. From the client side this includes: AS3 (Adobe ActionScript 3), FUJAX, and JavaScript.

    Signing Up

    The MapQuest Developer Network is the place to get started. The site provides an overview of the APIs features, in addition to links providing an online demo, product brochures and more. Before a developer can begin using the APIs in their applications they need to sign up for a Free Edition or Developer license. As shown in Figure 1, you can start that process at - http://developer.mapquest.com/Home/WhyJoin - click on the Register button in the upper right.

    Figure 1

    You'll need to provide basic personal information, and accept the terms and conditions.

    Shortly after you submit your information, you'll receive an email, you'll need to click on the link in the email to confirm your request. Once confirmed, you'll receive a second email in about 20 minutes. This email will contain the URL to the MapQuest Technical Resource Center, your username (which is the email address you used to sign up) and a temporary password, which you will change after your first login. Also included in the message is the authentication information you'll need to access the MapQuest Platform from your application. I'll be using this information later in this series of blogs.

    After you login to the Technical Resource Center and change your password, as shown in Figure 2, you'll have complete access to the documentation, SDK downloads, examples, and your account information. Click on the My Account link to view the information shown in Figure 3.

    Figure 2

    Figure 3

    In addition to your support form user id, you will be able to configure the referrers for your account. The referrer information basically provides information about the domains where you will be accessing the MapQuest Platform. Note at the bottom that there is an option to permit blank referrers. Read the warning note closely if you enable this option. I will discuss the specific referrer issues that occur with a Mac OS X Dashboard widget in the next post in these series.

    Conclusion

    You now know how to get started with the MapQuest APIs. Here are some resources for you to review before I begin to build the Dashboard widget. Dig in!