Passing request data with flashVars properties

You pass request data to applications built with Flex by defining the flashVars properties in the wrapper. You can also access URL fragments by using the BrowserManager. For more information, see Passing request data with URL fragments.

The flashVars properties and URL fragments are read in the application at run time. As a result, changing flashVars properties or URL fragments does not require you to recompile the application.

Passing request data with flashVars properties

If you are using the generated wrapper from Flash Builder, then you add flashVars variables by creating an object called flashvars, setting properties on that object, and then passing that object to the swfobject.embedSWF() method of SWFObject 2.

The following example sets the firstname and lastname properties of the flashvars object, and then passes that object to the embedSWF() method:
<script type="text/javascript"> 
    var swfVersionStr = "10.0.0"; 
    var xiSwfUrlStr = "playerProductInstall.swf"; 
    var flashvars = {}; 
    flashvars.firstname = "Nick"; 
    flashvars.lastname = "Danger"; 
    var params = {}; 
    params.quality = "high"; 
    params.bgcolor = "#ffffff"; 
    params.allowscriptaccess = "sameDomain"; 
    var attributes = {}; 
    attributes.id = "TestProject"; 
    attributes.name = "TestProject"; 
    attributes.align = "middle"; 
    swfobject.embedSWF( 
        "FlashVarTest.swf", "flashContent", "100%", "100%", swfVersionStr, 
        xiSwfUrlStr, flashvars, params, attributes); 
    swfobject.createCSS("#flashContent", "display:block;text-align:left;"); 
</script>

If your wrapper uses the <object> and <embed> tags, you can pass variables to your applications by using the flashVars properties in the <object> and <embed> tags in your wrapper. You do this by adding ampersand-separated sets of name-value pairs to these properties.

The following example sets the values of the firstname and lastname in the flashVars properties inside the <object> and <embed> tags in a simple wrapper:

<html>
<head>
<title>code/wrapper/SimplestFlashVarTestWrapper.html</title>
<style>
    body {
        margin: 0px;
        overflow:hidden
    }
</style>
</head>
<body scroll='no'>
<table width='100%' height='100%' cellspacing='0' cellpadding='0'><tr><td valign='top'>

<h1>Simplest FlashVarTest Wrapper</h1>

    <object id='mySwf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' height='100%' width='100%'>
        <param name='src' value='FlashVarTest.swf'/>
        <param name='flashVars' value='firstname=Nick&lastname=Danger'/>
        <embed name='mySwf' src='FlashVarTest.swf' height='100%' width='100%' flashVars='firstname=Nick&lastname=Danger'/>
    </object>

</td></tr></table>
</body>
</html>

The value of the flashVars properties do not have to be static. If you use JSP to return the wrapper, for example, you can use any JSP expression for the value of the flashVars properties that can be evaluated to a String.

The following example uses the values stored in the HttpServletRequest object (in this case, you can use form or query string parameters):

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- saved from url=(0014)about:internet -->

<%
    String fName = (String) request.getParameter("firstname");
    String lName = (String) request.getParameter("lastname");
%>

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <title>DynamicFlashVarTestWrapper.jsp</title>
        <script type="text/javascript" src="swfobject.js"></script>
        
        <script type="text/javascript">
            var swfVersionStr = "0";
            var xiSwfUrlStr = "";
            var flashvars = {};
            flashvars.firstname = "<%= fName %>";
            flashvars.lastname = "<%= lName %>";
            var params = {};
            params.quality = "high";
            params.bgcolor = "#ffffff";
            params.allowscriptaccess = "sameDomain";
            var attributes = {};
            attributes.id = "FlashVarTest";
            attributes.name = "FlashVarTest";
            attributes.align = "middle";
            swfobject.embedSWF(
                "FlashVarTest.swf", "flashContent",
                "100%", "100%",
                swfVersionStr, xiSwfUrlStr,
                flashvars, params, attributes);
        </script>
    </head>

    <body>
        <div id="flashContent"/>
   </body>
</html>
You can also PHP expressions to pass query string parameters in a wrapper, as the following example shows:
<!-- saved from url=(0014)about:internet --> 
<html lang="en"> 
<head> 
<?php 
    @ $fName = $_GET['firstname']; 
    @ $lName = $_GET['lastname']; 
?> 
<script type="text/javascript" src="swfobject.js"></script> 
<script type="text/javascript"> 
    var swfVersionStr = ""; 
    var xiSwfUrlStr = ""; 
    var flashvars = {}; 
    flashvars.fName = "<?php echo $fName; ?>" 
    flashvars.lName =  "<?php echo $lName; ?>" 
    var params = {}; 
    params.quality = "high"; 
    params.bgcolor = "#ffffff"; 
    params.allowscriptaccess = "sameDomain"; 
    var attributes = {}; 
    attributes.id = "FlashVarTest"; 
    attributes.name = "FlashVarTest"; 
    attributes.align = "middle"; 
    swfobject.embedSWF( 
        "FlashVarTest.swf", "flashContent", 
        "100%", "100%", 
        swfVersionStr, xiSwfUrlStr, 
        flashvars, params, attributes); 
    swfobject.createCSS("#flashContent", "display:block;text-align:left;"); 
</script> 
</head> 
<body > 
    <div id="flashContent"> 
</body> 
</html>

For more information about the HTML wrapper, see Creating a wrapper.

If your user requests the SWF file directly in the browser, without a wrapper, you can access variables on the query string without providing additional code in the wrapper (because there is no wrapper). The following URL passes the name Nick and the hometown San Francisco to the application:

http://localhost:8100/flex/myApp.swf?myName=Nick&myHometown=San%20Francisco

About flashVars properties encoding

The values of the flashVars properties must be URL encoded. The format of the string is a set of name-value pairs separated by an ampersand (&). You can escape special and nonprintable characters with a percent symbol (%) followed by a two-digit hexadecimal value. You can represent a single blank space by using the plus sign (+).

The encoding for flashVars properties is the same as the page. Internet Explorer provides UTF-16-compliant strings on the Windows platform. Netscape sends a UTF-8-encoded string to Flash Player.

Most browsers support a flashVars string or query string up to 64 KB (65535 bytes) in length. They can include any number of name-value pairs.

Using the SWF file path to pass request data

You can append the values of properties to the application’s SWF file path in the wrapper. The swfUrlStr property identifies the location of the application’s SWF file. It is the first argument in the swfobject.embedSWF() method call.

The following example appends query string parameters to the swfUrlStr properties in the custom wrapper:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- saved from url=(0014)about:internet -->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <title>wrapper/SwfObjectWithFlashVars.html</title>
        <script type="text/javascript" src="swfobject.js"></script>
        <script type="text/javascript">
            var swfVersionStr = "0";
            var xiSwfUrlStr = "";
            var flashvars = {};
            var params = {};
            params.quality = "high";
            params.bgcolor = "#ffffff";
            params.allowscriptaccess = "sameDomain";
            var attributes = {};
            attributes.id = "FlashVarTest";
            attributes.name = "FlashVarTest";
            attributes.align = "middle";
            swfobject.embedSWF(
                "FlashVarTest.swf?firstname=Nick&lastname=Danger",
                "flashContent", "100%", "100%",
                swfVersionStr, xiSwfUrlStr,
                flashvars, params, attributes);
        </script>
    </head>
    <body>
        <div id="flashContent"/>
   </body>
</html>

Variables you define in this manner are accessible in the same way as flashVars properties. For more information, see Accessing the flashVars properties.

Accessing the flashVars properties

To access the values of the flashVars properties, you use the FlexGlobals object’s topLevelApplication.parameters property. This property points to a dynamic object that stores the parameters as name-value pairs. You can access variables on the parameters object by specifying parameters.variable_name.

In your application, you typically assign the values of the run-time properties to local variables. You assign the values of these properties after the Application’s creationComplete event is dispatched. Otherwise, the run-time properties might not be available when you try to assign their values to local variables.

The following example defines the myName and myHometown variables and binds them to the text of Label controls in the initVars() method:

<?xml version="1.0" encoding="utf-8"?>
<!-- wrapper/ApplicationParameters.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" creationComplete="initVars()">
     <s:layout> 
          <s:VerticalLayout/> 
     </s:layout>
     
       <fx:Script><![CDATA[
          import mx.core.FlexGlobals;
       
          /* Declare bindable properties in Application scope. */
          [Bindable]
          public var myName:String;
          [Bindable]
          public var myHometown:String;
           
          /* Assign values to new properties. */
          private function initVars():void {
               myName = FlexGlobals.topLevelApplication.parameters.myName;
               myHometown = FlexGlobals.topLevelApplication.parameters.myHometown;
          }
     ]]></fx:Script>
       
     <s:HGroup>
          <s:Label text="Name: "/>
          <s:Label text="{myName}" fontWeight="bold"/>
     </s:HGroup>
     
     <s:HGroup>
           <s:Label text="Hometown: "/>
           <s:Label text="{myHometown}" fontWeight="bold"/>
     </s:HGroup>
</s:Application>

When a user requests this application with the myName and myHometown parameters defined as flashVars properties or as query string parameters, Flex displays their values in the Label controls.

To view all the flashVars properties, you can iterate over the FlexGlobals.topLevelApplication.parameters properties, as the following example shows:
<?xml version="1.0" encoding="utf-8"?>
<!-- wrapper/FlashVarTest.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="init()">
     
     <s:layout> 
        <s:HorizontalLayout/> 
     </s:layout>
     
     <fx:Script><![CDATA[
         import mx.core.FlexGlobals;

         private function init():void {
              for (var i:String in FlexGlobals.topLevelApplication.parameters) {
                 ta1.text += i + ":" + FlexGlobals.topLevelApplication.parameters[i] + "\n";
              }
          }
      ]]></fx:Script>
       
      <s:Label text="flashVars"/>
      <s:RichText id="ta1" width="300" height="200"/>

</s:Application>