This article is written for an old version of the Virtual Earth platform. While still available for reference purposes, it is unlikely to work if implemented.
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 afficionados, of course, but their Windows brethren can read all about it here.
I thought it would be neat to have a Virtual Earth map control 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.
If you'd like to jump directly to the completed widget, you can visit my homepage and download it directly.
Unfamiliar with the basics of the Virtual Earth controls? Visit the articles page and brush up first.
The Dashboard environment.
Apple has a comprehensive section on their developer pages describing the Dashboard environment. But to summarise, the four basic components you need for a Widget are:
- A HTML file that defines the user interface for the widget
- A default background image in PNG format
- An icon image to represent the widget in the Widget Bar
- An XML formatted property list that contains various widget metadata
In our case we'll put all this into a directory called virtualearth.wdgt. Before we even get properly started, download VE_MapSearchControl.js & css and place them into this directory.
Designing out our Widget
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 bezeled 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 Virtual Earth MapSearchControl 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 organise for MapSearchControl to be displayed inside this widget.
Writing our HTML page
<html>
<head>
<link href="VirtualEarth.css" type="text/css" rel="stylesheet"/>
<link href="VE_MapSearchControl.css" type="text/css" rel="stylesheet"/>
<script type='text/javascript' src="VE_MapSearchControl.js"/>
<script type='text/javascript'>
function setup()
{
var map = null;
map = VE_MapSearchControl.Create(37.3189139456153,-122.029211560580,
12, 'r', "absolute", 0, 0, 530, 530,
"http://virtualearth.msn.com/search.ashx", "http://virtualearth.msn.com/Ads.ashx");
document.getElementById("contents").appendChild(map.element);
}
</script>
</head>
<body onload="setup();">
<div id="contents"></div>
<img src="Default.png"/>
</body>
</html>
Let's examine this rather simple HTML block in more detail.
The first thing we do is include our stylesheet. The contents of this stylesheet will be examined in more detail shortly. We then include the standard MapSearchControl stylesheet, followed by the associated JavaScript file supplied by Microsoft.
Next we have a small block of JavaScript that takes care of initialising our MapSearchControl. 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.
Another parameter you might tweak would be the 530 pair, which correspond to the dimensions of the control. For a more detailed overview of the MapSearchControl constructor arguments, consult the Building Your First Commercial Website using Virtual Earth article. Finally, we attach the map control itself to element id "contents", defined below.
We then have a body tag which calls the previously defined setup() method after the page has loaded. Inside body are two simple tags; our empty div with id "contents", and an image. The image tag is the same background image I designed earlier.
Writing the stylesheet
Our layout magic happens (as it should) inside the stylesheet.
body
{ margin: 0; }
#contents
{
top: 35px;
left: 35px;
width: 530px;
height: 530px;
position: absolute;
-apple-dashboard-region: dashboard-region(control rectangle);
}
Our contents div is carefully designed to have just the right amount of padding and dimensions so that the MapSearchControl 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 behaviour. 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 Virtual Earth, as you must click and drag to actually use the map.
Apple provides in-depth developer documentation for this feature. Our application is pretty simple - we just define the entire rectangular area of div "contents" to be excluded.
Writing the metadata
Info.plist is our property list that contains metadata relating to the Widget. Apple's documentation takes you through the entire list of valid keys and values for this file.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDisplayName</key>
<string>virtualearth</string>
<key>CFBundleIdentifier</key>
<string>com.apple.widget.virtualearth</string>
<key>CFBundleName</key>
<string>Virtual Earth</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>MainHTML</key>
<string>VirtualEarth.html</string>
<key>AllowNetworkAccess</key>
<true/>
</dict>
</plist>
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.
Deploying the 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 I can perform searches using the build in search controls. 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 Virtual Earth.
In summary
I hope you enjoyed this glimpse into Dashboard's internals. Of course, if such a rich Web 2.0 control such as Virtual Earth 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.
Don't forget to check out more Dashboard Widgets at Apple's download page.
Article contributed by Luke Burton. Have you got something to contribute?