negush blog

There are situations when you need to create a web application that is part Flash, part HTML, like some handy widget that must reside in an HTML page and that would also have to communicate with it. The next example presents a simple color setting widget made with Flash, which communicates with the web page it is integrated in. Basically the Flash widget contains three slides to set the RGB color value and the composed color is displayed in the HTML page, in a text input control. The user also has the possibility to enter a hexadecimal value of a color in that text input which will set the sliders in the Flash widget to the corresponding values. Flash – HTML communication (actually ActionScript – JavaScript communication) is possible by using the ExternalInterface class within the flash.external package.

The ExternalInterface class was created to replace the older fscommand() function and can be used to call JavaScript functions from ActionScript or call ActionScript functions from JavaScript. It is also able to transmit a return value from the function being called to the code (ActionScript or JavaScript) calling the external function. It is much more flexible than fscommand() since it allows calling any JavaScript function defined in the HTML file with any number of arguments (of various data types), while fscommand() allowed calling a limited number of functions with a single String as argument. Also allows receiving a return value from the JavaScript function call to ActionScript and vice versa.

Calling a JavaScript function from ActionScript is quite easy. All you have to do is call the static call function of the ExternalInterface class:

ExternalInterface.call("myJSFunction");

You can even specify function parameters and receive the return value, like this:

import flash.external.ExternalInterface;
var value:String = ExternalInterface call("myJSFunction", param1, param2, param3);

Of course this means that in the HTML file containing your Flash clip there has to be a JavaScript function defined with the name of “myJSFunction”. In the above example, we presume that the type of the return value of the JavaScript function is a String, but the ExternalInterface class allows receiving other types of values too.

Calling an ActionScript, from within your HTML document using JavaScript is equally easy. All you have to do is get a reference to the Flash object embedded into the HTML document and then call the ActionScript function directly on this object. Of course, this requires that the ActionScript function is defined as a callback function for the JavaScript code, in the main timeline of the Flash clip:

ActionScript code:

ExternalInterface.addCallBack("myASFunction", someASFunction);

JavaScript code:

var flashMovie = window.document.MyFlashWidget;
flashMovie.myASFunction(value);

In this case, the name and id attributes of the Flash object must be set to “MyFlashWidget”. Another requirement for the HTML document is to set the allowScriptAccess attribute of the Flash object to “always”.

“myASFunction” is the function name that the external JavaScript code must call, but the actual name of the ActionScript function is “someASFunction”. This way, external JavaScript code can only have access to the ActionScript code that the developer allows to. Also, in this case, if the ActionScript code must change and the “someASFunction” function is removed, there could be another function passed to the addCallBack method. Thus, it is ensured that “myASFunction” always gets called by JavaScript and that Javascript can actually be oblivious to the changes of the ActionScript code.

One more thing worth mentioning is that it is a good practice to check if the JavaScript code is available for calling, before actually making any calls to it. This way possible errors or malfunctions are avoided in the application:

if (ExternalInterface.available) {
	try {
		ExternalInterface.addCallback("myASFunction ", someASFunction);			}
	catch(e:Error) {
		// Callback function could not be added for various reson.
		// You could treat this situation here.
	}
}

You can download the full example from here. I hope it will help out some of you.

Update: For Internet Explorer you should make sure that you specify your embedded Flash object the id attribute, as mentioned in this post: ExternalInterface.call not working with IE.