A Hello World Tutorial for Creating Dashboard Widgets
The most basic Tiger dashboard widget that would actually run successfully,
followed by other super duper basics for the widget-curious rest of us.
by Josh Nimoy, May 3,2005

for ITP
Create a folder on your desktop and call it HelloWorld.wdgt . The OS will probably pop up a dialog asking if you are sure, so click add.
Now take a look at the folder and notice how it appears with the Widget icon.

We will now remove the .wdgt from the end of the filename. Highlight the folder and open its Info window by choosing File > Get Info. Under Name & Extension, check the box where it says Hide Extension and then close the Info window.
The ".wdgt" is now hidden.
We will now open the widget folder and add some files. Control+click your new HelloWorld widget and a contextual menu will pop up. Choose Show Package Contents
A new folder will open up. Keep that folder open because you'll be dragging files into it.
Create a PNG image file called Default.png and drag the file into the widget folder. This here 100x100 pixel image is a photo of Tom Igoe's small pink monkey. Few things are not improved by its addition.
Now we will create a file called Info.plist using TextEdit. Open TextEdit and choose the menu item Format > Make Plain Text because you are creating a simple ascii file.
Enter in the XML code shown on the left. Here, you are creating 2 pieces of data: a CFBundleIdentifier key that holds a unique string for that widget, and a MainHTML key, telling the dashboard which HTML file in your widget to use. I've used com.jtnimoy.widget.HelloWorld in this example, but please make up your own unique string.

Choose File > Save As and call the file Info.plist. Drag this file into your widget folder.
Create an HTML file called index.html with the only the code "<img src=Default.png>" and place that file into the widget folder as well.
Your widget folder should have all three files in it, looking like the image on the left.
Double click your widget icon and it will launch the dashboard. You will see whatever you put into Default.png appear as its own useless little widget. You can drag the widget around, and close it.

Congratulations! You have just made your first dashboard widget!

The rest of this tutorial will guide you through the rest of the widget basics beyond this entry point.

Download the widget


Getting a widget into the dashboard shelf/chooser


With Icon.png


Without Icon.png
 Create an 79x80 pixel PNG image called Icon.png and include it in the widget bundle along side Default.png .

Doing any of the following things will get your widget into the dashboard widget chooser:

- Move the widget file into ~/Library/Widgets for just your user.

- Move the file into /Library/Widgets for all users on the system.

- Zip up the widget, upload the zip file to a server, and access the URL from Safari. Safari will automatically download the zip, unzip the file, then add it to ~/Library/Widgets and you'll see it in the widget chooser next time you look.
   


My First Interactivity : Flipping to the Back
The following steps show you how to make the widget flip back and forth between front and back sides when you click on it.
<div id=front><img src=Default.png></div> Reopen index.html and put that lone img tag into its own DIV. DIVs can be controlled like Director sprites or Flash Movieclips using CSS properties.
<div id=front><img src=Default.png></div>
<div id=back><img src=Back.png></div>
 Create some image called Back.png, preferrably the same size as Default.png, and place it into the bundle. Add another DIV with that image into index.html.
<script><!--
function swapDivs(id1,id2,transitionStyle){
  var i1 = document.getElementById(id1);
  var i2 = document.getElementById(id2);
  widget.prepareForTransition(transitionStyle);
  i1.style.display="none";
  i2.style.display="block";
  setTimeout ('widget.performTransition();', 0);
}
//--></script>		 The following is a generic function added to the top of the HTML file. This function, called swapDivs, will be called when either DIV is swapping back or forth to show and hide. If you look at this function, you'll see a special Javascript object called window.widget handling the fancy Apple effects.
<div id=front onclick='swapDivs("front","behind","ToBack");'>
  <img src=Default.png>
</div>
<div id=behind onclick='swapDivs("behind","front","ToFront");'>
  <img src=back.png>
</div>		 Now we can add some onclick events into both divs that call the swapDivs function.
Save the HTML and launch the widget again. Click and you will see it flip around clockwise. Click it again and you will see it flip back around, counter clockwise!


My First Button
Apple provides some useful shared resources in the folder /System/Library/WidgetResources . This guide will show you how to generate a 'generic' button on your widget using their provided createGenericButton function.
<script type='text/javascript' src='file:///System/Library/WidgetResources/button/genericButton.js' charset='utf-8'/> First add this script reference to the top of the page, it will provide that special function. When you call this function, you pass three arguments: the name of some poor DIV it's going to take over, a string for the message that will be inside the button, and the name of a javascript function the system will call when the user pressed the button.
<div id=front    ><img src=Default.png>
   <div id=button1></div>
</div>
<div id=behind><img src=back.png onclick='swapDivs("behind","front","ToFront");'></div>
Here, I've done 2 things to the main HTML. I removed the first onclick attribute from the front DIV, and I added a new baby DIV to the front and called it button1.
<script><!--
  createGenericButton( button1, "Yeah", button1Pressed);
//--></script>		 Then add this code to the very bottom of the page. This is the actual function call that relinquishes the button1 DIV to buttonhood.
function button1Pressed(){
  swapDivs("front","behind","ToBack");
}		 This function gets added into the javascript section right under swapDivs. This is what gets called when the button gets pressed. Fill it with whatever code you want. In this case, a flip to the back is initiated.
<style>
#button1 {
   position:absolute;
   top:60px;
   left:30px;
}
</style> 		And last but not least, we need to tell the button1 layer where it's going to sit on the form. top and left are like the X and Y position. This chunk of code can be added at the very top of the page.
  See the entire index.html now
Relaunching the widget now, you should see a translucent button on top of monkey's face that says "yeah." Click it and you'll flip to the backside of the widget.

Download this version of the widget



Where to go from here
The best resource for learning how to make dashboard widgets is (by far) Apple Developer - providing both a guide and a reference. I highly recommend reading Apple's documentation thoroughly if you are still interested in making widgets after having gotten you feet wet in this brief tutorial. [ Link ]
Just as web media programming can be best learned by viewing the source of other projects, you can also "view source" of a widget (partially) by opening the package contents and poking around in its files.
Furthermore, there is a small folder installed in the Tiger system, at /System/Library/WidgetResources and I recommend poking around in there, as well as seeing how existing widgets are referencing such resources.
Happy Widgeting!



Below this line are people's posted comments.
Your Name:


Add Comment:

[submission button has been removed until I can install a CAPTCHA]
posted by josh [24.130.46.241] on Tue May 3 2:16:30 PDT 2005

testing testing 1 2 3
posted by max [213.36.138.242] on Mon May 16 13:07:19 PDT 2005

thanks, really good tutorial i\'ve just made my first one ;)
posted by pea [62.252.192.12] on Tue May 17 17:08:56 PDT 2005

Thanks buckets!
I\'m also making my first widget.
Will post back once it\'s fully widgeted.
posted by jaap [82.92.231.47] on Tue May 24 3:36:33 PDT 2005

keeeeeeeeeeeeeeeeeenker
posted by deepPLay [206.163.124.208] on Wed May 25 22:17:11 PDT 2005

thank you .
posted by rblitz [24.188.87.62] on Thu May 26 19:59:25 PDT 2005

cool but how would you make a button that goes to anothor pic? like a photo album
posted by dooko [149.175.72.95] on Sat May 28 15:40:40 PDT 2005

I\'m trying to add a flash animation on top of the PNG but it isn\'t working... Otherwise, great tutorial.
here are some things to add into the info.plist but they are considered security risks.

<key> AllowInternetPlugins </key> <true/>
<key> AllowJava </key> <true/>
posted by bthemacgeek@aim.com [65.110.138.88] on Tue Jun 14 16:33:27 PDT 2005

Hey, thanks so much for the awesome tutorial! Just like the guy/girl above, I\'d like to create a sort of photo album by using a button to click through photos. If you know how to do this, please email me at the address I put as my name. Thanks!

-B. The Mac Geek
posted by Tommo [17.86.55.136] on Mon Jun 20 19:36:06 PDT 2005

have copied the stes you suggested but cannot gte my widget to work. The download of your helloworld widget works, though. Any suggestion as to what I can troubleshoot to fix
posted by a [80.202.23.17] on Mon Jun 27 14:59:20 PDT 2005

try again until it works, change some things while you\'re at it and it might work.
posted by Stan [81.179.73.118] on Sun Jul 10 18:36:57 PDT 2005

I\'m a bit confused about one line in the Info.plist file. The line which reads:

<string>com.jtnimoy.widget.HelloWorld</string>

what am i supposed to replace that with...? i tried replacing the \'jtnimoy\' part with \'stan\' but it did nothing...my widget wont launch. Any ideas?

Thanks
Stan
posted by Dwayne [24.46.31.159] on Fri Jul 15 9:57:01 PDT 2005

I want to make a widget Portfolio viewer? What do I need to know?
-dwayne
posted by Andrea [146.145.124.146] on Fri Jul 22 11:04:49 PDT 2005

Thank you!
posted by santhosh [202.54.130.194] on Fri Sep 2 0:33:25 PDT 2005

The first step itself doesnt work for me. I am not getting the icon even though i have a .png file in that folder. How do I fix it?
posted by Jasper Burns [24.15.78.169] on Mon Sep 5 5:18:50 PDT 2005

Great help for my own personal use, thanks.
posted by vijaythefool@gmail.com [61.2.197.10] on Fri Oct 7 23:40:16 PDT 2005

iam still wondering ,, whenre to add the code, i made an image and it pops out , without any coding , where to add jacvascripts to make it interactive ?
posted by Jeff [137.53.85.90] on Tue Nov 15 14:24:17 PST 2005

Thanks for the tutorial! I noticed one error. In the section 'flipping hte back', your div ID's in the HTML are front and back. The JavaScript references these as front and behind. They need to match, or it won't flip!
posted by kooler van der Nooler [82.92.231.47] on Tue Nov 29 0:48:01 PST 2005

posted by dfskhgksjdf@yahoo.com [66.36.233.232] on Sun Jan 22 15:48:30 PST 2006

Hi
Do not prompt how to adjust a font of the messages? posted by [72.232.102.130] on Mon Apr 24 1:42:39 PDT 2006