How to Include Your Flex Application on a Web Page

In this excerpt from Getting Started With Flex 4, you will learn how to include your Flex application on a web page and deploy it to a web server. You will learn what code you need to add to a web page to load your Flex application and what additional files you need to place on the web server along with the SWF file.

---

To view your application, the user needs Flash Player—more specifically, a particular version of Flash Player. This means the web page that embeds your application must also contain code to check for the presence of the minimum required version of Flash Player and code to help users upgrade or get Flash Player if their system does not meet the requirements.

Step 1: Look at the html-template Files

Look at the files used to generate your browser-embedded application.




The files you see in this folder will depend upon your project settings.

By default, when you build your application, these template files are used to generate the HTML file and other files that are placed in the bin-debug and bin-release folders. They contain variables that are populated by project properties or application tag attributes. The next two steps discuss the purpose of each file.

Step 2: Open TestDrive.html

The TestDrive.html file is in the bin-release folder. Look at the generated code for embedding the Flex application.

The primary code for checking for the presence and minimum version of Flash Player is provided by SWFObject 2, a standards-based library for embedding SWF files in HTML pages. The following code includes the library in the web page:

<script type="text/javascript" 
  src="swfobject.js"></script>

The SWF file is embedded by calling the embed() method of swfobject, as follows:

swfobject.embedSWF(
  "TestDrive.swf", "flashContent", "100%", "100%",
  swfVersionStr, xiSwfUrlStr, flashvars, params, 
  attributes);

The first argument is the location of the SWF file.

The second argument is the name of alternate content (the id of a div tag defined further down in the code) to display if Flash Player is not available.

The third and fourth arguments specify the height and width of the application. By default, these are set to 100% in the generated HTML wrapper so the application takes up the entire browser window. To change the application’s size—for example, to take up a certain amount of space in an existing HTML page—change these arguments to other absolute or relative values.

The fifth argument specifies the minimum required version of Flash Player. Flex 4 applications require Flash Player 10.0.0 or later.

The sixth argument adds Express Installation, a quick, seamless way for users to upgrade their version of Flash Player if it does not meet the minimum requirements. This argument is set equal to an empty string (for no Express Installation) or to the location of the SWF file providing this functionality: playerProductInstall.swf. Both of these values are set in Javascript code before the embed() call.

The last three arguments pass data to the application and set properties for the application. Use the flashvars object to pass data to the Flex application from the containing web page. Use the params and attributes objects to specify how the SWF file should appear in the browser, including its quality, alignment, scale, transparency, and more.

Finally, take a look at the noscript tag, which is executed in browsers with Javascript disabled. It contains two object tags that provide a nonJavascript way to embed a SWF file:

<noscript>
  <object 
    classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
    width="100%" height="100%" id="TestDrive">
    <param name="movie" value="TestDrive.swf" />
    <param name="quality" value="high" />
    <param name="bgcolor" value="#ffffff" />
    <param name="allowScriptAccess" value="sameDomain" />
    <param name="allowFullScreen" value="true" />
    <!--[if !IE]>-->
      <object type="application/x-shockwave-flash" 
        data="TestDrive.swf" width="100%" height="100%">
         <param name="quality" value="high" />
         <param name="bgcolor" value="#ffffff" />
         <param name="allowScriptAccess" 
           value="sameDomain" />
         <param name="allowFullScreen" value="true" />
    <!--<![endif]-->
    <!--[if gte IE 6]>-->
      <p> Either scripts and active content are not 
          permitted to run or Adobe Flash Player 
          version 10.0.0 or greater is not installed. 
      </p>
    <!--<![endif]-->
    <a href="/go/getflashplayer"><img 
      src="/images/shared/download_buttons/
        get_flash_player.gif"
      alt="Get Adobe Flash Player" /></a>
    <!--[if !IE]>-->
    </object>
    <!--<![endif]-->
  </object>
</noscript>

The object tag with the classid is for use with Internet Explorer and browsers that implement Flash Player as a Flash ActiveX control. The second object tag is for use with browsers that implement Flash Player as a plug-in, such as Firefox, Safari, or Chrome. Use param tags to set SWF parameters for both.

If you want to change SWF properties, make sure you set identical parameter values for the swfobject and both of the noscript object tags.

If you want to embed your application in an existing web page and not use the default wrapper, make sure all of this code (or equivalent functionality) exists in that web page.

Step 3: Look at the bin-release Files

When you deploy your application to a web server, to be on the safe side, you can just move all the files located in the bin-release folder to the production server. Take a look at each of these files now, though, so you can determine if you actually need them all.




Every Flex application uses at least part of the Flex framework. To minimize your SWF file size and download times, the framework code is not compiled into your application. Instead, it is provided separately as a group of Adobe authenticated Runtime Shared Libraries (RSLs), which you only have to download once. Flash Player caches the RSLs and you can use them with any Flex application. These are all the SWZ files you see in the project bin folders.

When a user requests an application that uses Adobe RSLs (which all Flex 4 applications do by default), if Flash Player already has the appropriate version of the framework files cached locally, it uses them. Otherwise, Flash Player downloads them from the Adobe website and caches them locally. This means you do not have to deploy these SWZ files to your web server. You can, though, if you want them on your server for failover or if you’re deploying an application to an Internet-restricted environment.

File	Description	Deploy?
history folder	Includes Javascript, CSS, and HTML pages that are used for deep-linking, which lets users navigate the application interactions with the browser’s Forward and Back buttons and enables the creation of custom URLs for bookmarking.	Yes, if your application uses deep-linking.
datavisualization_x.swz	RSL for the data visualization components, including charts and advanced grids.	No, provided on Adobe servers.
framework_x.swz	RSL for core Flex framework and MX components.	No, provided on Adobe servers.
osmf_flex_x.swz	RSL for the open source media framework used primarily with the Spark Video Player component.	No, provided on Adobe servers.
PlayerProductInstall.swf	The SWF file used with swfobject for Express Installation—a quick, seamless way for users to upgrade Flash Player.	Always, unless you disable Express Installation.
rpc_x.swz	RSL for data services that make HTTP, web service, or Flash Remoting calls.	No, provided on Adobe servers.
spark_x.swz	RSL for Spark components.	No, provided on Adobe servers.
sparkskins_x.swz	RSL for skins for MX components.	No, provided on Adobe servers.
swfobject.js	SWFObject 2 code for detecting Flash Player and embedding a SWF file in a web page.	Always, unless you do not use swfobject to embed your SWF file in a web page.
TestDrive.html	The HTML page that embeds the Flex application.	Deploy this file or another web server page that embeds the SWF file and checks for the minimum required version of Flash Player.
TestDrive.swf	Your application!	Always.
textLayout_x.swz	RSL for the Text Layout Framework used by the Spark text controls.	No, provided on Adobe servers.

Note: For PHP developers: You will also see an amf_config.ini file and a gateway.php file in the bin folders. These files are used when your application makes service calls.

Step 4: Change the Project Settings So History Files Are Not Generated

To prevent history files from being generated in your project, take the following steps:

• Select Project→Properties, go to Flex Compiler, uncheck “Enable integration with browser navigation,” and click Apply.
  
  
• Click OK in the pop-up window that appears to warn you that files in the html-template directory will be deleted or overwritten.
  
  Note: If you’ve customized index.template.html to do something like pass in flashvars to the application, you will need to reenter that information in the template file.
  
  
• Select Project→Clean.
  
  
• Take a look at the bin-debug folder again. You should no longer see the history folder.

When you clean a project, all of the files in the bin-debug folder are deleted and then built again from scratch.