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

Introduction

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 ftp.mactech.com/src/mactech/volume24_2008/24.10.sit. The source archive contains the following files:

SavePrefs.html file

SavePrefs.js file

SavePrefs.css

Info.plist

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"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>BackwardsCompatibleClassLookup</key>
<true/>
<key>CFBundleDisplayName</key>
<string>Save Prefs</string>
<key>CFBundleIdentifier</key>
<string>com.mtsouk.widget.saveprefs</string>
<key>CFBundleName</key>
<string>Save Prefs</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>CloseBoxInsetX</key>
<integer>14</integer>
<key>CloseBoxInsetY</key>
<integer>16</integer>
<key>MainHTML</key>
<string>SavePrefs.html</string>
</dict>
</plist>

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:

   if(window.widget)
   {
       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:

   if(window.widget)
   {
       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
-rw————
    1 mtsouk   mtsouk         98 May 18 22:13
    /Users/mtsouk/Library/Preferences/widget-com.mtsouk.widget.saveprefs.plist
mtsouk$

The contents of the widget-com.mtsouk.widget.save-prefs.plist file are the following:

   <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>OptionString</key>
   <string>Option 4</string>
</dict>
</plist>


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)!!

Conclusions

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: http://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_ProgTopics/Introduction/Introduction.html

Introduction to Dashboard Tutorial: http://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_Tutorial/Introduction/chapter_1_section_1.html

Developing Dashboard Widgets: http://developer.apple.com/macosx/dashboard.html

Apple Dashboard Page: http://developer.apple.com/appleapplications/dashboard/

Debugging Dashboard Widgets: http://developer.apple.com/technotes/tn2005/tn2139.html

Dashboard Sample Code: http://developer.apple.com/samplecode/AppleApplications/idxDashboard-date.html#//apple_ref/doc/uid/TP30000925-TP30000418-TP40001366

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 tsoukalos@sch.gr.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »

Price Scanner via MacPrices.net

13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1179 $120 off MSRP - 13″ 2.7GHz/... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Apple refurbished iMacs available for up to $...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
15-inch Retina MacBook Pros on sale for $200-...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 $200 off MSRP - 15″ 2.5GHz... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $300 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799.... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
ABBYY TextGrabber: 1,000,000 Installs in 5 Da...
ABBYY, an international OCR technologies provider, has announced that their image-to-text application TextGrabber, got installed 1,000,000 times in just five days while being featured by the App... Read more
New SkinIt Waterproof Case For iPhone 6
With its impact and waterproof design, the Skinit Waterproof case provides security and protection to guarantee your phone will get you through even the most demanding outdoor conditions. The impact-... Read more

Jobs Board

*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
Music Marketing Lead, iTunes & *Apple*...
…Music Marketing Lead is responsible for developing robust marketing campaigns and programs for Apple Music and iTunes across the whole of Apple ecosystem. This Read more
*Apple* Valley Medical Clinic is Hiring - AP...
Apple Valley Medical Clinic is Hiring! Apple Valley Medical Clinic is an independently owned practice operating a Family Medicine Clinic, a 24/7 Urgent Care, Read more
*Apple* New Products Testers Needed - Apple...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.