Developing Sidebar Gadgets – Part III

This is the third installment in the series. See the link list on the left side of my side home page to view the other entries in this series.

As I have developed sidebar gadgets I have found that time and time again that they make themselves MOST useful when pulling data from the web that you access quite often. Most of the common things you can think of are already taken, such as Stock quotes, News feeds, etc. So finding something new is not as common as trying to build a better what-ya-ma-call-it. So with that lets start off with the tips for this installment:

Tip #1

Do not create another search gadget and post it on Windows Live Gallery.  First, these are the easiest gadgets to create and there have to be over one-hundred of these things out there. All you do is add a text box and a button to an HTML page, maybe even make them pretty and then you have 3 lines of code:

function go()
{
    System.Shell.execute
         ("http://search.live.com/results.aspx?q="+
          txtBox.value)
}

I have looked at the source code of several of the "search" gadgets on Windows Live Gallery and many of them route your request through a secondary web site before they send your request to the desired search engine. Likely they are collecting your search data and your IP address for some monetary purpose – search demographics or something.

Regardless a search gadget simply removes a single step out of the search process – you enter a search term and press enter and it opens the browser for you – they really only look nice on the SideBar and do just a little more than take up space. I am not trying to deter you from creating a search gadget if that is truly what your heart desires – and it may even be a great starter gadget for a newcomer.I just suggest not posting it on Windows Live Gallery because there are already enough of them up there and most are welcomed with lots of ire by the community at large.

Tip #2

Let users know when you have posted an update to your gadget. Now there are two ways to do this, the way I currently use is to have a web service on an external web site that holds the location – this is more complex so lets save that for another day. However, I have long been looking for a more simple option to update based on the version posted on the Windows Live Gallery Site. The following code will work with the later:

function checkForUpdate()
{
    try {
        var url = LIVE_ITEM_URL;
        var myAjax = new Ajax.Request(
                                        url,
                                       {
                                        method: ‘post’,
                                        onComplete: parseResponse
                                     });
     } catch (ex) { /* DO NOTHING */ }
}

function parseResponse(originalRequest)
{
    var txt = new String(originalRequest.responseText);
    var startTxt = 0;
    var endTxt = 0;
    startTxt = txt.indexOf("<span
id=\"ctl00_ContentPlaceHolder1_LiveItemDetailInfo1_ltVersion\">",
startTxt);
    startTxt = txt.indexOf(">",startTxt) + 1;
    endTxt = txt.indexOf("</span>",startTxt);
    var sVer = txt.substring(startTxt, endTxt);
    if(sVer != System.Gadget.version)
    {
        // update the user in some way
    }
}

So here is what this does:

• LIVE_ITEM_URL can either be a global variable or you simply replace it with your item URL. It will look something like this:

  http://gallery.live.com/liveItemDetail.aspx?li=0ed6a06a-6782-41a7-b68c-2753fad412a5
  

• However, there is a catch 22 here. You will not have this URL until you have posted your item to the gallery and you cannot post your item to the gallery with an update routine unless you know the URL. As such here is what I suggest:
  • Place the item without an update routine on the gallery.
  • Once it is live, add the update routine and then repost it.
  • In the meantime, take the item offline through the gallery options until the second post is live.
• You need the Prototype library as per my previous tips to get the AJAX function. What this essentially is doing is loading the Windows Live Gallery page into a parser.
• Once the page is loaded the parseResponse function is called. This function then takes apart the HTML that is returned, looking for a specific tag and it parses the version from the HTML and compares it to the gadgets version. If they are not the same, then the user will get an update prompt of some form – as you desire.

Of course, this code can be refined in many way and some try/catch work can be done here, but the general purpose of this example is to get you started. My suggestion is to also have the update routine called when the gadget is first loaded and also set a window timeout for every 8 to 24 hours to check for updates. Something like this:

function checkForUpdateLoop()
{
    // check for update
    checkForUpdate();
    // loop once every 8-hours              
    window.setTimeout("checkForUpdateLoop();",28800000);
}

This code essentially loops every 8 hours and calls the checkForUpdate function as defined previously and then sets the timer to wait another 8 hours.

Tip #3

This is simply an item from my playbook and you can follow or not – your choice. But I have found it easiest and best to keep the source code for each HTML file in your gadget in a separate file. For example: main.html has main.js, flyout.html has flyout.js, settings.html has settings.js, etc. In addition, there are several times you find yourself calling similar or the same functions from each page. In this case I create a file called core.js in which gadget specific routines that are not specific to any one page are kept. Finally, I have one last file called helper.js that I sometimes include and this contains functions that are generic across all gadgets and are useful from project to project.

It can make debugging a problem a lot more simple when you think about each page having a separate file.

Tip #4

And this leads into a few of my favorite debug tips. Debug tips in general are few and far between in the Gadget world and it can be really hard to debug a gadget if you are not sure where to start. So, here is what I do:

1. Turn on all Internet Explorer Debugging options – regardless of your default browser, you need to do this in IE:
   • On the Tools menu, click Internet Options
   • Click the Advanced Tab.
   • Under the Browsing options, clear the checks from both:
     • Disable script debugging (Internet Explorer)
     • Disable script debugging (Other)
   • This way you will get a script error each time there is a serious issue with your code. Plus the error contains a line number which refers to the line in the given HTML or JS file where the error occurred.
2. Use Visual Studio to edit your files. There is a free version of Visual Studio.NET Express Edition that you should download. You get context sensitive help – inline – you get real-time error checking of both the HTML and the JavaScript, and you also get a good interface for navigating your project. Finally, and this where it helps for debugging, you can turn on line numbers: Tools, Options, Text Editor, All Languages (or the specific language you use like C#), check the option for Line Numbers.
3. Keep your gadget in the Global Gadget location while you are debugging it: c:\Program Files\Windows SideBar\Gadgets. You should also create a shortcut to this folder on your desktop. Otherwise if your VS project is in My Documents you have to zip it, rename the extension, then double-click on it to register it and get it loaded in the SideBar to test it. If it is in the global location you simply need to load/unload it through the interface to reload and get the changes. This by itself makes debugging 1000% faster.
4. Use comments in your code. I know, I know… you wrote the code, you know what it is doing, right, right…

Tip #5

Use CSS (style sheets) as much as possible and try to standardize the styles you want early on and stick with them. You can specify page size, shapes size, object positions, z-order, graphics, font styles, borders and much more with style sheets. The other reason they are important is because all you have to do in your code is change the className of an HTML element and it will change its style on the fly. I will cover this in more detail in a future posting, but for now, if you are not familiar with style sheets and how they are useful, read this article.

<><><><><><><><><><><>

So this concludes the third installment. I have received good feedback on my previous postings but I really do what to hear from you. If you like this series, please chime in and let me know what you are thinking. What should I do to improve it…