ActionScript - Passing parameters to a Flash movie

ActionScript
Passing parameters to a Flash movie

Generic Flash objects typically need one or more parameters to function. When displayed via a web page, there are 3 main methods to accomplish this.

FlashVars Parameters
Calling Javascript functions via the ExternalInterface class
Using the LocalConnection class to access flash popup windows

Normally, I then use these parameters to read a configuration file and/or to query a database and get more information.

This page covers what works, what doesn't, and presents some related notes.

URL Parameters

When calling web servers (cgi and ISAPI executables), it is common to pass named parameters via the hyperlink. The question mark (?) indicates the beginning of the parameters, individual parameters are separated with ampersands (&).

http://computer/path/CGI.exe?name1=value1&name2=value2

The help says that this same technique can be used with Flash movies.

<embed src="myApplication.swf?name1=value1&name2=value2" />

Parameters passed this way are accessed using

var s:String = stage.loaderInfo.parameters["name2"];

I could not get this method to work.

FlashVars Parameters

Assuming that you are launching the Flash movie via the Adobe provided code, you can pass parameters via the FlashVars parameter.

The basic html code (but without FlashVars) is automatically generated via

File / Publish...

which also creates AC_RunActiveContent.js. Note that, when using the default settings, the Flash file, html file, and AC_RunActiveContent.js should be copied to the same server directory.

To pass parameters, modify the html file to add FlashVars to both the AC_FL_RunContent function

AC_FL_RunContent(
 ...
  'FlashVars','name1=value1&name2=value2',
 ...
); //end AC code

and the object definition

<object ... >
  <param name="FlashVars" value="name1=value1&name2=value2" />
  <embed src="myApplication.swf" FlashVars="name1=value1&name2=value2" [many more parameters here] />
</object>

Notice that the object definition requires 2 entries of FlashVars

param is used by Internet Explorer
embed is used by Netscape and Macintosh Internet Explorer

whereas AC_FL_RunContent only requires one and creates the correct format based on the detected browser type.

Parameters passed this way are accessed in AS3 using any of the following

var s1:String = stage.loaderInfo.parameters["name2"];
var s2:String = this.root.loaderInfo.parameters["name2"];
var s3:String = root.loaderInfo.parameters.name2;           // reference

A number of characters have special meanings and can not be directly entered in names or values ... these will need to be entered as hex values. The following are some of most common problem characters.

space %20 
&     %26 
+     %2B 
=     %3D

The following will pass a filename with query parameters. Without the hex encoding, this parameter would be broken up into several separate parameters.

<object ... >
  <param name="FlashVars" value="Filename=Delphi_Program.exe?name1%3Dvalue1%26name2%3Dvalue2" />
</object>

Also note that the parameter names are case sensitive.

Notes

As usual, The Adobe Flash 9 (AS3) help was completely worthless.

After stumbling around for a while, I discovered the following hint in the help for LoaderInfo.parameters.

An object that contains name-value pairs that represent the parameters provided to the loaded SWF file.

You can use a for-in loop to extract all the names and values from the parameters object.

The two sources of parameters are: the query string in the URL of the main SWF file, and the value of the FlashVars HTML parameter (this affects only the main SWF file).

Unfortunately, there are only two (2) occurrences of FlashVars in the ActionScript 3.0 sections of the help and no explanation of what it means.

It took searching the internet to get any real information. Once I found an example - search the page for FlashVars - the rest was fairly straight forward.

After creating this page, I discovered that the Flash ActionScript 2.0 help contains several examples. I never thought to look there because most of the AS 2.0 help just gets in the way ... which is why I typically keep it disabled. There are 2 sections

Using FlashVars in an application

Using FlashVars to load and display text

(The links go to the associated web pages which also contain user notes.) In the help, you will need to click (expand) the plus sign to see the examples ... on the web pages, the examples are already expanded. Notice that the way to access the parameters is different - the method I show above works for AS3, the help files show the AS2 method where variables with the correct names are automatically generated.

Also note that the AS2 help suggests using both FlashVars and LoadVars to get data ... but the AS3 help says that LoadVars is no longer used. This is why I leave the AS2 help turned off and don't bother testing its code examples.

Fails

Based on the help, and the lack of AS3 FlashVars examples, these represent how I interpreted the help. These were tested and do not work.

<object ... >
  <param name="name1" value="value1" />
  <param name="name2" value="value2" />
  <embed src="myApplication.swf?name1=value1&name2=value2" />
</object>

And

AC_FL_RunContent(
 ...
  'name1', 'value1',
  'name2', 'value2',
 ...
); //end AC code

It was at this point that I searched the internet.

Debug Code

This is the debug code I used this to figure out what actually works. Filename_UIText was a Text field on the form.

for (var s1:String in stage.loaderInfo.parameters) {

  trace(s1 + " = " + stage.root.loaderInfo.parameters[s1]);

  Filename_UIText.text = Filename_UIText.text + s1 + " = " + 
                            stage.root.loaderInfo.parameters[s1] + " : ";

}

I also comment out the <noscript> tag (by changing it to <!noscript> so that I can test both the JavaScript and the object code - this shows 2 copies of the same Flash movie.

ExternalInterface class

The ExternalInterface class allows ActionScript 3 to interface with Javascript functions located in a web page. The provided help provides pretty good examples showing both

How to call code in a web page, and
How the web page can call code in the Flash movie

(See Example: Using the external API with a web page container)

The examples below require that ScriptAccess is enabled.

allowScriptAccess="sameDomain"

The AS3 help shows where these go in the html file.

Calling Javascript

This goes in the Flash program

var Barcode:String = ExternalInterface.call("GetBarcode");

And the matching javascript code (in the related html file)

<script language="JavaScript">
<!--
// ------- functions called by ActionScript -------
function GetBarcode()
{
  return "ABC-123";
}
//-->
</script>

Called by JavaScript

This goes in the Flash program

import flash.external.ExternalInterface;

  if (ExternalInterface.available) {
    try {
      ExternalInterface.addCallback("Callback_AliasName", AliasFunction);
    } catch (error:SecurityError) {
      //output.appendText("A SecurityError occurred: " + error.message + "\n");
    }
  } else {
   // output.appendText("External interface is not available for this container.");
  }

function AliasFunction(value:String){
  .....
}

In the web page (works in IE 6, fails in FireFox 1)

Multi-Browser

When writing JavaScript, you have to realize that there are no reasonable standards. Each browser follows what ever rules it wants. As a result, the code in the help files fails on Netscape browsers and Macintoch systems.

I found the following code as a user comment on the Adobe web site. I was able to verify that it works with with IE 6 and FireFox 1.

No screen name said on Oct 23, 2008 at 4:52 PM : I had the problem where calling a function(in Flash Active Script) from JavaScript was giving a "Type Error" with message stating "is not a valid function". On the URL of the browser, I type in: javascript:try { document.getElementById("FLVPlayer").onNextVideo(22); } catch (e) {alert(e); } It gives me an type error "onNextVideo is not a function". This works fine on IE and Chrome though - no errors - it changes the video successfully. Finally I figured out the issue. I had to do it this way: function getFlashMovieObject() { var movieName = "FLVPlayer"; if(document.embeds[movieName]) return document.embeds[movieName]; if(window.document[movieName]) return window.document[movieName]; if(window[movieName]) return window[movieName]; if(document[movieName]) return document[movieName]; return null; } function onPlayVideo(value) { var oFlv = getFlashMovieObject(); oFlv.onPlayVideo(value); } Now everything works on every browser I tested. FINALLY I'm HAPPY Sekhar.

So this is what I am currently using

IE Failures

To call ActionScript functions, an alias is defined and JavaScript "calls" (references) the alias. The problem is that some alias names are not supported ... and, of course,

The specific problem names are browser dependent, and
There is no list of problem alias names

The following aliases are known to fail with Internet Explorer (IE) - play, stop, LoadMovie - note that Load_movie works.

When using LoadMovie, double clicking the Error on page warning (in the status bar) displays this totally unhelpful error.

Line:  24
Char:  3
Error: Type mismatch
Code:  0
URL:   http://.......

When the name used in the JavaScript does not match the alias name, this error will be displayed.

Line:  48
Error: Object doesn't support this property or method

Notice that the line number changed ... same code different line number ... very confusing.

play and stop generate

Error: Wrong number of arguments or invalid property assignment

When testing these types of failures, beware of the various caches - your changes my not show up for several hours. Be sure to open a new IE window to load the most current swf file (Refresh - F5 - uses the cached version) - I use ctrl-n (New Window) with Internet Explorer.

Another failure occurs if you try to display the html file by simply double clicking it.

Adobe Flash Player has stopped a potentially unsafe operation.

The message goes on to tell you how to change your security settings so this warning will not be displayed - don't do that, it will open your machine to attacks from other Flash applications. Since there is no failure when getting the page from the web, my suggestion is to open the html page using a local web server.

http://localhost/Generic_mcGraph/index.html

Old Methods - fscommand

The old way to access Javascipt was to use fscommand

fscommand(command:String, args:String = ""):void
Lets the SWF file communicate with either Flash Player or the program hosting Flash Player, such as a web browser.

However, the AS3 (Flash 9) help says

If you are publishing for Flash Player 8 or later, the ExternalInterface class provides better functionality for communication between JavaScript and ActionScript ...

Old Methods - JavaScript "SetVariable"

According to Adobe, using Flash 4 it is possible for JavaScript on an html page to change values in a Flash movie. The basic method is

<script language = "JavaScript"><!--
function PassFlash(){
  window.document.movie.SetVariable("text", "hello");
}
//--></script>

I have not tested this. It seems unlikely that this is useful. For one thing, it does not work with Macintosh. In addition, I don't know how the Flash application will know that there has been a change ... I guess the value could be checked with a timer.

Also, if you called a JavaScript function, it could set multiple Flash variables before returning.

Multiple Flash Applications

When 2 or more Flash applications are running on the same computer, they can communicate using the LocalConnection class.

These applications can be in the same web page, or not. This technique can be used to develop popup windows to change parameters.

Author: Robert Clemenzi - clemenzi@cpcug.org