Widgetbox

Widgetbox allows you to configure a widget on behalf of a user and pass the configured widget on to Widgetbox for installation onto the user’s site.

This is designed to support several situations:

• External configuration forms. Many developers have a configuration form for their widget that lives on their own website. You can now let users configure a widget on your site and pass the configured widget to Widgetbox.
• Preconfigured widgets. Say you have a widget that displays RSS feeds. You might want to create a link to this widget that preconfigures it to the URL to a specific feed. This is would be useful if you have a blog and want your visitors to be able to get a widget containing your blog’s entries. Here’s a diagram of this:
  

How does this work? Each widget has a unique URL, known as a Widget URL, to its home page on Widgetbox. A Widget URL looks like this:

This Widget URL can include information that preconfigures the widget.

Every configuration parameter of every widget can be controlled in this way. Here are some other examples of configuration parameters you might want to preconfigure via the Widget URL:

• Link to a news or image widget, prepopulating its “search_terms” parameter.
• Link to an IM presence widget, prepopulating its “userID” parameter.
• Link to an eBay widget, prepopulating its “sellerID” parameter.

How To Include Configuration in a Widget URL

A widget’s configuration parameters can be passed into the widget’s Widget URL via the query string. For example, the following URL configures a widget named “my-widget-name”. It supplies the value “myValue” to the configuration parameter “myParameter”.

Parameter	Meaning
_wbx_external=1	Tells the system that the link is carrying external configuration. If left off, the system won’t process the external configuration. “1″ is the only valid value.
_wbx_autosubscribe=true	Automatically subscribe the user to the widget, or drop them on the widget’s gallery page so they can further configure it. To not autosubscribe, leave parameter off or turn to “true”.
myParameter	Parameter “myParameter” of the widget. Any widget parameters not included will default to the widget’s normal default value.
widget.width	Width of widget in pixels. Optional.
widget.height	Height of widget in pixels. Optional.
widget.name	Name of the subscription to the widget. For example, if the default name is “RSS Widget”, you might want to override it to “Wall Street Journal RSS Feed”. Optional.

Supports GETs or POSTs. These parameters can be part of a regular link, a GET form, or a POST form.

Example 1: Hand Code Your Links

In the examples below, each item is a RSS feed, and has a chiclet. Each chiclet links to this RSS widget on Widgetbox. Each chiclet passes in a different RSS feed URL, so the RSS widget is tuned to different content.

Example 2: Form Based Links

If your website has a form that configures the widget, you can use Javascript to get your form’s elements and pass them to Widgetbox. For example, each of the chiclets below uses Javascript to get specific form elements. The Widgetbox developer console has a tool for building these types of Javascript chiclets automatically.