About exchanging data with Flex applications -- Flex 2

Flex applications generally exist inside larger web applications that control everything from security to state management to the overall look and feel of the website. In this scenario it is important that the Flex application is able to communicate with the surrounding environment, providing a deeper integration with the larger web application. Enabling the Flex application to communicate with the environment provides a method of integration with other technologies such as AJAX.

Often, a Flex application is loaded in a browser within a wrapper. This wrapper is often an HTML page that can include JavaScript or other client-side logic that the Flex application can interact with. For more information about the wrapper, see Creating a Wrapper in Building and Deploying Flex 2 Applications.

There are several ways to communicate between the surrounding environment and the Flex application; depending on the type of integration required, any combination of flashVars properties, query string parameters, the navigateToURL() method, and with the ExternalInterface class can be employed.

To pass request data into your Flex applications, use query string parameters and access the value using either the Application.application.parameters or LoaderConfig.parameters objects. You can also pass data as flashVars properties in the wrapper and access the values using the parameters property of the Application and LoaderConfig objects. For more information, see Using flashVars. Using these techniques, you can personalize a Flex application without triggering a recompilation.

Use the methods of the ExternalInterface API to call the methods of your Flex applications and vice versa. The addCallback() method exposes methods of your Flex application to the wrapper. The call() method invokes a method within the wrapper and returns any results. If the wrapper is HTML, the addCallback() and call() methods enable method invocation between your Flex application and the hosted JavaScript running within the browser. For more information, see About the ExternalInterface API.

In some situations, you want to open a new browser window or navigate to a new location. You can do this with the navigateToURL() global function. Although it is not part of the ExternalInterface API, this method is flexible enough to let you write JavaScript inside it, and invoke JavaScript functions on the resulting HTML page. The navigateToURL() method is a global function in the flash.net package.

Subtopics

Enabling Netscape connections

In Netscape browsers, the <embed> tag in your wrapper must include swliveconnect=true to allow communication between the browser and your Flex application. This lets the Flex application connect with the page's scripting language (usually JavaScript). You add this parameter to the <embed> tags in the Flex application's wrapper, as the following example shows:

<embed pluginspage='http://www.macromedia.com/go/getflashplayer' 
    width='300' 
    height='100'
    flashvars=''
    src='TitleTest.mxml.swf'
    name='MyApp'
    SWLIVECONNECT='true'
/>

You are not required to set the value of swliveconnect to true in the <object> tag because the <object> tag is used by Microsoft Internet Explorer, but not Netscape browsers.

About the ExternalInterface API

You use the ExternalInterface API to let your Flex application call methods in the wrapper and to allow the wrapper to call functions in your Flex application. The ExternalInterface API consists primarily of the call() and addCallback() methods in the flash.external package.

Before you execute code that uses the ExternalInterface API, you should check whether the browser supports it. You do this by using the available property of the ExternalInterface object in your Flex application. The available property is a Boolean value that is true if the browser supports the ExternalInterface API and false if the browser does not. It is a read-only property.

The following example uses the available property to detect support for the ExternalInterface API before executing methods that use the class:

if (ExternalInterface.available) {
    var f:String = "myJavaScriptFunction";
    var m:String = ExternalInterface.call(f);
} else {
    // Handle failure here.
    trace("Sorry, mate.");
}

In addition to requiring that browsers meet certain version requirements, the ExternalInterface API requires that JavaScript is enabled in the browser. You can use the <noscript> tag in the HTML page to handle a browser with disabled JavaScript. For more information, see Handling browsers that disable JavaScript.

The available property determines only if the browser can support the ExternalInterface API, based on its version and manufacturer. If JavaScript is disabled in the browser, the available property still returns true.

The ExternalInterface API is restricted by the security sandbox in which the SWF file is running. Its use relies on the domain-based security restrictions that the allowScriptAccess and allowNetworking parameters define. You set the values of the allowScriptAccess and allowNetworking parameters in the SWF file's wrapper.

For more information on these parameters, see Creating a Wrapper in Building and Deploying Flex 2 Applications. For more information on security restrictions, see Applying Flex Security in Building and Deploying Flex 2 Applications.