The ExternalInterface is a fantastic way to communicate with Javascript directly from Flash. It is very similar to fscommand() , CallLabel(), and CallFrame(). The External Interface is much more flexible. You can pass as many arguments as you want to any function on the HTML page and receive a return value. It works in the opposite way as well. You can call Actionscript functions from Javascript and receive a return value immediately.

The ExternalInterface is an extension of the Object class. It requires the user's browser to support either ActiveX or NPRuntime API. ( http://www.mozilla.org/projects/plugins/npruntime.html ) It works on the following browsers: IE5+, Netscape 8.0+, Mozilla 1.7.5+, Firefox 1.0+, and Safari 1.3+.

Available : Flash 8; AS 1.0

Before we get into examples and details about the class, we'll list out the properties and methods for reference.

Properties

Modifiers

Property

Description

static

available:Boolean
[read-only]

Returns whether or not the player is able of offering
an external interface.

Properties Inherited from Object extension

Modifiers

Property

Description

constructor:Object

Reference to the constructor function for a given
object instance.

__proto__:Object

Refers to the prototype property of the class or constructor function used to create the object.

static

prototype:Object

A reference to the superclass of a class or function object.

__resolve:Object

A reference to a user-defined function that is invoked if Actionscript code refers to an undefined property or method.

Methods

Modifiers

Signature

Description

static

addCallback( methodName:String, instance:Object, method:Function ):Boolean

Registers an Actionscript method as callable from the container.

static

call( methodName:String, [parameter1:Object ] ) : Object

Calls a function exposed by the Flash Player container, passing 0 or more arguments.

Methods Inherited from Object extension

addProperty; hasOwnProperty; isPropertyEnumerable; isPrototypeOf; registerClass; toString; unwatch**; valueOf; watch**

** These are very useful but commonly overlooked methods of the Object class. I have an additional article dedicated to these methods.

This class is implemented into your file by calling:

import flash.external.ExternalInterface


The following is an example of communicating with Javascript from Actionscript.

Start off by creating a new AS 2.0 project in Flash, create a dynamic textbox on the Stage with the instance name of "return_txt". Fill it with some default text so you can see the change. This code will apply the JS function to the onMouseDown event, so clicking anywhere will show you how it works.

import flash.external.ExternalInterface
// import the external interface class

function onChange( str:String ){
     return_txt.text = "Javascript Return: " + str;
     // the return function
}

ExternalInterface.addCallback( "onChange", this, onChange );
// tells it the property in JS, the scope, and the return function to call

onMouseDown = function(){
     ExternalInterface.call("general_JS_call", "String to return to Flash:");
     // calling the function name first, arguments of the function following
}

HTML / JS Code

<script>
var me;
function getID( swfID ){
     if(navigator.appName.indexOf("Microsoft") != -1){
          me = window[swfID];
     }else{
          me = document[swfID];
     }
}

function js_to_as( str ){
     me.onChange(str);
}

function general_JS_call( str ){
     me.onChange( prompt(str) );
}
</script>
<body onLoad='getID("jsExample");'>
<embed src='test.swf' height='400' width='550' id='jsExample' >
<input type="button" value="Pass to AS" onClick="js_to_as('Test value to send to AS');">


So This HTML code will call the getID function onLoad to determine what kind of browser you're using for the DOM. The general_JS_call is called from the Actionscript code. The .onChange applied to me is also defined in the Actionscript.

Important Notice: When passing the variable back to Flash, don't set the onChange = str. You must use parentheses asif you are calling a function. me.onChange(str)

As you can see when you test this code, the argument passed from AS "String to return to Flash:" will show up on the prompt called in general_JS_call. This is a great example of how passing arguments to Javascript from Flash works.

This also demonstrates how to pass variables from Javascript to Actionscript.



This is a brief and generic overview of how to use the ExternalInterface class. It shows the ease and reliability of using the ExternalInterface for Javascript calls to and from Flash. Look out for more in-depth and deeper examples.

You can use these examples to get very elaborate and involved based on your JS and AS knowledge.