Recent Widgets


Register for DashboardWidgets

Recent Forums Posts

Partners


iCompositions

MacDesktops.net

RSS Showcase
RSS Comments
RSS Forums

Post new topic   Reply to topic Posted in: Widget Development

Widget Development FAQ (Read this first before posting!)

Author Message
kingmob



Joined: 07 May 2005
Posts: 68
Location: Vienna

Posted: Thu Jun 02, 2005 - 10:53 am    Post subject: Widget Development FAQ (Read this first before posting!) Reply with quote

DASHBOARD WIDGETS FAQ

This FAQ answers common questions and offers solutions to much-encountered problems. It was created to minimize the amount of "One problem, 5 threads" situations. If you find a mistake or have an addition, please PM me on the board.

TABLE OF CONTENTS

1.0 Introduction to widgeting
1.1 I'm completely new to this whole widget thing - where do I get started?
1.2 Where can I learn JavaScript?
1.3 How do I get beautiful and shiny backgrounds/icons for my widget?
1.4 Are there any guidelines on how a widget should act, look and feel like?
1.5 What files must be in a widget?
1.6 What is an Info.plist?
1.7 I created all the needed files, now how do I bundle my widget?

2.0 Programming issues
2.1 How do I open a link in a browser window from a widget?
2.2 I tried to run a program with widget.system(), but it didn't work!
2.3 How do I parse an HTML or XML document from a widget?
2.4 How do I debug a widget?
2.5 How do I call an AppleScript from a widget?
2.6 How can I make my widget do something when it appears or disappears?
2.7 How do I get a "Done" button like the one on the backside of Apple's widgets?
2.8 How can I make my widget check for updates?
2.9 How can I create a Preferences backside for my widget?
2.10 How do I add custom fonts to my widget?

3.0 Problems
3.1 My widget simply doesn't work! What now?
3.2 Searches via openURL() with one-word terms work, but if I look for two or more words, nothing happens.
3.3 Special characters (umlauts and the like) don't work for XMLHttp or openURL() calls!

4.0 The rest

1.0 Introduction to widgeting

1.1 I'm completely new to this whole widget thing - where do I get started?

Take a look at Apple's Dashboard Programming Guide, their Dashboard Reference and lutz' Dashboard Development for newbies. Also, if you have intalled the XCode Tools that come with your Tiger DVD, take a look at /Developer/Examples/Dashboard on your Macintosh HD.

There is also a new wiki centered around widget design and development.

1.2 Where can I learn JavaScript?

There are various tutorials about JS on the net. Here's one from w3schools.com , and another one from pageresource.com.

1.3 How do I get beautiful and shiny backgrounds/icons for my widget?

You could either ask one of the designers that lurk in the Widget Design forum, or read Alex Edelman's excellent widget graphics howto reverse engineering the shiny.

1.4 Are there any guidelines on how a widget should act, look and feel like?

Yes, the Widget Design Conventions. Please, read them. Memorize them. Love them. Wink

1.5 What files must be in a widget?

A widget needs at least a Default.png file (The image shown when the widget is loading), a main HTML file, an Icon, and an Info.plist. For more info on this, see here.

1.6 What is an Info.plist?

Info.plist is a file that contains basic information on your widget - the name, version number, filename of the main HTML file, and so on. You can create and edit it with the Property List Editor that comes with the XCode tools and is found in /Developer/Applications/Utilities on your Macintosh HD. For info on possible contents of Info.plist, see here.

1.7 I created all the needed files, now how do I bundle my widget?

Create a new folder, move the files into the folder and then add the file extension ".wdgt" to that folder. Finder will ask you if you really want to change the extension, say yes. You will then notice that the folder image has switched to the black-and-white dashboard icon. That's it!

2.0 Programming issues

2.1 How do I open a link in a browser window from a widget?

Use widget.openURL. Syntax:

Code:
widget.openURL("http://foo.bar.org");

2.2 I tried to run a program with widget.system(), but it didn't work!

widget.system() requires you to use the full path of the program you want to run. Example:

Code:
widget.system("usr/bin/id -un", null);

For more information, see here.

If you have problems with getting information back from a system() call, and the size of the info you expect is over 4k, read this thread for a workaround.

Also make sure that you have the AllowSystem key set to True in your Info.plist (Thanks to Mayhem who reminded me of this).

2.3 How do I parse an HTML or XML document from a widget?

Use the XMLHTTPRequest object. See here for the documentation. Also look at this thread for some examples.

Mayhem notes that this only works for XHTML compliant HTML, but he also offers a neat workaround for non-compliant pages.

2.4 How do I debug a widget?

Use the alert() function, for example,

Code:
alert(myString);

This will print the contents of the myString variable to the console log, which can be viewed with the Console program. See also Apple's Technical Note TN2139 on how to debug widgets.

2.5 How do I call an AppleScript from a widget?

Use widget.system() and the osascript program. See this thread for an example.

2.6 How can I make my widget do something when it appears or disappears?

You want to use widget properties. Here's the documentation, and here are some examples.

2.7 How do I get a "Done" button like the one on the backside of Apple's widgets?

Use createGenericButton().

2.8 How can I make my widget check for updates?

This has been discussed here.

2.9 How can I create a Preferences backside for my widget?

This is explained in the Dashboard Programming Guide.

2.10 How do I add custom fonts to my widget?

Tahkcalb answered this here. Add the following to your Info.plist :

Code:
<key>Fonts</key>
<array>
<string>FontFileName</string>
</array>

Then simply reference the font via CSS. The font file has to reside in the root directory of your widget for this to work.

3.0 Problems

3.1 My widget simply doesn't work! What now?

Okay, before you post in the forum, please go through this basic checklist.

* Does your widget contain all the needed files?
* Do you have all the needed entries in the Info.plist, ESPECIALLY the Allow flags?
* Is your code valid (Did you close all brackets, add semicolons where needed, etc.) ?
* Is the HTML valid (All tags closed, no <input> fields without a <form> around them ...) ?

If you checked all that, please search through the forums for a similar problem. If you don't find one, feel free to post Smile

3.2 Searches via openURL() with one-word terms work, but if I look for two or more words, nothing happens.

You need to exchange the whitespace between the words with a seperator. In most cases, this is a plus (+) sign. You can do this either with the encodeURI() function or with a small piece of regexp:

Code:
var foo = foo.replace(/[\s]/gi, '+');

OR

var foo = encodeURI(foo);

3.3 Special characters (umlauts and the like) don't work for XMLHttp or openURL() calls!

This is a known problem. See this thread for a workaround.

4.0 The rest

This FAQ has been created by Philipp Droessler (kingmob on DashboardWidgets), and uses both information from Apple and postings provided by other DashboardWidgets members, along with some external sources. All material is owned by the respective owners. I take no responsibility for the contents of this FAQ, the results of said content on you or others, or anything else for that matter. Please don't sue me, I mean well.

If you have any additions to this FAQ, or found an error, please PM me on the DashboardWidgets board, and I'll add/correct it as soon as possible.

Thanks to: Apple, everyone at DashboardWidgets.

Special thanks to the people who contributed to the FAQ: powermac99, Mayhem and Tahkcalb.
View user's profile Send private message Send e-mail Visit poster's website AIM Address ICQ NumberWidgets
Barcode



Joined: 02 Jun 2005
Posts: 16
Location: New York, NY

Posted: Thu Jun 02, 2005 - 3:10 pm    Post subject: Why use <form> tag? Reply with quote

In section 3.1 you mention the following.

"* Is the HTML valid (All tags closed, no <input> fields without a <form> around them ...) ? "

I don't understand the point of using <form> tags even if you are using <input> elements. You don't need to use them. Just add a button ( <input type=button> or <button> ) and use the onclick event to register your event handler for that button.

PS> This is a great FAQ, BTW.
View user's profile Send private message Widgets
kingmob



Joined: 07 May 2005
Posts: 68
Location: Vienna

Posted: Thu Jun 02, 2005 - 3:47 pm    Post subject: Re: Why use <form> tag? Reply with quote

Barcode wrote:
I don't understand the point of using <form> tags even if you are using <input> elements. You don't need to use them. Just add a button ( <input type=button> or <button> ) and use the onclick event to register your event handler for that button.

Hi Barcode, well, from my experience, unless you add a <form> tag with an "action='javascript:myFunction();'" line to the widget, the autosave feature of <input type="search"> won't work. Also, it's the proper way to do it Wink
_________________
I have no .sig and I must post.
View user's profile Send private message Send e-mail Visit poster's website AIM Address ICQ NumberWidgets
Barcode



Joined: 02 Jun 2005
Posts: 16
Location: New York, NY

Posted: Fri Jun 03, 2005 - 10:31 am    Post subject: Now I see... Reply with quote

Thanks kingmob for the clarification. I understand know what you are talking about.

On the Developing Dashboard Widgets page there is the following information.

Quote:
A new search type, <input type="search">, that allows you to create a Mac OS X-style search box.


When I read this page I must have missed that section.
View user's profile Send private message Widgets
Liquidrums



Joined: 17 Jun 2005
Posts: 23
Location: Houston, TX

Posted: Thu Jun 30, 2005 - 11:47 am    Post subject: Reply with quote

Where's a part in the faq about how to save the preferences between opening/closing of the widget?
View user's profile Send private message Send e-mail Visit poster's website AIM Address Widgets
segdeha



Joined: 23 May 2005
Posts: 15
Location: Albuquerque, NM

Posted: Thu Jul 07, 2005 - 12:45 pm    Post subject: Saving & Retrieving Preferences Reply with quote

Liquidrums,

I have recently posted a tutorial for developing Dashboard widgets. It includes a section on saving & retrieving preferences. Check it out at the following URL:

http://andrew.hedges.name/widgets/dev/

-Andrew
View user's profile Send private message Send e-mail Visit poster's website Widgets
tie



Joined: 03 Jul 2005
Posts: 21

Posted: Sat Jul 09, 2005 - 3:49 pm    Post subject: Reply with quote

This feels like a FAQ-type of question.

How can I read a local file?
View user's profile Send private message Send e-mail Widgets
segdeha



Joined: 23 May 2005
Posts: 15
Location: Albuquerque, NM

Posted: Sat Jul 09, 2005 - 4:00 pm    Post subject: Reading files into a widget Reply with quote

In my SlideShow widget, I use command-line PHP (installed by default in Tiger) to read in two files, one with captions and another with URLs. I think your idea of writing the output to a file would work. Feel free to download SlideShow and use the PHP code contained in the scripts folder for ideas on reading in the contents of your file.

http://www.dashboardwidgets.com/showcase/details.php?wid=653

-Andrew
View user's profile Send private message Send e-mail Visit poster's website Widgets
tie



Joined: 03 Jul 2005
Posts: 21

Posted: Sat Jul 09, 2005 - 5:38 pm    Post subject: Re: Reading files into a widget Reply with quote

Here is what I have tried, and it is not working:

Code:

var perlreadline = "while (<STDIN>) { print $_; }"
var asy = widget.system("/usr/bin/perl -e '" + perlreadline + "'", function(object) {
   alert("finished");
   alert("status= " + asy.status + ", output= " + asy.outputString + ", error= " + asy.errorString);
   asy.close();
});
asy.onreadoutput = function(object) { alert("out"); alert(object); asy.write("again\n"); }
asy.write("ready?\n");
asy.write("go!\n");


For now, I am just trying to get it to repeat out what is said in. Once that works, I can plug in
Code:

var perlreadline = "open (INFILE,$ARGV[0]) || die \"cannot open: $!\"; while (<STDIN> && ($line = <INFILE>)) { print $line; } close(INFILE);";

and feed it also the file name. The output should be
Quote:

out
ready?
out
go!
out
again
out
again
....

Yes, it should loop forever. But actually nothing is output, unless I call asy.close() in which case
Quote:

out
ready?
go!

is written. Note that both ready? and go! are coming out from a single call to onreadoutput, not two. Somehow the \n's aren't flushing STDIN. (Note that the perl code must use <STDIN> for even this behavior, <> doesn't do anything.) How do I properly flush STDIN?

Edit: I can't duplicate this behavior outside my widget. For example
perl -e 'while (<>) { print $_; }'
works fine, while
sh -c "perl -e 'while (<STDIN>) {print $_; }'"
is a bit crazy, presumably because STDIN isn't being directed properly (not the same issue as why the widget doesn't work).
View user's profile Send private message Send e-mail Widgets
Mary



Joined: 11 Aug 2006
Posts: 1

Posted: Fri Aug 11, 2006 - 6:04 am    Post subject: Reply with quote

Please don't re-post unverified, old responses. Several of the links in the above list are broken. Posting nothing would have been better in this case.

For example the link to the "Dashboard Programming Guide." in "2.9 How can I create a Preferences backside for my widget?" above is broken (and there are others).

And one of the threads ends with the user still not getting helped! So where's the help?

I'm sure you meant to be kind and thoughtful by posting a list of other previous answers, but what's facile for you is frustrating for others.

If you don't feel like answering, you really don't have to. Danke.
View user's profile Send private message Send e-mail Widgets
feddd



Joined: 30 May 2011
Posts: 1
Location: London

Posted: Mon May 30, 2011 - 2:46 am    Post subject: Reply with quote

Thank you for links, kingmob.
I am a newbie in Java and your FAQ is very useful for me. Keep going the same way!
Fed Drezden.
View user's profile Send private message Send e-mail Widgets
Post new topic   Reply to topic

 
Powered by phpBB © 2001, 2002 phpBB Group