Developing Sidebar Gadgets – Part I

So this is my first in the series of promised tips on developing Windows Vista Sidebar Gadgets. I am not sure how many of these there will be, but when I feel I have said enough or when those watching my site beg me to stop – I will.

Now, lets get started, shall we…

So, there is one HUGE reason I got involved in making gadgets and that was because of an internal contest at Microsoft. I had occasionally mentioned a gadget idea I had with friends and co-workers; but when a co-worker both informed me of the contest and assured me that my gadget idea was a winner, The Magic Folder was born. Alas I was three months late into the contest, but out of over a hundred entries I still managed to finished third place. For that I must thank the community of users who have downloaded my gadget: Thank you!

But now that the contest is over – I am hooked. But if you were like me and are just getting started you are probably finding that making a gadget is not nearly as easy as talking about it. There were several lessons I learned and in this post, I will share five (5) tips with you.

Tip #1

Get familiar with JavaScript, HTML/XHMTL/XML, CSS, and DHTML. You do not need to be an expert, just known enough to get around and use the Internet to search for what you do not know.

Because JavaScript is the language gadgets are written in it is pretty important to know it’s syntax. If you are familiar with JAVA, C++, PHP, C, C# type languages, you should be as happy as a pig in mud. Here is a great course on JavaScript. There is so much to cover in this area that I can only assume you have some basic understanding in these areas already.

Tip #2

Quickly get a basic understanding of how to create a SideBar gadget:

• Understand the folder structure – I may cover what I use in a future post.
• Understand the files that are required.
• Understand the information you need in the files.
• Get to know the System.Gadget namespace (some links below will get you started).
• Play with the gadgets you have and get a really good feel for how they behave, and then look at their source code.

There are tons of tutorials out there and example files. Focus on just getting something to work even if it only has text in it. Taking baby steps are best and this is what I did – each lesson builds on the next… Here are some links to get you started:

• MSDN basic tutorial: http://msdn2.microsoft.com/en-us/library/ms723694.aspx
• A bit more sophisticated Drive Information gadget: http://geekswithblogs.net/steveclements/articles/106819.aspx
• More information on setting up gadget parts and why: http://www.microsoft.com/technet/scriptcenter/topics/vista/gadgets-pt1.mspx
• And the somewhat lame "official" documentation: http://msdn2.microsoft.com/en-us/library/ms723683.aspx
• These rules will make more sense as you go along but there is good information in here: http://blogs.imason.com/jim.schwartz/archive/2007/03/20/10782.aspx
• If you have Visual Studio 2005 you can install a gadget template: Download here.
• Otherwise you need to create a file structure yourself and if you do not have Visual Studio at all, you can download it for free from here. Get to know the interface because it makes programming in JavaScript so much easier.

Finally, you can look "inside" other gadgets to see how things are done. They are plain text files so have a look (but be careful not to copy and then post the work around as your own because it can get nasty – and fast). The files are located here:

• For gadgets installed from the web: c:\users\<your name>\AppData\Local\Microsoft\Windows Sidebar\Gadgets
• For default gadgets: c:\Program Files\Windows SideBar\Gadgets

NOTE: When developing a gadget I find it a lot easier to work with it when it is placed in the default gadgets folder in the Program Files location. The reason is that when your gadget is located there, Vista SideBar will detect it and add it to the Gadget Gallery Dialog so you can easily load it, test something, then unload it again.

Tip #3

Since most gadgets use some type of web service or web page as a service from which to feed you information, you will need to learn how to use AJAX via the XMLHTTP object or a nifty little library called Prototype.js (which actually encapsulates the function of XMLHTTP and adds a lot of additional and useful tools). For now, I will leave you with some links, but in future tips I will try to include some sample code. So to get the Prototype.js library go here. Here is some very simple code to start you off:

<html>
<head>
<script src="prototype.js" type="text/javascript"></script>
<script type="text/javascript">
function init()
{
    var myAjax = new Ajax.Request(
    ‘http://checkip.dyndns.org/’,
    {
        method: ‘get’,
        onComplete: parseResponse,
        asynchronous: false
    });
}
function parseResponse(o)
{
    ip.innerText=o.responseText;
}
</script>
</head>
<body onload="init()">
    <span id="ip"></span>
</body>
</html>

Download the prototype.js file to your desktop, copy above text, place it in a text file on your desktop and rename it to text.html and save it. Double-click on it. It isn’t pretty, but it should help you get the point.

Anyway, this goes to the following page: http://checkip.dyndns.org/. It grabs the information from that page and places it your page in a specific control, in this case the SPAN with the ID of "ip." 

NOTE: The code above is using the Prototype.js library to get information and load it on your page. If you know anything about XMLHTTP you may find Prototype.js methods easier. However, here is a link that does the same as above, but this time using XMLHTTP (no need to add the Prototype.js library file).

Tip #4

You probably want to get proficient at creating graphics assets for your gadgets. No matter how well your gadget works in its guts or how eloquent your JavaScript code looks, your gadget is CRAP if it does not look pretty. Anyone who downloaded the very first version of The Magic Folder will understand what I mean. It was very functional but looked like doo-doo.

If your Gadget is not pretty and does not act snazzy it will get pulled off the SideBar, no matter how useful it is. So, to create graphics I actually use PowerPoint 2007. It is very easy to draw out the shapes, change the colors and formats of the shapes, group them, import pictures, crop and manipulate objects. Here are some PowerPoint tutorials/training courses.

Tip #5

Once I have the graphics the way I like them, I animate them with DHTL/JavaScript like this:

<img src="button.png"
     onmouseover="this.src=’hover.png’" 
     onmouseout="this.src=’button.png’" 
     onclick="alert(‘hello world’)" />

So what does this do? Well, when you mouse over the image it changes and when you click it, you get a message. Place the following sample code in Notepad and save it to the desktop as Test.html, then double-click on it to load it:

<html>
<body>
    <span id="link"
          onmouseover="link.style.fontWeight=’bold’"
          onmouseout="link.style.fontWeight=’normal’"
          onclick="window.alert(‘Your using DHTML!’)">
    Hover Over and Click Me
    </span>
</body>
</html>

As you hover over the text on the page it will become bold and as you hover away it returns to normal. When you click it you get a message box.

NOTE: The window.alert() command DOES NOT work in gadgets. I actually love using message boxes to sometimes help me debug something that is not working. However, the functionality (while it works in the browser) it has been stripped from gadgets completely. There is a workaround (albeit a little involved). I will cover it in a future tip.

In closing…

So, hopefully, with the tips above you have not damaged your computer too much.  The final tip I will give you for today is to be patient. Be patient with yourself, be patient with your gadget, do not expect to be an expert Gadget developer overnight. I have been programming since I was 11 years old and JavaScript came naturally to me, but Gadgets still took me time. And if you are already an expert programmer, there are several gotchas to watch out for. The rules link I proved above should point out a few. However, I plan to cover some of these in more detail later – and some workarounds to them.

/\/\/\/\/\/\/\/\/\/\/\

In closing, let me know what you think. Should I continue this series? If enough people like it, I might put together one each week. Please leave comments and let me know if you find this helpful.