Recipe 21.4. Passing Parameters to Flash from HTML

Recipe 21.5. Communicating Between Flash and JavaScript

Problem

You want to call a JavaScript function from Flash or an ActionScript function from JavaScript.

Solution

Use the ExternalInterface class in ActionScript.

Discussion

Prior to Flash 8, it was difficult to build Flash applications that integrated well with the container within which Flash Player was embedded. The most common example is one in which you want Flash Player to be able to communicate with the web browser. When authoring for Flash Player versions prior to 8, the optimal solution was to use the Flash/JavaScript Integration Kit (http://weblogs.macromedia.com/flashjavascript/). However, the ExternalInterface ActionScript class simplifies things significantly. ExternalInterface requires that you are publishing to Flash Player 8 or higher.

The ExternalInterface class enables Flash Player to make calls to functions within the container. In the case of Flash Player embedded in a web page, that means that Flash Player can call JavaScript functions. And ExternalInterface also enables the container to call ActionScript functions. That means that JavaScript can call Action-Script functions, and thus you can build integrated web applications in which Flash and the web browser are able to communicate.

The ExternalInterface class is in the mx.external package. Therefore, you'll generally want to import the class. The rest of the code in this recipe assumes that you've imported the class with the following code:

import flash.external.ExternalInterface;

When you want to call a JavaScript function from Flash, you can use the ExternalInterface.call( ) method. The call( ) method requires at least one parameter specifying the name of the JavaScript function to call. For example, if the HTML page within which Flash Player is embedded defines a function called updateForm , you can call that function from ActionScript using the following code:

ExternalInterface.call("updateForm");

Supposing that the function accepts parameters, you can pass those parameters to the function by adding those parameters to the parameter list of the call( ) method. For example, if updateForm expects four parameters (a string, a number, a Boolean, and an array), the following will pass parameters to the function:

ExternalInterface.call("updateForm", "a", 2, true, [1, 2, 3, 4]);

Additionally, ExternalInterface.call( ) works synchronously: if the JavaScript function returns a value, you can use that return value as part of an ActionScript expression. For example, if updateForm returns a Boolean value, the following code assigns that value to a variable within ActionScript:

var bFormUpdated:Boolean = ExternalInterface.call("updateForm", "a", 2, true, [1, 2,
	3, 4]);

When you want to call an ActionScript function from JavaScript, there are a few steps you should take:

1. Register the ActionScript function as a callback using ExternalInterface.addCallback( ) .

2. Within the JavaScript, retrieve a reference to the Flash object.

3. Call the registered function from the Flash object.

The ExternalInterface.addCallback( ) method enables you to register a function so that you can call it from JavaScript. The method requires the following parameters:

methodName

A string specifying the name by which the function is to be registered. The registered name is the name by which you can call the function from JavaScript.

instance

The object that will be referenced by this within the function when it is called.

method

A reference to the function or method that you want to register.

The following code defines a function called rotateClip( ) that rotates a movie clip ( mClip ) by the number of degrees specified by the parameter:

function rotateClip(nDegrees:Number):Void {
	  mClip._rotation = nDegrees;
	}

Assume that the function is defined on the main timeline. Then the following code, if also placed on the main timeline, registers the function so it can be called from JavaScript. It is registered so that from JavaScript it can be called by the name rotate instead of rotateClip .

ExternalInterface.addCallback("rotate", this, rotateClip);

The second parameter says that when rotateClip( ) is called from JavaScript, it is called as a method of the main timeline.

When a function is registered, it is possible to call it from JavaScript. In order to call the function from JavaScript you first have to retrieve a reference to the Flash object. How you retrieve the reference to the Flash object depends on the browser. If the browser is IE for Windows, the Flash object is determined by window. objectID where objectID is the value of the id attribute of the <object> tag. If the browser is not IE for Windows, the Flash object is determined by document. embedName where embedName is the value of the name attribute of the <embed> tag. You can determine whether the browser is IE Windows by testing whether navigator.appName contains the value Microsoft. The following code defines a function that returns the Flash object where the <object> id attribute and the <embed> name attribute are both examples:

function getFlashObject() {
	  if(navigator.appName.indexOf("Microsoft") != -1) {
	    return window.example;
	  }
	  else {
	    return document.example;
	  }
	}

You can then call the ActionScript function from the Flash object by the registered name. For example, the following code calls the registered rotate function. Notice that you can pass parameters to the function.

var exampleFlashObject = getFlashObject();
	exampleFlashObject.rotate(50);