Create your First Yahoo! Widget !

[abesh]

So you've been browsed through the SDN Widgets Forum and Wiki and now want to create your first Yahoo! Widget ?
Fear not, cause help is at hand !
This blog will take you step by step into what goes into building your very first Widget.

Part - I : The Basics

Tools of Trade

*Yahoo! Widgets Engine : *The first and the formost thing you will need is the Yahoo! Widget Engine which will interpret the widget code you write and display your widget.

1. 
   

*Text Editor : *On Windows, Notepad, but PSPad , a powerful free text editor is what I use.

1. 
   

*Image Editor : *Though there are a lot of image editors lying around, GIMP (GNU Image Manipulation) , for Windows, is what I use. Beware though, GIMP has an unconventional user interface which may lead to steeper learning curves.

1. 
   

*The Widget Converter Widget : *he use of this widget is twofold. First of all it breaks down flat widgets into its constituent folder structures and files. Secondly it can pack your widget code along with it's folders into flat widgets. So this is something you surely won't want to miss.

1. 
   

*Yahoo! Widget Engine Reference Manual *and other goodies which include a Widget Creation tutorial from Yahoo! can be grabbed from here .

1. 
   

Last but definitely not the least, a little knowledge of XML and Javascript
Widget Formats

1. 
   

*ZIP Widgets : * The ZIP format of packing widgets essentially involves creating a ZIP archive of your widget files and then renaming them with a .widget extension. Since the widget engine has to unpack the files as runtime, ZIP widgets are generally slower to load up.

1. 
   

*Flat File Widgets : * The Flat File widgets are essentially packed using the The Widget Converter Widget mentioned above. They launch really fast and can be signed to verify the authors identity.

1. 
   
2. *Mac format or HTML Widgets : * They are widget formats popularly followed on the MAC platform and are currently losing grounds to Flattened Widgets
3. 
   

Widget Files for Windows by their extension

1. 
   

*.kon : *This is the main file in a widget which is searched for when a user launches a widget. It contains code both in XML and javascript that generates the layout and visualisation of the widget as well as it's functionality. Sometimes, for more complex widgets, javascript code can be isolated and stored in a separate file with a .js extension. However this is not mandatory and the whole code of the widget can be contained in the .kon file itself.

1. 
   

*.js : * As mentioned above, these are javascript files and if present, contain generic javascript code which can be referenced from the .kon files. There may be none or more than one .js files present.

1. 
   
2. *.png, .jpg : *These are image files which are needed to generate the different visualizations for the widget.
3. 
   

Part - II : Getting your hands dirty

CPUMon : The CPU Usage Monitoring Widget
The First few steps....

1. 
   

Create a Folder for storing the contents of your widget. Call it CPUMon.

1. 
   

Inside CPUMon, create one more folder called images and store the background.png file in it. We'll use this image to form the background of our widget. Download it from *here*.

1. 
   

Create a file called CPUMon.kon inside the CPUMon folder and open it with PSPad to edit it.

1. 
   

In PSPad, click on View -> Change Syntax and select XML from the list.</li>
</ul>
The first piece of code that goes into the CPUMon.kon file is :
<?xml version="1.0" encoding="UTF-8"?>
This line tells the Yahoo ! Widget Engine the XML specification version and what encoding it uses.
Next we’ll put in the Widget Tags :
*
*
The widget tag tells the Widget Engine details like the version of the widget, the minimum version of the Widget Engine required etc. The closing widget tag indicates that end of the widget code has been reached. All pieces of code should go between the <widget></widget> tags.
We’ll now define a something called a Window :
The <window> is a Mandatory tag which defines how large to draw the Widget. Anything outside the window bounds will be cut off.
*

The following lines of code displays the image background.png and sets the title for the Widget.
*
stands for the Vertical Offset and hOffset, for the Horizontal Offset.
These Offsets determine how far from the top and left borders of the window these objects will be drawn.
Now let us have placeholders for texts displaying the CPU Activity and the Idle CPU Cycles.
Experiment with the hOffset and the vOffset values to determine how they affect the placement of the Text elements on the background image background.png.
Save your CPUMon.kon file and double click on it to load up the widget. The Widget should look like this :

Close your widget and get back to business ! We'll have enough time to ogle over it. In the meantime let's add some code to display the User and Idle CPU Activity !
The very next thing that we need to know are Triggers. A trigger is somewhat synonymous to that of a Gun. When it fires, things happen. In other words you define a trigger on an event and set it to fire a particular piece of code when that event occurs. Events can occur when when the Widget is first loaded, when it is focused, after the computer is awaken from sleep, when its preferences are changed, and more.
The syntax of a trigger is : <action trigger="(Some event here)"&gt
We'll initialise the CPU Activity reading when the widget loads, so we'll use the onload event to trigger this particular piece of code. But how do we actually get the CPU Activity ? Do we have to write complex code for that ? Fear not, because the Yahoo! Widget Engine has something called the system object which provides us with methods to access system details. Cool, ain't it ?
We can get the Active & Idle CPU cycles by referencing the following system properties by javascript :

1. 
   

system.cpu.activity

1. 
   

system.cpu.idle
*
Load up your widget to see that it actually looks somewhat like this :

But why is the data static ? Is the CPU Activity not ever changing ?
Apparently our Widget misses an important feature : Auto Update of Data.
For this purpose we’ll use something called a Timer. A timer is basically a ticker which ticks at regular interval and at each tick you can cause it to trigger a scpecific block of code !
The Following code should do the trick.
*
Now, if you have have already created your first Yahoo! Widget!, go ahead and Debug and Publish your First Yahoo! Widget!