If you’re a Flash Developer and you’ve started checking out our SDK, you may have stumbled across parameters in the documentation and you may have wondered about the bigger picture.
Widget Parameters, in the context of the SpringWidgets Platform, are values for variables inside your widget that are defined during initialization of your widget. They work very similar to the way query string variables are used by back-end scripts to determine the content on web pages. In fact, Flash uses query string variables also, to pass in initial variables into the _root of a Flash file; they can be found either appended to the .swf URL or defined on their own in the flashvars attribute.
There are some differences/enhancements that parameters in the SpringWidgets Platform offer. They are not stored in the _root, but rather are accessed through the API using two methods: Widget.getParameter(); and Widget.setParameter(object); - these two methods work identically on both the desktop and the Web. Values of parameters can change during the lifetime of a widget instance. Most importantly, the parameters are packed into a single object with developer defined properties.
The parameters can be used to determine:
- content (e.g. by passing in data ids or usernames)
- initial state of the widget (e.g. by defining the tab that should be selected initially)
- skins (e.g. by passing in a Jpeg URL)
- anything else your widget needs
Situations in which your widget could receive parameters:
- When a Widget embedded on a Webpage is loaded.
- When a Widget is popped from a webpage (Note: the current parameter values are passed down to the desktop, not the initial values. This means your code can change the parameters as the user interacts with the widget on the web and can pass those changes down to the desktop when popped, rather than loosing them, in which case the user would have to resubmit the same data again on the desktop)
- When a widget, that was left open when the application was closed, is launched when TheSpringBox is launched. TheSpringBox remembers widget parameters on shutdown and passes the back in when it “revives” the widget
Situation in which your code should update parameters are any events that occur in your widget that allow you to define the state in which your widget is in, e.g. current tab.
Once you have defined the parameters that your widget will receive, you can test your widget by using the Web Simulator that comes with our SDK. For testing purposes it allows you to declare the parameters that are passed into the widget. The panel will also give you insight on the current values of your parameters; this is helpful should your code alter them while the widget is running or is interacted with.
When you upload your widget to the SpringWidgets site (availability TBD) you will also find an interface with which you will be able to define your parameters, their respective data types and default values. This will define the customization form on your widget’s Share It! page, that user can use to mold your widget to their needs.
Example:
Let us assume we are creating a simple Stock Ticker widget that has 2 tabs; one for a quote and one for a chart. Users wanting to place this widget on there site may want to control two aspects: (1) the stock to be displayed, (2) the default tab.
Let us define 2 parameters: ticker and tab. We would access these values in an initialization function in our widget:
function initialization()
{
var param = Widget.getParameter();
if(param.ticker != undefined)
{
// can be any ticker symbol e.g. “GOOG”
setTicker(param.ticker);
}
// can either be “quote” or “chart”
setTab(param.tab);
}
You may wish you constantly update the value of the tab parameter every time the user changes the tab. This way, when the user changes the tab on the web and pops the widget, it will pop to the correct tab. Also, this allows you to maintain the state of a widget’s instance when the application restarts.
btnTabChart.onRelease = function()
{
setTab(“chart”);
// read the current parameter object
// and change only the tab property
var param = Widget.getParameter();
param.tab = “chart”;
// write it back
Widget.setParameter(param);
};
