Using Vista Gadgets to Extend a Web Site to the Desktop

The architecture of a Windows Sidebar gadget is surprisingly simple, it’s a little browser window that you populate with a mini-site built on standard HTML, stuff we already know. Distribution is as simple as zipping the mini-site and changing the extension to .gadget, upon installation it gets extracted to C:\Users\<USERNAME>\appdata\local\microsoft\Windows Sidebar\Gadgets.

An easy way to test your gadget while developing is actually pointing Visual Studio to that directory during development.

The only requirement for a gadget is that it has the gadget.xml file in the root folder pointing out the actual HTML-file that will load upon startup. This XML file, which has a scheme defined by Microsoft, also includes meta data such as author and logo.

The height of your gadget is defined in the CSS class for the BODY-element, you only have 130 pixels for the width. The two main panes beside the gadget pane is the settings dialog and the flyout window, both are configured using JavaScript code and as everything else they load up plain HTML.

There are a lot of introductions to gadgets and Hello World-samples if you are interested so I’ll focus on describing in short terms how the EPiServer Feed Gadget works. The main functionality is toggling news items from an RSS feed, the items are clickable and opens up the web site in the flyout window. The design of the gadget was made to integrate with the current design of www.episerver.com. When you hover the gadget previous/forward-buttons are displayed to toggle news items manually.

The startup file of the gadget is gadget.html, as defined in gadget.xml, and has a height of 200 pixels which is not much to work with. The layout consists of a background image with rounded corners and the EPiServer logo at the bottom, all or most design is defined in the CSS file epi.css. The actual content is controlled using JavaScript-code that reads data from the Windows Feeds API which is built into Windows Vista and Internet Explorer 7. Some sample code that tries to find a feed based on URL stored in settings:

var rssFeedUrl = System.Gadget.Settings.read("rssFeedUrl");
var fm = new ActiveXObject("Microsoft.FeedsManager");
var feed = fm.GetFeedByUrl(rssFeedUrl);All user-defined settings are stored in the gadget settings store that exposes a simple to use API in JavaScript. The file used for the settings dialog is also defined in JavaScript and not the obvious configuration file gadget.xml. There is no built-in property configuration as you might be used to from other common applications, you just read and write values to a collection.

Configuring the file for the settings dialog looks like this:

The settings dialog is reached by clicking on the toolbox icon while hovering the gadget. Only the inner content in between title and buttons is your own HTML file settings.html, the rest is provided by Vista.
Here is a screen dump and startup code for the settings dialog:

Maybe not that obvious but the way you actually save changes is by listening to the event onSettingsClosing. Settings are read from the API and then put into the appropriate textboxes for the user interface. A typical initialization may look like this: 

System.Gadget.onSettingsClosing = SettingsClosing;
rssFeedUrl.value = System.Gadget.Settings.read(

"rssFeedUrl");
rssFeedName.value = System.Gadget.Settings.read(

"rssFeedName");And the save routine looks something like this:

if
(event.closeAction == event.Action.commit)
{
        System.Gadget.Settings.write("rssFeedName", rssFeedName.value);
        System.Gadget.Settings.write("rssFeedUrl", rssFeedUrl.value);
}To make sure the main gadget window detects changes in configuration(because it won’t be reloaded automatically even if looks like it does) we use a second event called onSettingsClosed and make sure we read any new changes from the settings API.

We move on to the next dialog which is the flyout that is displayed when the user clicks on the gadget, and again we need JavaScript code triggered from the onclick event to show the flyout. The size of the window is defined in the CSS-class for the body element, same as for the gadget window. In this case we do want to load a site external to our gadget so we add an IFRAME to our flyout window.

If you see the “Loading..”-message while waiting for the site to load you are seeing the HTML file we initialize the IFRAME with. Sample code to show the flyout:

System.Gadget.Flyout.file =

'flyout.htm';
System.Gadget.Flyout.show =

true;
System.Gadget.Flyout.onHide = HidingFlyout;And here is what it looks like when displayed, you may notice that we switch background for the gadget to get clean transition to the flyout. We use the onHide event to change backround back when closed.

That wraps up the walk-through of the EPiServer Feed gadget, feel free to modify it to integrate with your EPiServer site and download more samples from the Windows Live Gallery, just rename the files from .gadget to .zip and extract to get behind the scenes.

Further Reading

›› Windows RSS Platform API: http://msdn2.microsoft.com/en-us/library/ms684701.aspx
›› Windows SideBar API: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sidebar/sidebar/reference/refs.asp
›› Windows Live Gallery: http://gallery.live.com

Comments