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.

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 the ExternalInterface class can be employed. In addition, you can communicate between two Flex applications on the same page by using SharedObjects.

To pass request data into your Flex applications, you can define flashVars properties inside your HTML wrapper and access their values using either the Application.application.parameters or LoaderConfig.parameters objects. For more information, see Passing request data with flashVars properties. Using these techniques, you can personalize a Flex application without requiring 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.

Accessing environment information

Flex provides some simple mechanisms for getting information about the browser and the environment in which the application runs. From within the Flex application, you can get the URL to the SWF file; you can also get the context root. The following example gets the SWF file's URL, constructs the host name from the URL, and displays the context root, which is accessible with the @ContextRoot() token:

<?xml version="1.0"?>
<!-- wrapper/GetURLInfo.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="getHostName()">
  <mx:Script><![CDATA[

  [Bindable]
  public var g_HostString:String;
  [Bindable]
  public var g_ContextRoot:String;
  [Bindable]
  public var g_BaseURL:String;
  
  private function getHostName():void {
     g_BaseURL = Application.application.url;
     var pattern1:RegExp = new RegExp("http://[^/]*/");
     if (pattern1.test(g_BaseURL) == true) {
        g_HostString = pattern1.exec(g_BaseURL).toString();
     } else{
        g_HostString = "http://localhost/"
     }   
  }
  ]]></mx:Script>

  <mx:Form>
     <mx:FormItem label="Base URL:">
        <mx:Label text="{g_BaseURL}"/>
     </mx:FormItem>
     <mx:FormItem label="Host Name:">
        <mx:Label text="{g_HostString}"/>
     </mx:FormItem>
     <mx:FormItem label="Context Root:">
        <mx:Label text="@ContextRoot()"/>
     </mx:FormItem>
  </mx:Form>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can also use the flash.system.Capabilities class to access information about the client, such as Operating System, Player version, and language. For more information, see Using Flash ActionScript.

You can access more information about the browser and the application's environment using the ExternalInterface. For more information, see About the ExternalInterface API.

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.adobe.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.

The following browsers support the ExternalInterface API:

• All versions of Internet Explorer for Windows (5.0 and later)
• Embedded custom ActiveX containers, such as a desktop application embedding Adobe® Flash® Player ActiveX control
• Any browser that supports the NPRuntime interface (which currently includes the following browsers):
  • Firefox 1.0 and later
  • Mozilla 1.7.5 and later
  • Netscape 8.0 and later
  • Safari 1.3 and later

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:

<?xml version="1.0"?>
<!-- wrapper/CheckExternalInterface.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="checkEI()">
  <mx:Script><![CDATA[
     [Bindable]
     public var eiStatus:String;

     private function checkEI():void {
           eiStatus = ExternalInterface.available.toString();
     }

  ]]></mx:Script>
  
  <mx:Label id="l1" text="{eiStatus}"/>

</mx:Application>
The executing SWF file for the previous example is shown below:

For examples of using the ExternalInterface API with Flex applications, see Using the ExternalInterface API to access JavaScript from Flex and Accessing Flex from JavaScript.

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.

For more information on security restrictions, see About ExternalInterface API security in Flex; also see Applying Flex Security.