Introduction

Since version 4.0, Yahoo Widget Engine (YWE) has supported a "Widget Dock", or side bar, with an icon for each widget you are currently running. The dock icon displays an icon that should represent your widget; a sort of visual summary of its function. Although YWE will assign a default icon to any widget that doesn't have an included dock icon, a great way to make you widget look more polished is to add a dock. Unfortunately, Yahoo does not offer a comprehesive tutorial to create a dock for your widget. I wrote this tutorial after spending several hours figuring everything out.

The first part of this tutorial will go over making a simple dock icon with pictures and text. All of the code and files mentioned in this tutorial are available for download at the bottom of the page. You are free to use this code for your own widgets.

Part 1: A Simple Dock Icon

Step 1: Create a dock.xml file

As you can see, in this example we create a background image and a piece of text. Syntax is very similar (but not identical) to widget XML. Some of the advanced options (opacity) don't seem to work, while others do (rotation). zOrder also does not seem to work. The best way to get around this is to create objects in the order they are displayed (i.e. background defined first, then next layer, and so on...)

Notice that each image and text has an "id" tag, which is similar to a name. This ID is what the widget uses to identify each element of a dock. Make sure that every image and text element that you may want to update while the widget is running has a unique ID.

Your background image should be about 75 pixels wide by 70 pixels tall. The widget engine adds the glass effect on top of your image automatically.

Step 2: Loading the dock into your widget

We now have a DESCRIPTION of the dock in the dock.xml file, we need to use javascript to create a dock icon based on that description from the widget file. In your widget file, under the <action trigger="onLoad"> tag, we need to insert some code to tell the widget to open the dock.xml file, and use the information inside of it to create a dock icon.

This first line of this code reads the dock.xml file. The second line takes the information and sets it as your dock icon. You will need to re-run this command every time you want to update your dock.

At this point, your dock is done if you want a static dock. If you want to update your dock, read on.

Part 2: Creating a Dynamic Dock

A static dock is enough for some widgets, but for other widgets, you may want to show information on the dock. For instance, in the weather widget, it makes sense to show the current temperature on the dock. In order to update the dock, we must use javascript to modify the dock icon properties, then tell YWE to refresh the dock icon.

Below is an example of an update function that can be called whenever you wish to update the dock (by timer, event, or whatever).

Modifying the dock is an exercise in Object Oriented Javascript (cool to play with, BTW). The dTitle variable is a text object. This means that it is a big variable with sub-variables for all of the attributes a "text" element can have. These include data, font, color, hOffset, vOffset, etc... To create a text object, you create a variable and then read into it a text object from the dock.xml file.

Now we will go through this code line by line to determine exactly what it does.

The first line creates a variable, dTitle, and makes it a text object. It then gets all the properties of the text object in the dock, with the ID "dockTitle". The new variable contains all the information about that text, including what it says, what font to use, the color, and its position.

Now we can change attributes of the text. In this line, and change the "data" attribute to be "new text". You can also change other attributes, for instance, changing the "vOffset" to be 5 works as well.

Finally, we tell the widget that it should refresh our dock icon with the new data.

Step 4: Images

We have covered how to deal with text objects. Dealing with images is very similar. You can create an image object, modify its properties using the setAttribute command, and then update the dock icon to reflect those changes.

You can also get an attribute from the dock using the "getAttribute()" command:

You cannot get data that you have not already implicitly defined. EXAMPLE: getAttribute("width") will not return anything unless you have already set a width, either in the xml file or with the setAttribute command.

Updating the dock is much more processor intensive than updating a widget. For this reason, you do NOT want to use animations or anything fancy on the dock. Update the dock no more than once every 2 seconds. Preferably, update it much less frequenly; as little as possible. This will keep the processor consumption down on your widget, and more people will use it!

Good luck with creating a dock icon! This is just a basic tutorial. I am sure that there is a lot more to learn about dock icons, but I wish a tutorial like this existed when I created my first dock icon!

Demo Widget and Code Download

Current Version: 1.0
Last Updated: January 24th, 2009

Attached is a zip file containing a simple demo widget. This widget acts as a clock. It shows the time in the dock, and updates it every 10 seconds. This code is free for you to use to base your own widgets on. I do appreciate if you credit Jozerworx on your "About" page. Please feel free to e-mail me and tell me what you think of this tutorial!