Flash Widgets at Widgetbox

Using Widgetbox to launch my Flash widget was a no-brainer.

A Flash widget contains a SWF file hosted on your server.

You can author your SWF file using Adobe (Macromedia) Flash Professional or other compatible tool. Users who subscribe to your widget will receive a copy of it served by your server.

When you make a Flash widget on Widgetbox, simply enter the URL to your SWF file.

Benefits of Registering Your Flash Widget With Widgetbox

Widgetbox provides the following Flash-specific benefits to widget developers:

No-paste installation into MySpace and other sites.
Flash widgets are supported by more sites than Javascript/HTML widgets because some sites simply don’t allow Javascript code to be added.
MySpace linking. We enable your widget to link out of MySpace.
User configuration of Flash. Allow bloggers and other subscribers to configure your widget. This actually changes the generated <EMBED> tag. Users get a live preview of their changes as they make them.

In addition, Flash developers get everything we offer all widgets, such as:

Widget Syndication Metrics. Track the spread of your widget across the internet with your own widget analytics dashboard. Learn more.
Viral adoption. Widgetbox provides a simple, direct mechanism for people that see a widget in the wild to get it for themselves.

Get started! Below are some details about how Flash widgets work in Widgetbox:

The Basics of Flash Registration
Flash Widget Configuration
Default Flash Widget Parameters
No-Paste Installation Into MySpace
Links in Flash Widgets

The Basics of Flash Registration

When you register a Flash-based widget with Widgetbox, you register the URL to your Flash movie/application (the SWF file). Widgetbox generates an <EMBED> tag each time the widget is viewed.

Widgetbox does not download or otherwise cache the SWF file; the end viewer of the widget downloads it from wherever you specified.

Flash wrapper. Widgetbox wraps your Flash in a Widgetbox wrapper SWF which retrieves the user’s configuration info from Widgetbox every time a someone views the widget, and supplies it to your SWF. By default, when a user subscribes to your widget, they are provided with the <EMBED> tag for our Flash Wrapper to paste into their site. The same code is also used when a user chooses to use one of our automatic installers to place the widget.

NOTE:

For AS2 developers - While running in a Flash wrapper, you cannot use references to _level0; instead use _root.
For AS3 developers - While running in a Flash wrapper, your SWF movie no longer has a reference to stage.

Flash 9 Player Requirement Our Flash wrapper is written in ActionScript 3.0 and published for Flash Player 9. End viewers of the widget are required to have Flash Player 9 or later installed. As of January 2008, between 2% and 3% of all Flash Player installations are NOT Flash Player 9.

JavaScript wrapper. When a user chooses to use our JavaScript wrapper instead of the default (the Flash wrapper), the <EMBED> tag is generated by the JavaScript every time a user views the page.

Flash Widget Configuration

Widgetbox lets you graphically create a Widget Settings form that users can use to customize their copy of your widget, as explained here. Widgetbox supplies this configuration info to the Flash application via the <EMBED> tag.

Here’s what the Widget Settings form looks like from a user’s perspective:

You, the developer, can control where configuration parameters show up in the <EMBED> tag. These are described in the following sections.

SWF Query String Parameters

By default, Widgetbox config parameters are appended to the URL to the SWF file in standard http querystring format.

For example, if you have a movie at http://domain.com/movie.swf and your Widgetbox configuration form has a parameter named ‘username’with a value of ‘Ed’, the movie will load from http://domain.com/movie.swf?username=Ed.

The <EMBED> tag would look like this:

Parameters sent this way can be retrieved with Flash Actionscript by referencing ActionScript’s _root object. So in this example, the value of _root.username would be ‘Ed’.

If the height and width of your widget are user-configurable, Widgetbox will pass in widget_width and widget_height on the URL querystring.

Plugin Parameters

Widgetbox config parameters that start with "plugin." set Flash plugin parameters.

For example, Flash’s standard “wmode” parameter is used to make a Flash movie transparent.

When you build the Widgetbox configuration form, naming a parameter "plugin.wmode" and giving it a value of "transparent" will set the wmode parameter in the <EMBED> tag, like this:

Hiding config items from end users
You can hide config elements from end users. This is a screenshot of a hidden Widget Setting called “My Hidden Setting”. The name of the hidden param is called my_hidden_setting.

The plugin.scale configuration parameter vs Stage.scaleMode inside your ActionScript
In Flash 6 and above, you can specify the scale mode for your Flash movie. By setting the Stage.scaleMode attribute you tell your widget how it should stretch and grow. When you register a widget with us, if you set this attribute within your Actionscript code, you must also include the widget configuration parameter plugin.scale. This is because our wrapper does not know anything about your code, only what you tell us. In order for your widget to display correctly in our wrapper, we need to know if you have any special scaling mode turned on. (If your widget does not look like it is scaling correctly when installed via our Flash embed code, it may indicate a problem with this setting.)

FlashVars Parameters

Widgetbox config parameters that start with "flashvar." are added to the FlashVars string.

What is FlashVars? The Flash <EMBED> tag supports a FlashVars parameter that is used to send a querystring-encoded set of variables to a Flash movie. For example, if your widget has a parameter "flashvar.param1" and has a value of "xxx" the <EMBED> tag will look like this:

Actionscript 2.0 Users: Your flashvars aren’t accessible via _root
Since Flash widgets on Widgetbox run within a Flash wrapper, referencing _root will NOT return your FlashVars. Instead, refer to them by name without the prefix.

For example, a FlashVar that has a parameter name of “siteURL” is not referenced as “_root.siteURL”. Instead, your ActionScript code becomes simply “siteURL”

Default Flash Widget Parameters

When you input the URL to your SWF file in the widget wizard, Widgetbox inspects the SWF and adds parameters (hidden to the user) containing your SWF’s background color, width, height, framerate. These help the Widgetbox Flash wrapper to function (if the stage size or framerate of your widget changes, you will need to update these values to match.)

The default parameters will look something like this:

Code-Free Installation Into MySpace

Widgetbox’s Get Widget installation menu screen lets users choose what part of MySpace to install the widget to:

Alternatively, advanced users can choose to get the HTML embed code for their widget.

Links in Flash Widgets

How To Avoid Getting Caught by a Popup Blocker

Adobe’s Flash Player Plugin v9 presents some interesting challenges for Flash widget developers when it comes to linking out. When your Flash widget is embeded on a page with allowScriptAccess set, it can affect the behavior of your links. Widgetbox always adds the allowScriptAccess parameter to every subscription of your widget with the value of sameDomain (to prevent any malicious usage of Javascript.)

When your widget runs in this mode, you need to make sure you do 3 things:

Any link outs from your widget must target “_blank”.
The actionscript call that opens the new page (getURL or navigateToURL) MUST be called from within the event listener function that handles the user’s interaction.
AS2 - Use onRelease instead of onPress to capture a user’s interaction if it results in a linkout.

How To Make Your Widget’s Links Work In MySpace

A MySpace link-enabled widget is wrapped with two “softkey” buttons, similar to cell phones softkeys. The screenshots below show how it works.

Normal Widget

With Softkeys

Link Selected

These softkeys show up automatically when the user installs your widget on MySpace. Everywhere else, the widget appears normally.

What You’ll Need To Do
You’ll need to do two things to get MySpace linking working:

In your own SWF file, update any code that generates a link. The code is shown below. It is designed such that your Flash application works whether or not Widgetbox is involved; you can use the same SWF on your own site, or in other widget directories (though won’t link in MySpace) .
To make the Widgetbox wrap your widget with the MySpace wrapper, you have to add a few parameters to your widget in our widget editor.

Activating Softkeys in ActionScript 2.0

Example Code

Download the ZIP file containing the working example code for the Echo Test (Flash AS2) example widget.

Initial Setup

Put the following at the top of your Flash file, in global scope so that all parts of your application can access it.

//Allow your swf to talk to our wrapper
Security.allowDomain("*");

//Default Softkey parameter to handle when not in Widgetbox Flash Wrapper
if(wbx_softkey == null){
wbx_softkey = "false";
}

Activating Softkeys - General Use

This function "openPage" is called where you would normally use getURL().

_global.openPage = openPage; //parallel definition in global scope is needed for activation from an HTML link
function openPage(u:String, window:String){
    if(wbx_softkey == "true" && widget_id!= null && widget_id != ""){
        //setup local connection to activate softkeys
        var sender:LocalConnection = new LocalConnection();
        sender.onStatus = function(oStatus:Object){
            trace(oStatus.level);
        }
        sender.send(wbx_wrapper_channel, "setSoftKeyURL", u);
    }else{
        if(window==undefined || window==null){
            window="_blank";
        }
        getURL(u, window);
    }
}

Activating Softkeys - From a HTML text link

Any urls in HTML text links will need to be prefixed with the string "asfunction:openPage,".

var actionScriptCall = "asfunction:openPage,";
var myTextField = this.createTextField("myTextField", this.getNextHighestDepth(), 0, 0, 100, 12);
myTextField.html = true;
myTextField.htmlText = "<a href=\"" + actionScriptCall + "http://www.widgetbox.com/" + "\">Widgetbox!</a>";

Activating Softkeys in ActionScript 3.0

Example Code

Download the ZIP file containing the working example code for the Echo Test (Flash AS3) example widget.

Initial Setup

Put the following at the top of your Flash file, in global scope so that all parts of your application can access it.

//You must prepare your SWF file to accept the following input parameters as QS params:
private var wbx_softkey = null;
private var wbx_wrapper_channel = null;

//Allow your swf to talk to our wrapper
Security.allowDomain("*");

//Default Softkey parameter to handle when not in Widgetbox Flash Wrapper
if(wbx_softkey == null){
wbx_softkey = "false";
}

Activating Softkeys - General Use

This function "openPage" is called where you would normally use navigateToUrl().

Activating Softkeys - From a HTML text link

Any urls in HTML text links will need to be prefixed with the string "event:", and a listener needs to be defined to handle the click event.

//Create the prefix and prepend your HTML links with the prefix
var eventPrefix = "event:";
var myTextField = new TextField();
myTextField.html = true;
myTextField.htmlText = "<a href=\"" + eventPrefix + "http://www.widgetbox.com/\">Widgetbox.com</a>";
addChild(myTextField);

//You must define a handler function for Link Events
private function openPageFromLink(event:TextEvent){
    var target = event.text;
    if(wbx_softkey == “true” && wbx_wrapper_channel!= null && wbx_wrapper_channel != “”){
        //setup local connection to activate softkeys
        var sender:LocalConnection = new LocalConnection();
        sender.send(wbx_wrapper_channel, “setSoftKeyURL”, target);
    }else{
        navigateToURL(new URLRequest(target), “_blank”);
    }
}

//And the textField object must have the TextEvent listener added to it
myTextField.addEventListener(TextEvent.LINK, openPageFromLink);

Final Step: Update Your Widget’s Parameters

To make the Widgetbox wrap your widget with the MySpace wrapper, you have to ensure you have a few parameters to your widget in our widget editor.

How to add parameters to a widget:

Edit your widget by going to the My Registrations page and clicking ‘Edit’. You should now be in the Widget Editor.
Go to the Parameters tab.
Enter the magic parameters as described below.

These are the parameters your widget needs. They can be of type ”Hidden“ — they do NOT need to show up in the user’s configuration form. Most are actually added automatically by the system when you register the widget, so the only one you should have to deal with is wbx_softkey.

Parameter	Meaning
`wbx_softkey`	Tells Widgetbox to use softkeys on MySpace. REQUIRED. Does not need a default value.
`wbx_stageWidth`	The actual width of the stage of your regular SWF. REQUIRED.
`wbx_stageHeight`	The actual height of the stage of your regular SWF. REQUIRED.
`wbx_framerate`	The framerate of your regular SWF. OPTIONAL — defaults to 12.

This is what your config screen in the widget editor might look like: