Tutorials: Using SpringWidget Parameters

Using SpringWidget Parameters

What are parameters and how are they used?

SpringWidget parameters are values that can be dynamically passed into your widget to allow for future customization. Variables inside of your widgets code can be easily modified from the outside by simply changing the parameters being passed in. Parameters help developers streamline their development process by eliminating the redundant cycle of republishing every time a widget asset changes. For example, a dynamic audio player widget could be developed to load a music file referenced by a URL parameter passed, instead of from a hard-coded URL.

Parameters can be used to determine:

content (e.g. by passing in data ids or usernames)
state Management of the widget (e.g. by defining the initial selected state)
skins (e.g. by passing in a .jpg URL)
anything else the widget may need.

How Can I Use Parameters?

First, the appropriate SpringBox API code commands must be written to allow for parameter communication. Widget.getParameter() - To receive a parameter into your widget.

Example:

// Code for Receiving the Parameter Object:
// Receive Widget Parameter********************************

var param:Object= Widget.getParameter();     // Param Object 
var passedVar:String = param.yourParamName;  // Custom param 
// *******************************************************

Now your custom parameter is ready to use and packaged into the newly created variable named "passedVar".

To populate a dynamic text field (instance named "txtPassedVar") with your newly passed parameter, use the following code:

// Code to Illustrate Applied Parameter Object:
// Applying Widget Parameter*******************************

var param:Object = Widget.getParameter();         // Param Object 
var passedVar:String = param.yourParamName;       // Custom param 
Widget.trace('My Passed Var' + passedVar); 
txtPassedVar.text= passedVar;                     // Set Text field as parameter
// *******************************************************

Not only can you use the parameters that are initially passed into your widget, but you can also overwrite those parameter values on-the-fly by using the following code: Widget.setParameter() - To save/rewrite a widget parameter.

// Code for Saving / Rewriting the Parameter Object Values:
// Save Widget Parameter********************************

	/* You must retrieve the parameter object 
	each time a change is made to any parameter values. 
	Doing so will ensure that the parameter 
	object being called is the most current data. 
	Once a new value has been applied,the parameter 
	must then be saved using setParameter();*/ 
	
var param:Object = Widget.getParameter();     // Param Object
param.yourParamName = "New Value";            // Your new param value 
Widget.setParameter(param);                   // Apply new Param value
// *******************************************************

// Code for Saving the Parameter Object at Specific Event:
// Save Widget Parameter At Event********************************

mcInstanceName.onRelease = function()        // When MC is released 
{ 
var param:Object = Widget.getParameter();    // Param Object 
param.yourParamName = "newValue";            // Your new param value
Widget.setParameter(param);                  // Apply new Param value
};
// *******************************************************

How Can I Test Parameters?

Once all of the parameter variable names and their potential values have been established, they can be tested with the Web Simulator (included with the SpringWidgets SDK ).

The Web Simulator provides the ability to test parameter communications before the widget is actually uploaded for review at Springwidgets.com. At this time, the web simulator is supported by the Windows Operating System only.

(Figure 1.1)

How Can I Use Parameters On The Web?

By this step, you should have your widget assets (.swf, .fla and optional .as files) uploaded to the Springwidgets.com website and your widget should either already be approved or is in the review process.

Once your widget is approved, you will then have the ability to edit the parameters that you optionally set during the initial widget submission process.
(see Figure. 1.2 below)

Adding Parameters During Submission Process

During the widget submission process you will be given the opportunity to set parameters.

However, once a widget is submitted for review, its parameters will remain un-editable until the widget has then been approved.

edit parameters

(Figure 1.2)

What Exactly Am I Passing Into My Widget?

Each parameter passes to Flash, a data type in a format that Flash understands. For example, the color parameter (Fig. 1.3) passes back to Flash, a hexadecimal (0xCCFF66) value that Flash expects when using its native color object.

color parameter

(Figure 1.3)

Once a new parameters value are selected, simply press the "Preview Widget" button to instantly see how your widget applies them.

(Figure 1.4)

Editing Parameter Properties Of An Existing Widget

There are various data types that can be passed to a Widget via parameters. Simply choose the appropriate data type for a parameter and add it.

The example below illustrates the editing of a parameter of string data type:

string data type

(Figure 1.5)

Give us your ideas and feedback on the nature of these tutorials, or any other builder specific questions by posting in our SpringWidgets Developers Forum. A SpringWidgets Developer will personally answer all posts. Or, you can always contact us at support@fimlabs.com.

Thanks for Playing and Happy Widgetizing!

Subscribe - RSS