Published on MacDevCenter (
 See this if you're having trouble printing code examples

Build a Dashboard Widget

by Andrew Anderson

According to Apple, Tiger adds over 200 new features to Mac OS X. While some of these features are simple upgrades or underlying fixes that are nearly invisible to users, one feature that users and developers alike have been looking forward to for months is Dashboard.

Dashboard is a new environment that allows users to run mini-applications called widgets. These widgets, while able to use all of the advanced features of Tiger, are simple to use and simple to develop. This is the first in a series of two articles that gives an introduction to developing Dashboard widgets. This article will focus on the basics of widget development and then go over the steps required to develop a widget that displays *nix man pages.

Dashboard Overview

Dashboard widgets are a lot like web pages. They use HTML markup for user interfaces and JavaScript for programming tasks, and are written and saved as text files. On the face of it, this makes Dashboard sound like a glorified web browser, but two things make Dashboard much more than a web browser. First are the additions to JavaScript that support interaction with many of the underlying features of Tiger, and second is the ability to isolate widgets from each other and display them in a visually appealing and consistent manner.

Dashboard's hooks into OS X allowing developers to:

Add in the features and ease of coding with JavaScript, and you have an environment that gives developers all of the tools they need to develop powerful, interesting applications. The widgets that Apple includes with Tiger show off many of the types of things that developers can do, including controlling Address Book and iTunes, downloading weather information from a remote server, and converting values between units. Apple's widgets, and the widgets in the this and the next article, only touch the surface of the types of applications a clever developer can create.

Since widgets are really just web pages, presenting them to the user can be something of a challenge. Web pages in Safari are defaulted to have white backgrounds, are usually 800 by 600 pixels and use a huge amount of screen space for toolbars. If widgets were displayed in browsers, then on an 12" iBook, one or two widgets would take up the whole screen. These two widgets could also interfere with each other and either of them could cause the browser to crash.

Apple's Dashboard environment strips the toolbars, default size, and background color from the browser and puts each widget in its own sandbox so they cannot interfere with each other. This allows widgets to run on their own and also look like individual applications to users.

Anatomy of a Widget

Dashboard widgets are stored in one of two places: user widgets are stored in ~/Library/Widgets, while system widgets are stored in /Library/Widgets. Widgets are stored in widget packages, which are just directories with a .wdgt extension. Each widget package has to have at least three files:

Info.plist contains all of the information that Dashboard needs to run a widget. This information includes mappings for the default HTML page and default background image, information on the developer of the widget, and information on what the widget is allowed to do. The Info.plist file that we will use for the ManPage widget looks like this:

<?xml version="1.0" encoding="UTF-8"?>
  "-//Apple Computer//DTD PLIST 1.0//EN"
<plist version="1.0">
	<string>Man Page</string>

Related Reading

Learning Unix for Mac OS X Tiger
By Dave Taylor

These properties are used to set the following for each widget:

The MainHTML, Width, Height, CFBundleName, CFBundleIdentifier, and DefaultImage properties are required. Info.plist can be edited in Apple's Property List Editor or with any text editor.

The Default Image

As I said in the "DefaultImage" section of the Info.plist overview, widgets need to have a default background image. This image is displayed while Dashboard loads a widget. For a simple widget, the easiest thing to do is to have this image be the same as the background image that you will have for the widget once it is loaded. Apple's documentation specifies that this image needs to be a PNG file. PNG files can be created with Photoshop, Fireworks, GIMP, or just about any other image-editing software.

To keep things simple, I have named the file for the ManPage project Default.png. Here is what it looks like:


While this file can be as complex or as simple as a developer would like, it is important to remember that the main purpose of this file is to display an image while the widget is loading. This allows the user to see information about the widget, the default footprint of the widget, and other visual information that the developer wants the user to see. To keep things simple for the ManPage widget, this image is the same as the as background for the widget.

The MainHTML File

MainHTML is the file that provides the basic user interface and JavaScript functions for the widget. While complex widgets could include multiple HTML, CSS and .js files, for simplicity's sake, the ManPage widget consolidates all of this into one file.

While MainHTML files are basically HTML files, similar to those for regular web pages, there are some things to keep in mind while developing them. First and foremost, there is no default background for a widget. In order for the widget to have a canvas to draw on, you need to specify a background image. (I am not sure if invisible widgets would work, but it would be cool to try out.) This can be done using a div tag, like in the ManPage HTML section below.

The second thing to keep in mind is that Dashboard conforms to CSS, JavaScript, and DOM web standards. While this article is not intended to be an overview of developing CSS-based HTML pages, I will say that since Dashboard is basically a conforming browser, it is much easier to develop and debug widgets using web standards.

The MainHTML for the ManPage widget is below:

<title>Dashboard Man Page</title>
<meta http-equiv="Content-Type"
      content="text/html;charset=utf-8" >

<style type="text/css">
.backStyle {
        visibility: visible;

.textStyle {
        font-family: Lucida Grande, Arial, Helvetica, sans-serif;
        font-size: 12px;
        color: #000000;
        left: 128px;
        top: 26px;

        left: 246px;
        top: 24px;
        visibility: visible;

        left: 33px;
        top: 72px;
        visibility: visible;

<script type='text/javascript'>
// get man page
function getManPage()
  if (document.getElementById('programName').value != null)
 var commandLine =
  'groff -mandoc -Tascii -P-b -P-c `/usr/bin/man -w "'
  + document.getElementById('programName').value+'"`'
  + ' | /bin/cat';
        var output = widget.system(commandLine, null);
        document.getElementById('outputArea').value = output.outputString;


<div id="BackgroundLayer" class="backStyle">
        <img src="Default.png" width="400" height="600">
        <div id="TextLayer" class="textStyle">
                <div align="right"> Get More Info On:</div>

<div id="InputLayer" class="inputStyle">
  <input id="programName" type="text"
         size="14" border="0" height="23px" width="123px"

<div id="OutputLayer" class="outputStyle">
  <textarea  id="outputArea" cols="42"
            rows="25" readonly>


This is about as simple an HTML file as you can get: there is some header information, one JavaScript function, one style, and then some HTML markup. The HTML markup defines three layers: one for the background, one for a box where a user can input the name of the *nix command that they want a man page for, and one for the output of the man page. To trigger the retrieval of the man page, when the value in the programName input box has changed, it calls the getManPage() function via the onchange attribute.

The getManPage() function is where all the heavy lifting of this widget happens. Here is what happens, line by line:

More to Come

While this is not the most complex or useful widget in the world, it does show off some of the capabilities of what Dashboard can do. Since Dashboard gives full access to the *nix shell, it is easy to imagine a widget calling a Perl script that makes database calls or interacts with a local CVS server. This means that, beyond the obvious uses of creating end-user widgets, Dashboard provides developers with a rapid prototype environment where they can try out new ideas with only a little bit of coding required.

The next article will include information on debugging and testing widgets, links to some sites that have sprouted up with widgets to download and bulletin boards for widget developers, and a how-to on writing a widget that uses JavaScript's object to retrieve information from remote web XML servers.

If you are looking for more information on Dashboard widget development, check out Apple's Developing Dashboard Widgets page. The page is kind of sparse, but gives some insight to developing widgets

Andrew Anderson is a software developer and consultant in Chicago who's been using and programming on the Mac as long as he can remember.

Return to

Copyright © 2009 O'Reilly Media, Inc.