Integrating Bing Maps into the OS X Dashboard

Caution

The content in this article may still be applicable to the current version of the Bing Maps AJAX Control 6.3, but it uses a previous version of the Bing Maps AJAX Control 6.3 which is no longer supported. More information about the current version of the Bing Maps AJAX Control 6.3 is found in the Bing Map Control SDK.

Apple's flagship operating system is OS X Tiger, and it contains a nifty feature known as the Dashboard. This is old news to Mac aficionados, of course, but their Windows brethren can read all about it here.

I thought it would be neat to have a Bing Maps AJAX Control 6.3 accessible through the Dashboard, so I went ahead and implemented my own Dashboard Widget for the task. I had never written anything for the Dashboard before, and so was pleasantly surprised to see how easy it was to write one. This tutorial will take you through my Widget, step by step. You can also download the complete widget here.

I admit to being very much less than a genius when it comes to Photoshop. However, I can still knock up something that would make a graphic designer sigh painfully (as opposed to burst with gales of laugher). I thought maybe a beveled stone sort of look would be a suitably flagrant violation of Apple's user interface guidelines. This is named Default.png.

It's worth noting that the minimum dimensions of the Bing Maps AJAX Control 6.3 forced me to produce a widget this large; I would have preferred something slightly smaller.

I also pilfered the ViaVirtualEarth logo and turned it into a transparent png. This file is named Icon.png.

So now we just need to organize for our Map Control to be displayed inside this widget. We start with a basic HTML page:

The first thing we do is include our reference to the Bing Maps AJAX Control 6.3 API. The single script reference automatically includes all of the necessary controls and styles to display a map.

Next we have a small block of JavaScript that takes care of initializing our Map control. The most notable parameters are the two first floating point arguments, which specify the latitude and longitude for this map's starting coordinates. I chose Cupertino, just to be cute. The next parameter is the zoom level (1 - world, 19 - street). The character parameter is the map style ('r' - road, 'h' - hybrid, 'a'- aerial, 'o' - Oblique/Birds Eye). The last parameter indicates whether we want to lock the map. Note that our map is automatically attached to the "contents" div tag in the body of the HTML page, and will take on the size of that tag. The next part of the load method attaches our what/where search box to the map and positions it. The last part of the script block defines our search method.

In the body of the HTML, we start with a call to the previously defined setup() method after the page has loaded. The first tag inside the body is the "contents" div that will contain the map. We will size this map through CSS. The second tag is an image tag that is the same background image I designed earlier. The third tag defines our what/where search block. We can't use the default what/where find control because it is too big for our purposes.

Our contents div is carefully designed to have just the right amount of padding and dimensions so that the map lies squarely inside the frame. The way we achieve this is through standard CSS layout techniques.

Apple has provided some special stylesheet extensions that handle Dashboard specific behavior. One of these is the "-apple-dashboard-region" statement. Normally, one can grab a Widget anywhere and drag it around the Dashboard. We can use dashboard-region to stop certain areas of the Widget from being drag handles. This is pretty important for Bing Maps, as you must click and drag to actually use the map.

CFBundleDisplayName must match the name of the Widget directory on disk, minus its extension. CFBundleIdentifier is a string that uniquely identifies the widget, a la Java'package naming system. MainHTML points to the main HTML file of this widget. And AllowNetworkAccess very importantly grants our Widget access to make network calls. This is important for any AJAX application embedded in a Widget.

With all these pieces in place, all that remains is to actually install the Widget. This is accomplished by a simple double click on the Widget directory from the Finder. You will be prompted to confirm that you'd like to install this Widget, which then takes you to the Dashboard. You're prompted again to confirm you want this Widget, after which you should finally have it.

Well, give it a try! It should look something like this:

Notice that if you have a Mighty Mouse, or other scroll mouse, you can zoom in and out using the scroll wheel. And of course you can pan around the map, switch to Aerial or Hybrid, and generally do everything you normally can using Bing Maps.

I hope you enjoyed this glimpse into Dashboard's internals. Of course, if such a rich Web 2.0 control such as Bing Maps can live happily inside the Dashboard, you should be pretty excited about the possibilities! Don't forget Dashboard Widgets can closely integrate with Apple specific applications via plugins as documented here. The sky is the limit, and the cleanliness and elegance of the Dashboard as an AJAX programming environment will make it all too easy for you.