Here is a question that seems to pop up with some regularity on the sidebar newsgroup: "Why doesn't the weather gadget remember where I live, if I close it and then add it again to my sidebar?"

The answer is that every time you add the weather gadget to the sidebar, you are creating a new 'instance' of the gadget; and every instance has its own associated location.  So the newly-added weather gadget has settings that are completely distinct from the settings on the one you closed.  This makes sense when you start to think about having three or five weather gadgets running at the same time - they should each be able to show the weather at a different location.

Having said that, you may choose to make a different design choice in your gadgets.  Unfortunately, the sidebar does not offer a built-in mechanism for sharing settings between gadget instances.  When asked how to do this by other gadget developers, my first response was: "you can use a shared file to share settings between gadget instances."

To make life easier for everyone, I decided to write a javascript library that encapsulated that work, and exposed a simple API for reading and writing shared settings.  In the process of writing the library, I discovered that just saying "use a shared file" vastly oversimplifies the effort involved.  *grin*

I've uploaded the results to the 'Sandbox' section of the Channel 9 site:

Persistent Settings ZIP Archive

The ZIP archive contains a JS file that implements the APIs, and a README.TXT file describing the APIs.  You can include the file in your gadget HTML as follows:

<script src="persistentSettings.js" language="javascript"></script>

I'm including the contents of the README.TXT file below, for ease of reference:

PersistentSettings.js - A Persistent Setting API For Sidebar Gadgets

These APIs allow multiple instances of the same gadget type to share a set of common settings. It will also maintain those settings even when all instances of the gadget are shut down. It will not maintain the settings if the gadget is uninstalled from the gadget gallery window, and then reinstalled.

There are two functions:

setPersistentSetting( name, value [, callback ] )

This function stores the specified name/value pair in the common settings.

Note: You are not guaranteed that your setting is stored until that callback function is called. If you do not specify the optional callback, you must not assume the setting has been written when the function call returns; it has not.

Example:

setPersistentSetting( "CDName", "Bat out of Hell", setCallback );
function setCallback()
{
    document.body.innerText = "CDName set!";
}

getPersistentSetting( name, callback )

This function gets the value associated with the specified name from the common settings. If the name is not currently present in the shared settings, null is returned.

Note: you must specify a callback function in order to obtain the result of your setting query.

Example:

getPersistentSetting( "CDName", getCallback );
function getCallback( value )
{
    document.body.innerText = "CDName: " + value;
}

If you have any questions, suggestions or bugs related to these APIs,please contact Bruce.Williams@microsoft.com. I hope you find this useful!

-Bruce