Calling JavaScript methods from Flex applications -- Flex 2

The ExternalInterface API makes it very simple to call methods in the enclosing wrapper. You use the static call() method, which has the following signature:

flash.external.ExternalInterface.call(function_name:
    String[, arg1, ...]):Object;

The function_name is the name of the function in the HTML page's JavaScript. The arguments are the arguments that you pass to the JavaScript function. You can pass one or more arguments in the traditional way of separating them with commas, or you can pass an object that is deserialized by the browser. The arguments are optional.

The following example script block calls the JavaScript f() function in the enclosing wrapper by using the call() method:

<mx:Script>
<?xml version="1.0" encoding="iso-8859-1"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        import flash.external.*;
    
        public function callWrapper():void {
            var f:String = "changeDocumentTitle";
            var m:String = ExternalInterface.call(f,"New Title");
            trace(m); 
        }
    </mx:Script>
    <mx:Button label="Change Document Title" click="callWrapper()"/>
</mx:Application>

On your HTML page, you define a function as you would any other JavaScript function. You can return a value, as the following example shows:

<SCRIPT LANGUAGE="JavaScript">
    function changeDocumentTitle(a) {
        window.document.title=a;
        return "successful";
    }
</SCRIPT>

This feature requires that the embedded movie file have an id attribute. Without it, no call from your Flex application will succeed.

The call() method accepts zero or more arguments, which can be ActionScript types. Flex serializes the ActionScript types as JavaScript numbers and strings. If you pass an object, you can access the properties of that deserialized object in the JavaScript, as the following example shows:

<mx:Script>
    public function callWrapper():void {
        var o:Object = new Object();
        o.lname = "Danger";
        o.fname = "Nick";
        var f:String = "sendComplexDataTypes";
        ExternalInterface.call(f,o);
    }
</mx:Script>

Flex only serializes public, nonstatic variables and read-write properties of ActionScript objects. You can pass numbers and strings as properties on objects, simple objects such as primitive types and arrays, or arrays of simple objects.

The JavaScript code can then access properties of the object, as the following example shows:

<SCRIPT LANGUAGE="JavaScript">
    function sendComplexDataTypes(a:Object) {
        alert("Welcome " + a.fname + " " + a.lname + "!");
    }
</SCRIPT>

You can also embed objects within objects, as the following example shows. Add the following code in your Flex application's <mx:Script> block:

<mx:Script>
    public function callWrapper():void {
        var f:String = "sendComplexDataTypes";
        var o:Object = new Object();
        o.lname = "Danger";
        o.fname = "Nick";
        o.b = new Array("DdW","E&T","LotR:TS");
        var m:String = ExternalInterface.call(f,o);
    }
</mx:Script>

<SCRIPT LANGUAGE="JavaScript">
    function sendComplexDataTypes(a) {
        // Get value of fname and lname properties.
        var m = ("Welcome " + a.fname + " " + a.lname + "!\n");
        // Iterate over embedded object's properties.
        for (i=0; i<a.b.length; i++) {
            m = m + a.b[i] + "\n";
        }
        alert(m);
    }
</SCRIPT>

Flex and Flash Player have strict security in place to prevent cross-site scripting. By default, you cannot call script on an HTML page if the HTML page is not in the same domain as the Flex application. However, you can expand the sources from which scripts can be called. For more information, see About ExternalInterface API security in Flex.

You cannot pass objects or arrays that contain circular references. For example, you cannot pass the following object:

var obj = new Object();
obj.prop = obj; // Circular reference.