Utility software

Whip up a widget

Sure, you can download a widget that finds the nearest Pizza Hut or that flips a virtual coin. But what if you simply want to keep track of the days until your next vacation, or make sure that your spouse remembers to plan your surprise birthday party? You don’t have to settle for downloaded widgets when it’s so easy to make your own.

I’ll show you how to build a widget that counts down to an event that’s as far as a year away. Because the widget does all this with a single image and some HTML, JavaScript, and CSS, you can easily modify it to display whatever you want. You can download everything you need for the job.

Widget Deconstructed

At its simplest, a widget consists of four things: a PNG image named Default.png, a preference file named Info.plist, an HTML file, and a folder (which holds the other pieces) with a name ending in .wdgt.

The PNG Image Widget graphics must be PNG (Portable Network Graphics) files. In particular, a widget needs a background image named Default.png. I chose a picture of a white cake because it’s appropriate for so many occasions—from birthdays, anniversaries, and weddings to a baby’s due date.

The Preference File If you’ve never written a Mac application before, the Info.plist file is probably new to you. It’s really just a text file containing preference information that the widget needs in order to work correctly. For example, this file tells the widget how large it should be and where to put the close box (the X within a circle). If you’ve installed the Xcode Developer Tools that come on the Tiger installation DVD, you can launch the Property List Editor utility (/Developer/Applications/Utilities) and create a file from scratch that contains the required properties and values (see first screenshot). For this example, simply download the countdown widget’s Info.plist file and modify the appropriate fields using the Property List Editor utility or a plain-text editor such as Bare Bones Software’s free TextWrangler.

The HTML File There isn’t enough room here to print the entire text of the widget’s main.html file. Instead, download it from Macworld.com and open it with a text editor. If you’ve ever worked on a Web page before, you won’t find much that’s surprising. Actually, you can open this HTML file in a Web browser and it will display just fine—that’s a handy way to debug any changes before turning the whole thing into a widget.

About two-thirds of the file is JavaScript, with a smidgen of CSS and HTML making up the remainder. Even if you don’t know the first thing about JavaScript or HTML, it’s not hard to modify the following critical part:

	var theMonth = 8;
	var theDay = 7;
	var thePerson = "Dori";
	var theEvent = "birthday";

This code says that my birthday (what the widget counts down to by default) is on the seventh day of the eighth month—that is, it’s on August 7. Just change these four fields, and your widget will display a new event. For instance, to count down to my niece’s upcoming marriage, I’d change the fields to read as follows:

	var theMonth = 5;
	var theDay = 6;
	var thePerson = "Kate and Aaron";
	var theEvent = "wedding";

The widget would then display a countdown to their nuptials on May 6 (for example, “165 days until Kate and Aaron’s wedding”). After their wedding, I can change one line:

var theEvent = "anniversary";

The widget will forever afterward remind me of their anniversary each year.

The Folder Believe it or not, all you need to do to create a widget is move the three files mentioned earlier into a folder, and then give that folder a name ending with .wdgt (for example, My Vacation.wdgt ). You’ll get an alert asking whether you really want to use that extension; click on Add to verify that you do. (Those letters on the end tell OS X that the folder is a package.) The folder icon then turns into a widget. When you double-click on it, the OS will launch it instead of opening the folder.

Move that widget into / your user folder /Library/ Widgets. You’ll see this folder if you’ve ever autoinstalled a widget; if it doesn’t exist, just create it. The next time you trigger the Dashboard layer (by pressing F12) and click on the plus sign (+) at the bottom of the screen (or press Command-=) to reveal the Widget Bar, your new widget should appear, listed in alphabetical order (based on folder name). If you can’t see it, you might have to scroll past where it should be and then back again to reveal it. Click on the widget, and it will ripple and then appear in the center of your screen (see second screenshot).

Eradicate Errors If, when you view your widget, you find that you made an error and need to get into the files again, control-click on the widget folder in the Finder and choose Show Package Contents from the contextual menu. Edit the files and reload the widget, and you should see your changes. Reload a widget by clicking on it in the Dashboard layer (to make it the frontmost widget) and pressing Command-R. You’ll see it swirl, and then the new version will appear.

Advanced Geekery

Everything we’ve discussed so far should be well within the abilities of anyone who has ever edited a text file, created a folder, and renamed a file. Here are some possibilities for people who want to take this a step further .

Change Your Image If the image of the plain white cake doesn’t fit your event, you can replace it with any PNG file you want. Just give it the name Default.png, and your image will display instead of mine.

To make it look perfect, though, first pick an image that’s not too large (the average widget is no more than 300 pixels high by 350 wide, and most are smaller) and that has enough empty space to hold your message. Next, go into the Info.plist file and change the

values (in pixels) to match those of your new image. (Click on the image icon in the Finder and press Command-I. You’ll find the image dimensions under More Info.) You may also need to change the
values; those are, respectively, the x and y coordinates for where you want the close box to display.

Change Your Style Maybe fuchsia and cursive just aren’t your style, or perhaps you have a lot to say and only a small space in which to say it. Look in the HTML file for the style section, and modify the rules in the


font: 40px/56px "Apple Chancery", cursive; color: fuchsia

CSS (Cascading Style Sheets) standards determine the colors and styles you can choose from. Basically, you can style the text using any fonts on your computer, but you should always assign a backup of serif, sans serif, monospace, cursive, or fantasy in case that font isn’t available. Pick a color from options including black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, and yellow. (If you’re feeling sassy, you can use any CSS RGB hexadecimal value, from 000000 to FFFFFF.)

One of the best things about widgets is that you can reliably depend on people having the many gorgeous fonts that Apple includes with Tiger—from AmericanTypewriter to Zapfino. If you want to pass your widget on to others, make sure to use an Apple font.

Double Your Pleasure Want to have multiple countdowns, each for a different date? Duplicate your widget and give the new version a different name (still ending with .wdgt, though). Open the new widget’s HTML file and change the dates and names (as you did earlier) to reflect the alternative event. Now open the new Info.plist file and look for each property that starts with

. If you want more than one countdown widget based on this example, you need to change these to unique values. For example, you might change

Go back into the Dashboard layer and check out the Widget Bar; you should see both versions now.

What’s Next?

Now that you’ve created your first widget, you can send it to your friends or upload it to Apple’s widget submission page for other people to check out. Even better, send your countdown widgets (based on this example) to geekfactor@macworld.com. We’ll post our favorites on the Web site.

[ Dori Smith is the author of the upcoming Dashboard Widgets for Mac OS X Tiger: Visual QuickStart Guide (Peachpit Press). ]

A preference file called Info .plist stores all the basic information that a widget needs to know about itself—from its dimensions to the location of its close box.Put one of these on your spouse’s Mac, and he or she will never again forget your birthday or anniversary.

Subscribe to the Help Desk Newsletter