Accessing Flex from JavaScript
You can call Flex methods from your enclosing wrapper by using the ExternalInterface API. You do this by adding a public method in your Flex application to a list of callable methods. In your Flex application, you add a local Flex function to the list by using the addCallback() method of the ExternalInterface API. This method registers an ActionScript method as callable from the JavaScript or VBScript in the wrapper.
The signature for the addCallback() method is as follows:
addCallback(function_name:String, closure:Function):void
The function_name parameter is the name by which you call the Flex function from your HTML page's scripts. The closure parameter is the local name of the function that you want to call. This parameter can be a method on the application or an object instance.
The following example declares the myFunc() function to be callable by the wrapper:
<?xml version="1.0"?>
<!-- wrapper/AddCallbackExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp()">
<mx:Script>
import flash.external.*;
public function initApp():void {
ExternalInterface.addCallback("myFlexFunction",myFunc);
}
public function myFunc(s:String):void {
l1.text = s;
}
</mx:Script>
<mx:Label id="l1"/>
</mx:Application>
To call the Flex function from the HTML page, you get a reference to the movie object. This is the same value as the id and name properties of the <object> and <embed> tags. In this case, it is mySwf. You then call the method on that object, passing whatever parameters you want, as the following example shows:
<html><head>
<title>wrapper/AddCallbackWrapper.html</title>
</head>
<body scroll='no'>
<SCRIPT LANGUAGE="JavaScript">
function callApp() {
window.document.title = document.getElementById("newTitle").value;
mySwf.myFlexFunction(window.document.title);
}
</SCRIPT>
<h1>AddCallback Wrapper</h1>
<form id="f1">
Enter a new title: <input type="text" size="30" id="newTitle" onchange="callApp()">
</form>
<table width='100%' height='100%' cellspacing='0' cellpadding='0'>
<tr>
<td valign='top'>
<object id='mySwf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab' height='200' width='400'>
<param name='src' value='AddCallbackExample.swf'/>
<param name='flashVars' value=''/>
<embed name='mySwf' src='AddCallbackExample.swf' pluginspage='http://www.adobe.com/go/getflashplayer' height='100%' width='100%' flashVars=''/>
</object>
</td>
</tr>
</table>
</body></html>
The default value of the id and name properties in the wrapper is mxml_filename.mxml.swf. The name that you use to access the Flex application in your HTML page's script cannot contain any periods, so you must change the default values in the wrapper. For more information, see Editing the Flex application's id and name properties.
If you do not know which browser your users will be using when they request your Flex application, you should make your wrapper's script browser independent. For more information, see Handling multiple browser types.
If there is no function with the appropriate name in the Flex application or that function hasn't been made callable, the browser throws a JavaScript error.
Flex and Flash Player have strict security in place to prevent cross-site scripting. By default, Flex functions are not callable by HTML scripts. You must explicitly identify them as callable. You also cannot call a Flex function from an HTML page if the HTML page is not in the same domain as the application. However, it is possible to expand the sources from which Flex functions are called. For more information, see About the addCallback() method.
Handling multiple browser types
In most cases, you must write your HTML page's scripts to handle multiple browser types. Getting a reference to the application object is not the same in Internet Explorer as it is in Netscape-based browsers such as FireFox.
To write script that is browser independent, you examine the name of the navigator object and return a reference to the application based on that. The following code gets a reference to the application in all major browsers:
<html><head>
<title>wrapper/BrowserAwareAddCallbackWrapper.html</title>
</head>
<body scroll='no'>
<SCRIPT LANGUAGE="JavaScript">
// Internet Explorer and Mozilla-based browsers refer to the Flash application
// object differently.
// This function returns the appropriate reference, depending on the browser.
function getMyApp(appName) {
if (navigator.appName.indexOf ("Microsoft") !=-1) {
return window[appName];
} else {
return document[appName];
}
}
function callApp() {
window.document.title = document.getElementById("newTitle").value;
getMyApp("mySwf").myFlexFunction(window.document.title);
}
</SCRIPT>
<h1>AddCallBack Wrapper</h1>
<form id="f1">
Enter a new title: <input type="text" size="30" id="newTitle" onchange="callApp()">
</form>
<table width='100%' height='100%' cellspacing='0' cellpadding='0'>
<tr>
<td valign='top'>
<object id='mySwf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab' height='200' width='400'>
<param name='src' value='AddCallbackExample.swf'/>
<param name='flashVars' value=''/>
<embed name='mySwf' src='AddCallbackExample.swf' pluginspage='http://www.adobe.com/go/getflashplayer' height='100%' width='100%' flashVars=''/>
</object>
</td>
</tr>
</table>
</body></html>
Editing the Flex application's id and name properties
By default, the name of your Flex application's application object is mxml_filename.mxml.swf in the wrapper. However, periods are not allowed in JavaScript or VBScript method or object names. So, in order to use the ExternalInterface API, you must edit the id property that is assigned to your Flex application in the wrapper.
You rename the object on the page by changing the values of the <embed> tag's name property and the <object> tag's id property.
The following example shows the locations in the wrapper where you edit the application's name:
<noscript>
// Set the id of the application in the <object> tag.
<object
classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'
codebase='http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab'
width='300'
height='100'
id='MyApp'>
<param name='flashvars' value=''>
<param name='src' value='MyApp.mxml.swf'>
// Set the name of the application in the <embed> tag.
<embed
pluginspage='http://www.adobe.com/go/getflashplayer'
width='300'
height='100'
flashvars=''
src='MyApp.mxml.swf'
name='MyApp'
/>
</object>
</noscript>
<script language='javascript' charset='utf-8'>
// Change the id and name properties in the script block, too.
...
</script>
This example shows the <object> and <embed> tags in the <noscript> block of the wrapper. You must also change the name and id properties of the <object> and <embed> tags in the <script> block. These nearly identical blocks are both required to run a full-featured Flex application.
After you change the name of the Flex application object, you can reference the application by name in your JavaScript.
Handling browsers that disable JavaScript
In some cases, the client's browser either does not support JavaScript or the user has purposely disabled it. You can use the <noscript> tag in the wrapper to define what happens when this user tries to run your Flex applications.
One possible solution is to insert a message that tells the user that they cannot use some functionality of your application because JavaScript is disabled. The following example warns users when someone with JavaScript disabled tries to run your Flex application:
<html>
<body>
<noscript>
<EM>Your browser either does not support JavaScript or has disabled it. Some features of this application require JavaScript. Click <A HREF="...">here</A> to continue anyway, Otherwise, please enable JavaScript and reload this page.
</EM>
</noscript>
<script src="mysource.js"></script>
</body>
</html>