TweetFollow Us on Twitter

A Dashboard Widget that Reads and Saves its Preferences

Volume Number: 24
Issue Number: 10
Column Tag: Dashboard Widgets

A Dashboard Widget that Reads and Saves its Preferences

Create a Dashboard Widget that can save and read data after restarting it.

by Mihalis Tsoukalos


In this article I am going to illustrate how to create a Dashboard Widget that saves its preferences. After saving the preferences, you will learn how to read and use the saved information and display the selected data in the front side of the Widget. The name of the Widget is "Save Prefs".

The files that compose the Widget

Figure 1 shows the files of the Widget as well as their sizes (in bytes).

Figure 1: The files that compose the "Save Prefs" Widget.

As you can understand by looking at Figure 1, the "Save Prefs" Widget is relatively simple. You should notice that it has a directory -the AppleClasses directory- that contains three JavaScript files. Apple provides the contents of the AppleClasses directory and the only thing that you should do is to copy the three JavaScript files inside your Widget's directory.

Also, as you will see in the next section, you will have to include them in the main HTML file of your Widget. Source code for this project can be downloaded from The source archive contains the following files:

SavePrefs.html file

SavePrefs.js file



You may think that the SavePrefs.js JavaScript file contains a lot of code but most of the code is typical when creating a Dashboard Widget. The showPrefs() and hidePrefs() functions are used for watching and hiding the back side of the Widget and you usually have to copy and paste their definitions to your new Widgets.

The SavePrefs.css file

The CSS file looks pretty simple. Nevertheless, if you make small mistakes to the CSS code the Widget may misbehave very badly! I am saying this because I had some problems with the #OptionPopup declaration. Due to my wrong declarations the option list was displayed outside of the Widget area and I could not see it at all!

The Info.plist file

The Info.plist file is pretty simple and is as follows:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
<plist version="1.0">
<string>Save Prefs</string>
<string>Save Prefs</string>

Explaining the Technique

The presented technique uses the following two JavaScript methods:

  • widget.preferenceForKey(keyName): This method tries to read the value of a key, if the value is already saved.
  • widget.setPreferenceForKey(value, keyName): This method sets the value of a key. The Dashboard Reference suggests that you should pass null in order to delete an existing key.

Apple suggests that you utilize the widget.preferenceForKey(keyName) function using the following practice:

       var optionString = widget.preferenceForKey("optionString");
       if (optionString && optionString.length > 0)
           optionText.innerText = optionString;

Similarly, Apple suggests that you use the widget.setPreferenceForKey(value, keyName) function as follows:

       widget.setPreferenceForKey("Hello MacTech!","optionString");

A word of advice: The described method stores strings without any encryption. It is therefore not a secure way to store your sensitive information.

The following lines of JavaScript code declare two global variables, called glassDoneButton and whiteInfoButton, respectively. Each of the two variables holds one button. The first declaration creates the done button whereas the second declaration creates that little info (i) button that you frequently see in Widgets.

   var glassDoneButton;
   var whiteInfoButton;

The following JavaScript code implements the two button definitions:

   glassDoneButton = new AppleGlassButton(document.getElementById("doneButton"),
            "Done", hidePrefs);
   whiteInfoButton = new AppleInfoButton(document.getElementById("infoButton"),
            document.getElementById("front"), "white", "white", showPrefs);

The following command line output text explains where Dashboard keeps the Widget stored information using the described method:

mtsouk$ ll ~/Library/Preferences/widget-com.mtsouk.widget.saveprefs.plist
    1 mtsouk   mtsouk         98 May 18 22:13

The contents of the file are the following:

   <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
   <string>Option 4</string>

Figure 2: The final look of the presented Widget (both sides).

A word of advice: You can now understand why it is extremely important to have a uniquely defined CFBundleIdentifier key for every Widget that you create or use. The above plist file that stores the Widget preferences uses the CFBundleIdentifier value as a part of its filename. It is also important to have a UNIQUE CFBundleName key because if you try to install a Widget with the same CFBundleName key, Dashboard will ask you if you want to replace the existing Widget (the other, different Widget with the same CFBundleName name)!!


This article presents an advanced technique that lets you store and retrieve your Dashboard Widget preferences or any other data you like. The presented Widget uses the back side for selecting the desired preference and its front side for displaying it but you can choose to implement it any way you want.

Bibliography and References

Introduction to Dashboard Programming Topics:

Introduction to Dashboard Tutorial:

Developing Dashboard Widgets:

Apple Dashboard Page:

Debugging Dashboard Widgets:

Dashboard Sample Code:

Disclaimer: The presented Widget code is a modified version of the "GoodBye" Widget provided by Apple and located on your Tiger machine (but not in Mac OS X 10.5), inside the "/Developer/Examples/Dashboard/GoodbyeWorld/3-SavingPreferences" folder. The "Save Prefs" Widget that is presented in this article has four options and, as you saw, it is a little bit more complicated than the "GoodBye" Apple Widget.

Mihalis Tsoukalos lives in Greece with his wife Eugenia and enjoys digital photography and writing articles. He is the author of the "Programming Dashboard Widgets" eBook. You can reach him at


Community Search:
MacTech Search:

Software Updates via MacUpdate

Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »
Snowboard Party 2 (Games)
Snowboard Party 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Crowned the best snowboarding game available on the market, Snowboard Party is back to fulfill all your adrenaline needs in... | Read more »
One Button Travel (Games)
One Button Travel 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: “To cut a long story short, If you like interactive fiction, just go buy this one.” - “Oozes the polish that... | Read more »
Light Apprentice Volume 1 (Games)
Light Apprentice Volume 1 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Light Apprentice Volume 1 includes Chapters 1 to 4, all gathered in a new exclusive game. When life in the world of... | Read more »
The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »

Price Scanner via

iMobie Releases its Ace iOS Cleaner PhoneClea...
iMobie Inc. has announced the new update of PhoneClean 4, its iOS cleaner designed to reclaim wasted space on iPhone/iPad for use and keep the device fast. Alongside, iMobie hosts a 3-day giveaway of... Read more
Black Friday deals on the Apple Watch and App...
Apple resellers are offering discounts and bundles with the purchase of an Apple Watch this Black Friday weekend. Below is a roundup of the deals being offered by authorized Watch resellers: Apple... Read more
Early Black Friday sale at B&H Photo, up...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699 $300 off... Read more
NewerTech/OWC/MacSales Black Friday Deals 201... • Free Shipping available on nearly EVERYTHING on orders $35.00 & up within USA + • International Delivery Specials from $2.99+ Special Purolator... Read more
Walmart Black Friday deals: $100 off select i...
Walmart has released their Black Friday deals for 2015, now available online. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2: $399, $100 off MSRP - 16GB iPad Air: $... Read more
Photo Cleaner 1.0 Reclaims iPhone Storage Spa...
Seoul, Korea based mix1009 has announced the release and immediate availability of Photo Cleaner 1.0, their handy iPhone app that deletes the video portion of Live Photos, in order to reclaim space... Read more
Black Friday and Holiday sales on our price t...
Scan our Mac Price Trackers for the latest Black Friday and Holiday season information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the... Read more
Best Buy Black Friday deals: Up to $200 off M...
Best Buy has posted their Black Friday sale prices for 2015. Save on MacBook Pros, MacBooks, MacBook Airs, iMacs, iPads, and Apple Watches. Choose free shipping or free local store pickup (if... Read more
Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more

Jobs Board

Storefront Operations Coordinator, *Apple* -...
# Storefront Operations Coordinator, Apple -Latin America Job Number: 43587750 Miami, Florida, United States Posted: Oct. 16, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
*Apple* Enterprise / Government Professional...
# Apple Enterprise / Gove ment Professional Services Engineer Job Number: 42292976 Reston, Virginia, United States Posted: Aug. 18, 2015 Weekly Hours: 40.00 **Job Read more
iOS Wallet & *Apple* Pay Engineer - App...
# iOS Wallet & Apple Pay Engineer Job Number: 40586801 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** The iOS Read more
Software Engineer, *Apple* Watch - Clock Fa...
# Software Engineer, Apple Watch - Clock Face Team Job Number: 44368761 Santa Clara Valley, Califo ia, United States Posted: Nov. 14, 2015 Weekly Hours: 40.00 **Job Read more
Administrative Assistant, *Apple* Online St...
# Administrative Assistant, Apple Online Store Job Number: 43992352 Santa Clara Valley, Califo ia, United States Posted: Nov. 9, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.