clearspring - the widget network.

This guide covers the Clearspring configuration mechanism, and its advantages in greater detail.  If you're looking for an in-depth understanding of the mechanism, and it's advantages, it's worth a read. 

The Basics of Widget Configuration

All but the most basic widgets leverage some kind of configuration.  That is, they need some kind of parameters to control their behavior.  This could be anything -- something simple like a color to use to display a UI component, or an RSS feed to gather information from a server, or even preferences specific to an individual viewer of the widget.  Usually, these parameters are a combination of things you as the widget developer care about and don't really want users to know about, and some things the user needs to deal with, either explicitly or with your help.  This is widget configuration at its simplest -- somehow you've got to get parameters into the widget, and then offer a way for end users to change the ones that you want them to be able to. 

Some Common Techniques, and their Problems

With most widgets, and even some widget platforms, the parameters are written into the code that a user includes in their site or page.  In other words, if you have a widget that shows a particular user's music listening history, you might have the username for the music tracking service in the code that you embed.  For javascript, it might be written into the javascript or passed as a URL argument, and for Flash these are often passed as FlashVars.  So you might have a Flash widget that has its parameters set in an embed tag, for use in Myspace.

With these techniques, the code you generate to include a widget somewhere is basically hard-coded  to a certain set of parameters -- parameters which can't change without actually changing the embedded code.  If you are a widget publisher, this means you can't modify the appearance or other behavior of the widget once it's put somewhere without building in a complex back-end infrastructure and maintaining it yourself.  It also limits the ability for users to share widgets between each other, as the new copies will not be configurable for the new user.

Other common techniques include using cookies to store a user's preferences, but those are of course only available after the widget is initially displayed (and it sets its cookies), and are only available to that one individual viewer of the widget.

The Clearspring Solution

When you distribute your widgets through the Clearspring platform, two things help you eliminate all of these problems.  First, our Widget ID/Placement ID (WID/PID) scheme, which identifies not only each widget, but also each instance of each widget.  When you upload your widget on our platform, it gets a unique Widget ID.  There's also, however, a unique Placement ID every time your widget is placed somewhere (like on a user's social network page).  This means Clearspring knows about the difference between different instances of your widget on the Interwebs.  Building on this, the second thing that really brings this together is that your configuration parameters are hierarchically assigned to the Placement ID, and managed completely dynamically by our servers.  So, if you have a widget that accepts some parameters, here's how it goes:

1. You upload the widget to our system and tell us what parameters it takes, what types they are, and whether they can be edited by a user or not.
2. When someone gets the code to put your widget somewhere, we associate a unique id to that placement.
   
3. The code that lives out in the wild -- on a social network or startpage -- doesn't contain any parameters at all.  Instead, our server dynamically generates and delivers the right parameters to the widget using the WID/PID, when it is viewed by the user (when the page that holds it is loaded by someone).
   
4. If someone wants to get their own instance of your widget, the widget platform will ask them to specify any needed user-specific parameters (ones you mark as user-editable and required) when they try to grab it, then store those new values specific to that new user as a new placement (tied to the original placement, but more on that later).  Parameters that are not specific to the placement -- parameters you might think of as "global" -- are kept at the WID level. 
5. The process then continues forever like this, with each widget placement getting its own set of values for placement-specific parameters, none of which are ever included in any code embedded by an end user.

Why does this matter?  Well, it gives you as a widget publisher a number of significant advantages:

• Widget code is not brittle: One of the tricky problems with distributing widgets is that you are basically handing out code for people to use, so changing that code means handing it out again.  With Clearspring, the code contains no configuration at all, and therefore making changes doesn't require you to hand it out again.  As a developer, you can even do things like change the names of parameters if you want, without breaking anything.
  
• You can change widget configuration dynamically: This is the big one.  You can make your widget do something completely different simply by modifying values of configuration parameters using the Widget Console.  When you do this, the changes will apply for every single placement, as long as there is not a value overridden for that placement by either the user or by a custom overridden URL.  That is, unless you explicitly set up your parameters such that specific values are required for each individual user placement, changes will apply for every single instance of your widget out in the wild.  This is great for things like temporary promotional content, for example.
• You can allow end users to reconfigure widgets: By storing and managing configuration in this way, we can allow end users to customize your widgets to their heart's content (within boundaries set by you of course), without you ever having to do anything as a developer.  The system will simply track this new configuration with this particular placement, and you're good.

There are some other advantages, like the fact that you can override parameters by specifying URL arguments to our widget server, and getting a small amount of parameter security by not exposing them at all.  There's also a lot of fancy stuff you can do with this whole system that we'll get to over time, especially once we start talking about analytics, but this is the basic idea.  

Note: One very important thing to keep in mind is that parameters that are set at the placement level per user -- parameters that are set by a user from within the get and share menu -- are now locked down for that placement.  The user can change these values again, the server is no longer using global values for them, so changes you make in the widget console to those default values will not be used.