We’ve heard from several OEMs who are having trouble pre-configuring Sidebar gadgets using the Sidebar unattend settings. We will explain in more detail how these settings work.

First, the Sidebar unattend settings are overrides for the default gadget settings. To determine what the default Sidebar gadget settings are, you can examine the “%programfiles%\Windows Sidebar\settings.ini” file. The default settings.ini file that shipped with Vista contains the following information (note that this can change between versions of Windows):

[Root]
SettingsVersion=00.00.00.01
SidebarShowState=Imploded
SidebarDockedPartsOrder=0x1,0x2,0x3,
Section0=1
Section1=2
Section2=3
[Section 1]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\Clock.gadget
PrivateSetting_Enabled=true
[Section 2]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget
PrivateSetting_Enabled=true
[Section 3]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget
PrivateSetting_Enabled=true
loadFirstTime=defaultGadget 

As you can see, the default settings indicate that Sidebar should be on by default and that the Clock, SlideShow and RSSFeeds gadgets are loaded.

The unattend.xml file can be used by OEMs and Corporations to override certain default properties of Windows components, including Sidebar, during Windows setup. Using the unattend.xml file, OEMs and Corporations my override the following Sidebar default settings:

• Whether Sidebar is on by default when Windows boots
• Whether Sidebar is visible by default when it is running
• Control up to five default gadgets  

Whether Sidebar starts when Windows boots is controlled by the “SidebarOnByDefault” unattend value. Whether Sidebar is visible by default when it runs is controlled by the “SidebarVisible” unattent setting. To have Sidebar not start by default when Windows load, you would add the following to your unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarOnByDefault>false</SidebarOnByDefault>
      </component>   
   </settings>
</unattend>

To have Sidebar start when Windows is booted but not be visible by default, you would add the following to your unattend.xml file:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>false</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
      </component>   
   </settings>
</unattend>

To use the Gadget settings, you need the information from the default settings.ini file. It’s also best to think of the Gadget settings as slots to hold up to five gadgets. Each slot (Gadget1,…, Gadget5) contains two pieces of information; the path of a preinstalled gadget and whether that gadget is enabled (true) or disabled (false). These five gadget slots override the settings in the default settings.ini file (which controls which gadgets start by default). Let’s consider a few examples.

Example 1. Suppose you want to have Clock, SlideShow, RSSFreeds and your own custom preinstalled Foo gadget to load in that order. Since Clock, SlideShow, and RSSFeeds are already the default gadgets that load (and in that order) for Vista, you could just add the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>   
   </settings>
</unattend>

However, it’s best to avoid dependencies on the default values in settings.ini as much as possible since those could change in later versions of the operating system. You could accomplish the same thing in a safer way by adding the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,true</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>   
   </settings>
</unattend>

Example 2: Now suppose you wanted only your Foo gadget to load. In this case, if you just add a Gadget4 setting for Foo.Gadget, you will still have SlideShow, Clock and RSS starting since the unattend settings are just overrides (nothing has overridden the first three slots). There is no way to explicitly remove a gadget entry using the unattend.xml file, but you can disable a default gadget. So, to have only Foo load by default, you could add the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.gadget,false</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,false</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,false</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>   
   </settings>
</unattend>

In the above case, we just disabled the three existing gadgets and added a new entry for Foo. Another way to accomplish that could be to replace the slot 1 gadget with Foo and disable the other two slots, like so:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\Foo.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,false</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,false</Gadget3>
      </component>   
   </settings>
</unattend>

Example 3: Finally, let’s say you want to have three instances of Clock start up and then two instance of SlideShow.

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\Clock.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget,true</Gadget4>
         <Gadget5>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget,true</Gadget5>
      </component>   
   </settings>
</unattend>

Note that configuration of a gadget (beyond whether it’s enabled or disabled) is not supported via the unattend.xml file at this time.

Here's a few tips for developers writing Sidebar gadgets that interact with Sideshow (the Windows Vista support for auxiliary displays):

Early versions of the Sidebar/Sideshow documentation incorrectly refers to the enabled method as a property. The following code snippet demonstrates how to determine in your gadget whether Sideshow is available using the enabled method:

var sideshowEnabled = System.Gadget.SideShow.enabled();
…
if (sideshowEnabled) {
….
}

Also note that the enabled method reports whether Sideshow is supported on that operating system, not whether a Sideshow device is currently available. Thus, it always reports “true” on Windows Vista.

The applicationEvent feature is not fully supported on the currently shipping version of Sidebar and should generally not be used.

You can update content using repeated calls to addText/addImage with the same id value. We recommend that you call remove before updating the content for a given id, otherwise the script may suffer from a memory leak.

Instead of this:

…
System.Gadget.SideShow.addText(100, originalContent);
….
System.Gadget.SideShow.addText(100, newContent);

 Do this:

….
System.Gadget.SideShow.addText(100, originalContent);
….
System.Gadget.SideShow.remove(100);
System.Gadget.SideShow.addText(100, newContent);
…

Thanks,
Paula Tomlinson

 One of my favorite new web technologies is now available for preview. I’d urge to you go check out the developer center and team blog.

Of course, since “WPF/E” is a technology designed to work in web pages, many of you are going to try it out inside gadgets. Very cool. Unfortunately, you’ll probably hit some roadblocks when attempting to render “WPF/E” content inside a Sidebar gadget.

External Files

Samples that access external files will not be able to access those files. This includes images referenced in the XAML and XAML files, even inside the gadget package.

This is not a security issue, but rather a problem with the way the “WPF/E” control resolves file paths and URLs. Unfortunately, there is no known workaround, such as placing the files on a remote server. Only XAML content embedded in the HTML files will load.

Making samples into gadgets

It is minor in comparison to the above issue, but most examples won’t have height and width set on the body. This is required for Sidebar gadgets, so be sure to add it.

Brian

The final RSS gadget, “Feed Headlines” is done and available with Windows Vista! This gadget is featured on the Vista Sidebar by default and allows users to see new headlines peripherally. We built the gadget using the Windows Feeds Platform, which greatly reduced the complexity of getting and storing of feed data so that we could focus more on the user experience.

Initially, the gadget was prototyped using an http request to handle the xml files from each feed, similar to other AJAX development. Designing and developing the prototype quickly revealed that managing feeds was going to be very consuming to develop due to how much code would need to be written for feed download, storage, and user management not to mention the bugs introduced due to the extra code.

We started prototyping a gadget to be a full-fledged feed aggregator for all types of syndicated formats. As part of this development process we took a look at the Internet Explorer 7 feed reading experience and realized that our experience with a Sidebar gadget had to interact with Vista’s new feed platform. We ended up building a gadget that essentially became a face to the feed platform. Because we chose to build the gadget on top of the feed platform the job became a lot less complex, and a more usable gadget emerged. It was more usable in that the user doesn’t need to maintain another RSS list specific to the “feed headlines” gadget and read/unread data is synchronized.

In hindsight, it becomes quite clear that managing feeds in one location accessible to all applications is “how feed management on the OS should work”. Sure you can be savy and have your opml list and import it to all your RSS apps, but I personally am just not that organized, and isn’t that a lot of the reason we use computers - to do our mundane tasks for us?

By choosing to build our gadget on top of the feed platform, we introduced a dependency on the feed platform. If it breaks we break. This is not a bad thing, because if it does break we know where things went wrong and can be fixed from one point instead of several.

In conclusion, I don’t believe this would be a viable gadget without the feed platform. As an independent feed aggregator, there is just too much set-up to ask of the user. Gadgets are quick glance mini-applications. I don’t believe users will want to spend a great deal of time interacting with them, and API’s like the feed platform will make gadgets extremely robust.

Notes on the gadget’s usage of the Feed Platform APIs:

The RSS gadget uses a number of the APIs from the feed platform in ways that may not be obvious on the surface. Helpfully, the feed platform exposes its APIs through a scriptable ActiveX object, so it was simple to access these APIs in a Sidebar gadget using JavaScript.

By default, the RSS gadget displays all feeds in the feed platform, including subfolders. Because the feeds can be organized into folders, it’s possible through the settings dialog to select an individual feed or a folder of feeds.

The gadget also displays only the unread items from the selected feeds, making it more relevant to the user as a gadget. Further, if the user opens a feed item from the gadget’s flyout that particular item will be marked as read.

-John Moscarillo, Sidebar Gadget Developer

I just saw this interesting exchange on an internal discussion list, and thought I'd pass it on:

From: A Microsoft Guy
Subject: Formatting date/time strings

Is there a good way to format a date/time string using the current system local?  The javascript function toLocaleString() only outputs the long date + time format.  I’m looking for a way to do short date, short time, and other formats.  Any tips/suggestions, other than just providing a format string that gets localized for a particular language (not the best solution, but better than nothing).

From: A Sidebar Guy
Subject: RE: Formatting date/time strings

Shawn Steele graciously provided us with some information on this and added it to his blog here:

http://blogs.msdn.com/shawnste/archive/2006/09/05/741871.aspx

Soon after I posted my persistent settings library, I received my first bug on it.  I'll discuss the bug a bit, but first things first - the bug is fixed, and the links updated; if you previously downloaded the library, please go ahead and get the updated version.

Details:

The symptom of the bug was that the following two consecutive calls:

getPersistentSetting( "setting", firstCallback );
getPersistentSetting( "setting", secondCallback );

Would result in two calls on the 'secondCallback' function.  The failure itself made it clear to me where the error was; and the location of the error suggested the fix.  I'm afraid I don't know enough about the intricacies of the javascript language to know exactly why it failed in the first place, though; perhaps one of my more knowledgable readers will chime in.

Here is the failing code:

window.setTimeout(function ()
{
    try
    {
        workItem.callback(returnValue);
    }
    catch (e)
    {
        persistentSettingLog("exception from callback: " + e.name + ": " + e.message);
    }
}, 0);

And here is the fixed version:

persistentSettingScheduleCallback(workItem.callback, returnValue);
function persistentSettingScheduleCallback(callback, returnValue)
{
    window.setTimeout(function ()
    {
        try
        {
            callback(returnValue);
        }
        catch (e)
        {
            persistentSettingLog("exception from callback: " + e.name + ": " + e.message);
        }
    }, 0);
}

In the RC1 release of Windows Vista, the Sidebar received a number of changes in the APIs that make up our object model. These APIs make building rich gadgets that interact with other Windows components, and the Sidebar itself, easy and familiar to HTML developers.

Some gadgets written for the Beta 2 release of Windows Vista may fail to function correctly on this newer build, but most gadgets that we have seen are not affected.

The changes we made can be summarized as follows:

• Small additions for Gadget user experience
• Better integration with Windows components
• Simplification and removal of several APIs

The following guide will help you as you examine the documentation for the Windows Vista Sidebar in RC1. For more information, please visit MSDN.

Gadget User Experience

System.Gadget.Settings.readString, writeString

We added these two methods in order to give developers more control over the way settings are stored. For instance, our note gadget uses these methods because a user that types in a long string of numbers, say, “2065551212”, probably doesn’t want to see “2.0 E9” returned because our type system believed it to be a long integer.

System.Gadget.document

To expose better communication between a gadget and its flyout we now expose the HTML document objects for both to the other. Two way communication was difficult prior to this change.

System.Gadget.visible, visibilityChanged

This property and event allow a gadget to suspend operations when a gadget goes off the screen. This assists gadgets in consuming as few system resources as possible.

Sidebar Graphics Library

• Background element/object
• Image object
• Text object

The new graphics library, exposed in HTML markup and to script, allows greater flexibility in designing gadgets with alpha transparency, manipulating images and placing text and images over transparent regions of the gadget.

Windows Component APIs

System.Contacts
A set of APIs allows a gadget to access the information from the Windows Contact data store.

System.Machine.CPUs
An improved set of APIs allows a gadget to access information and utilization data about the different CPUs on the computer.

System.Machine.PowerStatus
An improved set of APIs allows a gadget to detect information about the power supply, and to alter the behavior to use fewer resources if the machine is operating from battery power. Several APIs were removed or modified as part of this change.

System.MessageStore
A new set of APIs allows a gadget to inspect mail and other messages present  in Windows Mail.

System.Network.Wireless
A simplified set of APIs allows a gadget to detect information about the wireless connection state. Several more generic Networking APIs were removed as part of this change.

System.Time
A new set of APIs allows a gadget to display information formatted for the current, or other, time zones.

Removals and Simplifications

We made a number of changes to simplify the APIs and make the information more reliable. The following removed APIs typically are exposed in other places, such as WMI (Windows Management Instrumentation) or through the Shell and FileSystemObjects for scripting

System.Net.NetworkInterface
System.RecycleBin.percentFull
System.Sound

- Brian Teutsch