How to Hack a Dashboard Widget

The Dashboard these days is stale. We place a calculator here and a sticky-note there once every few weeks, but sadly, we haven't seen many great widgets come out recently. Today, to remedy the empty space in our Dashboard's heart, let's tear apart a widget and hack it into our own!

A Dashboard Dilemma

When we look at the Dashboard of the average Mac user, it's likely empty and never used, or overwhelmingly full of sports-news feeds and sticky-notes. Sometimes we see festive Christmas lights as well! Surely, there must be more to the Dashboard than this.

The dashboard was never meant for this! Well, hopefully it wasn't.

We could move on with our lives and continue staring at our messy screens, but that's not in accordance to the Mactuts+ style! Dashboards are dying out so let's revive the scene by customizing our Widgets more than ever before.

To combat one aspect of this Widget-depression, we'll edit the "Stickies" Widget and make it our own. The edits are simple: modify the backgrounds of the sticky-notes so that we can have specific note colors (and labels) for specific purposes. For example, we'll have one sticky-note type for personal thoughts, one for a todo-lists, and possibly another for random notes. We'll also be adding a custom "Erase All" button to make clearing our notes faster.

Dashboards are dying out so let's revive the scene by customizing our Widgets more than ever before.

You're going to need some HTML, CSS, and JavaScript knowledge, but the process certainly isn't too advanced. Let's get started!

Step 1: Get the Widget Open

All widgets are located in the folder "/Library/Widgets". You can do a quick Comman+Shift+G to quickly access it. Because we'll be editing the Stickies Widget, find the widget file Stickies.wdgt and make a copy to your Desktop. This way we can edit the files without having to worry about permissions and saving-based troubles.

On your desktop, right-click and select Show Package Contents in order to open the widget as a folder rather than open it up in the Dashboard.

This will open up the widget as a folder, rather than in the Dashboard.

Now that we have the Widget's files open, let's take a look at the general structure of a Widget.

Step 2: Look at the Files

Dashboard widgets are relatively simple. They're small HTML setups with JavaScript sprinkled in to make them interactive. Because of this, the files included within each widget are straight-forward and easy to modify, especially when we just want to change simple things like the images. The Stickies Widget is a great example of this simplicity.

Be sure to have opened the widget through a right-click -> Show Package Contents. Don't open it and install it to your Dashboard.

In order to get an understanding of the workings of a Dashboard widget, let's look at each individual file and see what it's used for.

Info.plist

The structure of the Info.plist file may look familiar if you've looked at the preference files of your Mac or iOS device before.

The Info.plist file determines information about the Widget. It's central to the Widget as it includes the Bundle Name ("Stickies" here), the current version, the height and width of the widget, and more. However, because we're only editing widgets in this tutorial, we can ignore this file.

Version.plist

This file is generally the same as the last. It holds more information about the widget. It has the version number, build number, etc. It's not important for what we're doing.

Stickies.html

This is the real meat of the widget. Here we have the code that makes up what we see. As stated before, each widget is just an HTML page, so this is easily editable. If you open it, you'll find it very familiar if you've worked with websites before. (As a note, the "Stickies" in the file name changes based on the Widget, so this file does not always have the same name This is also true of the next two files.)

Stickies.css

Of course, with the HTML we'll want to style the content, so here's the CSS file to accompany it.

Stickies.js

The interactivity of the widget comes from JavaScript, and this is where all of it is held. We'll get to editing this as well later on!

Default.png & Default@2x.png

When any widget loads, these images are shown as placeholders until everything is loaded. It's the splash screen of the widget. (If you're wondering what the "@2x" means at the end, it's a bigger sized image for the Retina Display on newer screens.)

Icon.png & Icon@2x.png

When you're adding a widget to your Dashboard, the icons you can see and drag are these files. Again, the "@2x" is for Retina Displays.

Images Folder

Just like any website, all the images are compiled in one place for easy access.

The Stickies widget uses an "Images" folder to hold all of its images. You'll notice inside are all the backgrounds and icons that make up the widget.

Step 3: Edit the Images

The first and easiest thing we can do before stepping into the code is to edit the image files in order to change the appearance of the widget. In the case of the Stickies widget, and many other stock widgets, we can just drag and drop new images into the Widget folder in order to make changes. For example, if I wanted to change the Stickies icon, I could create new .png files and replace the old ones ("icon.png" and "icon@2x.png").

You can treat the widget just like a website. Here, I've edited the icon!

I've also now changed the yellow background image in the "Images" folder by adding a theme of "personal thoughts." I changed the colors and added an icon to the top-right to indicate the purpose of the note.

Just by replacing the first image with the second, we've edited the widget.

Now if we install the new Widget, we'll instantly see the edits and our yellow notes will now have the "personal thoughts" theme. Let's change one more note and this time turn it into a todo list.

Another small change can make a widget much more personal and appealing.

Editing the images is a great way to add stylish flair to your widgets. It's quick and simple to do, and if that's all you'd like to do, then you can skip ahead to Step 5 to install the newly modified widget. Otherwise, let's keep working at it.

Step 4: Edit the Code

Now it's time to add some true functionality! This is where the HTML/CSS/JavaScript knowledge comes in handy because every widget is built with just that. We won't be going too far in-depth into editing the code, but we'll be working with all three files to get you acquainted. As I stated before, we'll be working to add another small icon to the bottom-left that functions as an "erase all" button.

To the humble web developer, this feels right at home.

The HTML File

In order to add the new button, we'll need to add another #eraseButton div right before the #infoButton div (line 21). Right now this is just an empty div with an image inside, but we'll style it in order to make it look like an actual button soon. The img is a simple 12px by 12px "x" icon that I've placed in the "Images" folder.

1

	<div id="eraseButton">		<img src="Images/x.png">	</div>

The CSS File

Now in order to give the erase button styling, let's turn to the Stickies.css file and add some basic location and size information before the #infoButton selectors. Let's also give it a little more style by increasing the opacity when hovered over.

1

#eraseButton {	opacity: 0.5;	position:absolute;	top: 166px;	left: 15px;	width:13px;	height:13px;}	#eraseButton:hover {		opacity: 1;	}

The JS File

If you look at the Stickies.js file, you'll realize it's very well documented and written thanks to Apple. This makes it easy for us to work with it.

The JavaScript code to make the erase button work is a very simple function that just sets the content of the textbox to nothing. Add this code anywhere in the Stickies.js, preferably where it fits with other functions. I put it after the textToHTML function.

1

function eraseAll() {	mydiv.innerHTML = "";}

In order to call the JavaScript code, let's add an onclick event to the #eraseButton in the Stickies.html file.

1

	<div id="eraseButton" onclick="eraseAll();">		<img src="Images/x.png">	</div>

And the button is done! It's a very simple example, but it also shows the extendability of widgets like these because of their simplicity

Step 5: Install the New Widget

If you ever want to test out your widget as you make changes, there are two options: open up the .html file in your browser like a website, or install the widget and test it out in the Dashboard. The first is faster for development, while the second provides a true Dashboard experience.

We've changed the icon, the backgrounds, and added a new function!

Installing a widget is very simple as well. All it takes is a double click on a widget and a "yes" to the install prompt. Be sure that before you install your new widget, you save a copy of your edited version. This is because as you install it, the file will be moved to "~/Library/Widgets". Also note that when we install the new Stickies Widget, it will overwrite the last as it has the same name.

Just as we wanted, the new button works and our new backgrounds work.

Editing the widget seemed daunting at first, but its simplicity allowed us to make changes easily. We've finished editing our Stickies Widget, and hopefully gave the Dashboard world a small rumble. If we wanted, we could now continue to create more backgrounds and add more functions to satisfy our needs.

More Hacking and Fiddling

We've really only gotten ankle-deep into the things we can do by modifying our Dashboard widgets. This is indeed just a primer to the Widget-hacking world, and what you can do will be based on your ability to manipulate photos and work with the code. You know how to make the changes now, but what comes next is to decide what changes you want to make.

Perhaps you'd like to add a clock to your Weather widget or perhaps you'd want to add a custom skin to the Clock widget. Maybe you'd even like to make a dashboard widget of your own! (Apple has great documentation to guide you on that path.) Whatever you choose though, be sure to let us know in the comments about the great things you modify and create!