MACROMEDIA FLASH |
YOUR FIRST FS COMMAND |
FS Command: A Short Introduction
Note: if you're looking for a javascript/flash gateway, you should also take a look at the "Flash/JavaScript Integration Kit".
For the purposes of this article, "fscommand()" refers mainly to Flash -> JavaScript communication (ie. Flash executing javascript statements in a web browser). However, fscommand's scope is actually broader than that. Without going into too much detail, here's a slightly longer description of fscommand():
"fscommand()" is the name of a function in Flash that provides communication with a flash movie's host application ("application" means anything that can play Flash media, whether natively, eg. the stand-alone Flash player, or with the use of a plug-in, eg. a web browser). For example, a web-based fscommand() might execute a JavaScript function from a Flash button click. (We'll see later that JavaScript can also control the Flash movie playback.) fscommand() can also communicate with Lingo and can send a limited set of built-in commands to the stand-alone Flash player (eg. "Quit", "FullScreen", "AllowScale", "ShowMenu").
Support for FS Command
Okay, let's get back to the topic at hand: using fscommand() on the web. If you intend to develop scripted Flash movies for the web, you need to be aware that not all browsers support fscommand. The specific browsers that support it are:
The specific browsers that don't support fscommand() are:
Unsupported browsers lack the ActiveX (IE) or LiveConnect (Netscape 4 and older) required to communicate between the plugin and the browser. Further, starting with Flash 3.0, if you are developing fscommand Flash content for Netscape 4, you'll need to explicitly enable LiveConnect on every page that hosts a scripted Flash movie (you do not have to enable LiveConnect in Netscape 6.2 and later). To enable LiveConnect, include this attribute in your movie's EMBED tag: swLiveConnect="true". During the enabling process, users will see "Starting Java..." in the Netscape status bar, and will experience a delay (15 seconds is not uncommon) while Java loads.
Two Directions of Communication
So now that you know where fscommand works, you probably want to know how it works. We'll first examine fscommand-based Flash -> Javascript communication. Then we'll take a look at sending information the other way with JavaScript -> Flash methods.
How Flash Talks to JavaScript
(Before we study executing JavaScript code with fscommand, it should be noted that JavaScript may also be executed from getURL() functions exactly like you'd execute javascript from an anchor (<A>) tag. The getURL() approach is actually more widely supported in browsers than fscommand(), not to mention more convenient to code. For more info, see launching a window with a getURL JavaScript call. Now back to fscommand()...)
Flash attempts to send a message to JavaScript whenever an fscommand function executes. When the browser receives an FS Command from Flash, it checks if there's a matching JavaScript function (or VB Script in the case of IE) that can "catch" the command. If there is, it executes that "catcher" function, sending two parameters to it--the values of the "Command" and "Arguments" parameters of the fscommand.
The following diagram illustrates the process, using the example of an fscommand that calls a JavaScript alert. The fscommand's arguments are "call_alert" and "Hello world!", as follows:
fscommand("call_alert", "Hello world!");
The implementation of fscommand in Netscape and IE differs slightly; the diagram shows how the command travels from Flash to JavaScript in both browsers. Below the diagram is the matching Flash sample movie. Take a look at the model and the sample, then I'll get into the details of how to do it.
<HTML> <HEAD> <TITLE>My First FS Command</TITLE> </HEAD> <BODY> <OBJECT CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" WIDTH="100%" HEIGHT="100%" CODEBASE="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab" ID=testmovie> <PARAM NAME="MOVIE" VALUE="mymovie.swf"> <PARAM NAME="PLAY" VALUE="false"> <PARAM NAME="LOOP" VALUE="false"> <PARAM NAME="QUALITY" VALUE="high"> <PARAM NAME="SCALE" VALUE="SHOWALL"> <EMBED NAME="testmovie" SRC="mymovie.swf" WIDTH="100%" HEIGHT="100%" PLAY="false" LOOP="false" QUALITY="high" SCALE="SHOWALL" swLiveConnect="true" PLUGINSPAGE="http://www.macromedia.com/go/flashplayer"> </EMBED> </OBJECT> </BODY> </HTML>
<SCRIPT LANGUAGE="VBScript"> <!-- // Catch FS Commands in IE, and pass them to the corresponding JavaScript function. Sub testmovie_FSCommand(ByVal command, ByVal args) call testmovie_DoFSCommand(command, args) end sub // --> </SCRIPT>
<SCRIPT LANGUAGE="JavaScript"> <!-- function testmovie_DoFSCommand(command, args) { if (command == "call_alert") { alert("Here's the Flash message: " + args); } } //--> </SCRIPT>
How JavaScript talks to Flash
JavaScript can send commands to Flash by invoking built-in methods on embedded movie objects. Calling Flash methods works exactly like all calls to built-in methods on JavaScript objects (eg. document.write() or window.close()). From a developer point of view, this direction of communication is one sided--JavaScript methods control a Flash movie entirely in JavaScript, without requiring complementary code in the Flash movie.
I'll go through a single example of controlling a movie by calling a JavaScript Flash method. You can then extrapolate the technique and apply it to any of the Flash methods available (for a complete list of Flash 2.0 and 3.0 methods, see Macromedia's Flash Methods reference document). Take a look at the following sample movie to see an example of Flash controlled by JavaScript.
Sample 2: JavaScript Controls a Flash Movie
Then follow the steps below to see how to it works. For reference, you can download a .zip of the files used in sample 2.
<HTML> <HEAD> <TITLE>JavaScript controls Flash</TITLE> </HEAD> <BODY> <OBJECT CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" WIDTH="100%" HEIGHT="100%" CODEBASE="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab" ID=testcommand> <PARAM NAME="MOVIE" VALUE="mymovie.swf"> <PARAM NAME="PLAY" VALUE="false"> <PARAM NAME="LOOP" VALUE="false"> <PARAM NAME="QUALITY" VALUE="high"> <PARAM NAME="SCALE" VALUE="SHOWALL"> <EMBED NAME="testcommand" SRC="mymovie.swf" WIDTH="100%" HEIGHT="100%" PLAY="false" LOOP="false" QUALITY="high" SCALE="SHOWALL" swLiveConnect="true" PLUGINSPAGE="http://www.macromedia.com/go/flashplayer/"> </EMBED> </OBJECT> </BODY> </HTML>
<SCRIPT LANGUAGE="JavaScript"> <!-- var movieName = "testcommand"; function thisMovie(movieName) { // IE and Netscape refer to the movie object differently. // This function returns the appropriate syntax depending on the browser. if (navigator.appName.indexOf ("Microsoft") !=-1) { return window[movieName] } else { return document[movieName] } }
function playmovie() { thisMovie(movieName).Play(); } //--> </SCRIPT>
// Checks if movie is completely loaded. // Returns true if yes, false if no. function movieIsLoaded (theMovie) { // First make sure the movie's defined. if (typeof(theMovie) != "undefined") { // If it is, check how much of it is loaded. return theMovie.PercentLoaded() == 100; } else { // If the movie isn't defined, it's not loaded. return false; } }You can use movieIsLoaded() to check your movie's load status before invoking any methods, like this:
function playmovie() { if (movieIsLoaded(thisMovie(movieName))) { thisMovie(movieName).Play(); } }
<FORM> <INPUT TYPE="BUTTON" VALUE="Play" ONCLICK="playmovie()"> </FORM>
References
Macromedia's Technote 04160 (Scripting with Flash)
The first developer article on scripting with Flash. Most of the technical information about FS Command is there, but the content is aimed at experienced developers.
Macromedia's Scripting with Flash Tutorial
A well written article covering both JavaScript Flash method usage and fscommand().
Macromedia's Creating a smarter Site Navigation Bar with Flash and JavaScript
A short discussion on how to use JavaScript to maintain the state of a Flash navigation bar across frames. Thin from a documentation standpoint, but useful for its sample code. [NOTE: THE ABOVE ARTICLE IS NO LONGER AVAILABLE AT MACROMEDIA'S SITE, BUT CAN BE READ AT THE WAYBACK MACHINE'S WEB ARCHIVE.]
Macromedia's Hawaii Map Demo
Originally a sample site by Jon Gay, (the inventor of Flash), which demonstrates some of the things you can do with FS Command. This demo is now up at Flash Central. Again, good for the samples, but light on documentation. You'll have to root around with View Source...
Macromedia's Scripting with Flash and ActiveX
A list of the ActiveX-only (ie. *not* Netscape) methods available with Flash.
John Croteau's JavaScript/Flash Clock Tutorial
A well written, in depth tutorial on making a clock in Flash movies that's run by JavaScript. A good application of FS Command that's worth checking out once you're familiar with FS Command basics.
John Croteau's FS Command Methods Table
A complete spread-sheet style table listing the FS Command methods for JavaScript, the stand-alone player, and ActiveX.