Getting Started

To include the source files for SWF Utility and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.11.0/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('swf', function (Y) {
    // SWF Utility is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using the SWF Utility

This section describes how to use the SWF Utility in further detail.

Anatomy of the SWF Utility

The SWF Utility uses the browser information from the Y.ua variable to generate the appropriate markup for embedding the Flash player. The markup that the SWF Utility generates is entirely based on the <object> tag, and therefore will not work in older browsers that use the non-standard <embed> tag.

In addition, the SWF Utility also determines the version of the Flash player (using YUI's swfdetect library), and places that information in Y.ua.flash as a period-delimited string (MajorVersion.MinorVersion.Revision). This information is used by SWF utility to prevent Flash Player embedding if the version of user's installed Flash player does not match that required by the developer.

While the SWF Utility provides a direct access to the instance of the Flash player it encapsulates, it is recommended that all communication to that instance occur via the methods provided by the SWF Utility (see below.)

Configuring and Instantiating the SWF Utility

For simplicity, all configuration of the embedded Flash player instance happens in the SWF Utility at construction time, and therefore, all configuration parameters must be provided as arguments to the SWF constructor.

By default, the SWF constructor requires only two arguments – the reference to the container in which the instance of the Flash player should be placed, and the URL of the swf application that the Flash player instance should load. Note that the Flash player instance created by the SWF Utility always adopts the size of the parent container it is placed into; therefore, setting the size of the Flash player is as simple as setting the size of its container.

To put an instance of the Flash player on the page, simply create a new instance of Y.SWF and provide it with the reference to the container in which it should be placed, as well as the URL of the swf file that needs to be loaded:

YUI({...}).use('swf',function (Y) {

    // Default everything
	var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf");

});

If you would like to specify additional parameters or pass arbitrary variables to the SWF, you can provide the constructor with the third argument, a paramter Object:

var params = {version: "9.0.115",
	          fixedAttributes:
			  {allowScriptAccess:"always", allowNetworking:"all"},
			  flashVars:
			  {foo: "bar", foo1: "bar1"}
			 };
var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf", params);

The parameter object may contain the following possible properties:

Property	Description
version	A period-delimited string of three numbers specifying the minimum version of Flash player that must be installed on the user's machine.
fixedAttributes	An object with a set of configuration variables specific to the Flash player. The list of all possible configuration variables and their values, provided by Adobe, can be found here.
flashVars	An object with a set of variables to pass to the Flash player. These variables are made available to the Flash application at initialization time, in the ActionScript's Stage.loaderInfo.parameters container.

Calling Methods on the instance of Flash player

The SWF Utility provides a wrapper for calling methods that have been exposed to JavaScript from within the Flash application. This allows the developer to call the methods without having to directly reference the private pointer to the instance of the Flash player contained in the SWF Utility. To call a method foo(arg1, arg2) on an instance of the Flash player, do the following:

YUI({...}).use('swf',function (Y) {

	var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf");
	myswf.callSWF("foo", [arg1, arg2]);	

});

Note that, since Flash player is run as a separate thread, the existence of its instance is not guaranteed when the method call on it is made. To make sure that Flash is ready to accept incoming method calls, it's best to have the Flash player make a call to JavaScript announcing that it has finished initializing. While there is a number of ways to do that, YUI hybrid components use the YUIBridge ActionScript library to automate this process. See the next section for notes on its usage.

Working with the YUIBridge ActionScript Library

YUIBridge ActionScript library creates a standardized method for sending YUI events from a Flash application. In an ActionScript application, an instance of YUIBridge is created as follows:

import com.yahoo.util.YUIBridge

...

// The scope for 'this' should be either the top-level application
// or a Sprite that has been placed on the stage.

var yuiBridge:YUIBridge = new YUIBridge(this.stage);

Instead of using ExternalInterface.addCallback on each method that needs to be exposed to JavaScript, you can instead call a collective addCallbacks() method available in YUIBridge:

import com.yahoo.util.YUIBridge

...

// The scope for 'this' should be either the top-level application
// or a Sprite that has been placed on the stage.

var yuiBridge:YUIBridge = new YUIBridge(this.stage);
yuiBridge.addCallbacks({externalMethodName:internalMethod, externalMethodName2:internalMethod2});

});

To dispatch YUI events (fired by the instance of the SWF Utility on the JavaScript end, you can call YUIBridge's sendEvent method:

import com.yahoo.util.YUIBridge

...

// The scope for 'this' should be either the top-level application
// or a Sprite that has been placed on the stage.

var yuiBridge:YUIBridge = new YUIBridge(this.stage);
yuiBridge.sendEvent({type:'someevent', payload:'some payload'});
});

In addition to any custom events you dispatch, YUIBridge also fires a swfReady event at initialization time, announcing that the Flash player is ready for communication with JavaScript:

YUI({...}).use('swf',function (Y) {

	var myswf = new Y.SWF("#swfContainer", "http://example.com/example.swf");
	myswf.on('swfReady', init);
	
	function init() {
		// Start communicating with the Flash player instance here
		myswf.callSWF("foo", [arg1, arg2]);
	}

});