Apple’s operating system OS X has been supplied with a feature/app called Dashboard since version 10.4 Tiger. Dashboard is effectively a layer that appears on top of your desktop, displaying a number of custom “widgets” to tell you pretty much anything you want to know, like world times, flight times, your ebay sales etc etc… Since the release of 10.4, thousands upon thousands of these so-called “widgets” have been developed, and in this tutorial I will describe how you can do the same, using the power of jQuery.

Dashboard Widgets

All Dashboard Widgets are effectively mini websites in a tight wrapper. The basic structure of any widget is an HTML file (assume your index file for example), a number of related javascript files to control the widget and its custom controls, such as buttons – and a number of image files. Sounds pretty familiar right?

So what Dashboard does is it reads in your HTML page, but instead of rendering it within a browser page, it scraps that idea and renders the contents of that HTML as a widget. It uses the webkit framework that the Safari browser also uses to render the pages, so if your code is standards compliant – it should look exactly as you expect.

So seeing as the basic construction of a Dashboard widget appears to reflect any normal web application, javascript libraries such as jQuery can be utilized to the full, for ajax functionality, element animation, css changes – the lot. Whilst jQuery doesn’t actually support this type of use, it does work (How well it completely works I don’t know), but it starts to make the idea of creating widgets extremely easy to swallow.

Setting up the project

I will be using Apple’s Dashcode application to build my widget, simply because it makes our lives even easier. So first things first, create a new widget in Dashcode using the “custom” template.

Once that is complete, we need to import the jQuery file into our project. Goto File -> Add File and browse to your jQuery .js file and choose OK. This will import a copy of that file into the project. You can now view where that has been placed within the strucutre of the widget by checking out the the file browser window in the bottom left.

The final step is to reference the new jQuery library. Assuming that the jQuery library was imported into the root directory, this would be done like so in the main.html file:

Make sure you add this before the HTML file calls the main.js file, as that is where we will put our controller code.

Setting up the Widget

Next up we need to create the controls on our widget. Remove anything already on there – probably some text like “Hello World” and drag on two things:

1. A Button – Give it an ID in the inspector of “jQueryButton”
2. A Rounded Corner box. Give it an ID in the inspector of “rounded_box”

Here’s how I’ve done it:

The last thing you need to do is goto the main.css file in your project and edit the “#rounded_box” element. Add a CSS parameter of “display: none” to the element and save your project. What should happen here is your rounded box will disappear from the layout preview.

Adding the jQuery

The last part of the tutorial is adding our jQuery code into the project to wire up our button to do something. Dashboard actually has the ability to already wire up evens such as onclick etc, however I am going to write this all completely in jQuery as it is supported. So, within the main.js file, scroll to the bottom and add the following code:

var toggle = "off";

$(document).ready(function() {

$("#jQueryButton").click(function(){

if(toggle == "off")
{
$("#rounded_box").animate({"opacity": "show"}, 300);
toggle = "on";
} else {
$("#rounded_box").animate({"opacity": "hide"}, 300);
toggle = "off";
}
});

So this piece of code sets up a “toggle” variable, and wires up a click event for our new button and tells its to animate our rounded box to show/hide on click. As you can see, this is 100% jQuery functionality, and it all works seamlessly within the widget.

Notes

Now that jQuery is implemented you can use it to really enhance and ease the development of your widgets. Ajax calls can be a whizz – remember to turn on Network communications in the widget settings though, otherwise no GET or POST ajax calls will work.

You can also use jQuery to manipulate all of the built-in controls Apple provides in a similar way as I have done so above.

Theoretically this approach should also be applicable for Vista Gadgets if you’re that way inclined…

I’d love to see what you guys come up with, so feel free to pimp out your widgets below that use jQuery. Also let me know any limitations you may find.

Download

I have packaged up the Dashcode project for you to check out how this is implemented, and re-use as necessary. Click the icon on the left. Please share any feedback or projects you worked on that this helped with below.

Tools to help you learn…

Learning jQuery 1.3	Amazon Kindle 2	jQuery UI 1.6

This entry was posted on Tuesday, March 10th, 2009 and is filed under Apple, Development, Technology, jQuery. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.