About the wrapper

A simple wrapper is responsible for embedding the application’s SWF file in a web page, such as an HTML, ASP, JSP, or Adobe ColdFusion page. In more complex wrappers, you can enable features such as deep linking and Express Install. The wrapper can also ensure that users both with and without JavaScript enabled in their browsers can access your applications built with Flex. You can also use the wrapper to pass flashVars variables into your applications and to use the ExternalInterface API. These topics are described in Communicating with the wrapper.

There are several ways to create a wrapper:

  • Write a simple wrapper using the instructions in Create a custom wrapper.

  • Generate an HTML wrapper in Flash Builder. This wrapper includes features such as deep linking and Express Install support by default.

  • Use the html-wrapper Flex Ant task. For more information, see Using the html-wrapper task.

The mxmlc command-line compiler does not generate a wrapper. When using mxmlc, you generally write the wrapper manually or use the existing template as a guide. You can start out with a simple wrapper that just embeds your application’s SWF file. You can then add features such as deep linking and Express Install support to your wrapper.

About the Flash Builder wrapper

Adobe® Flash® Builder™ generates a wrapper that embeds your application built with Flex. The Flash Builder wrapper includes support for Express Install and deep linking by default, although you can disable these features or configure them to your specifications.

To view the wrapper generated by Flash Builder, run the current project. Flash Builder generates an HTML page in the same location as the project’s SWF file output. This directory also includes the wrapper’s supporting files such as the swfobject.js and playerProductInstall.swf files.

You can configure the wrapper by using the Flex Compiler properties dialog box in Flash Builder. Configuration settings include:

  • Enable or disable wrapper generation

  • Set the minimum required version of Flash Player

  • Use Express Install

  • Enable deep linking support

For more information, see Flex compiler options.

About the HTML template

Flex SDK includes an HTML template and supporting files in the flex_install_dir/templates/swfobject directory. For Flash Builder, these files are located in the install_dir/sdks/4.6.0/templates/swfobject directory. The file name is index.template.html.

For clients with scripting enabled, the template uses SWFObject 2 to embed the SWF file built with Flex. For clients with scripting disabled, the template provides a <noscript> section that uses the <object> and <embed> tags to embed the SWF file.

For deployment, rename the template to index.html or whatever filename fits your web site’s configuration. If you already have the HTML set up for your web site and are incorporating applications built with Flex into that site, then you can copy and paste the code from the template into your existing web site’s files. The template HTML also works with dynamic scripting code such as PHP, ASP, or JSP.

The template uses tokens, such as ${height} and ${title}. Flash Builder replaces these tokens with the appropriate values when it compiles a project. If you are editing the wrapper manually and deploying an application built with the SDK, then you manually replace these tokens with the appropriate values.

In many cases, the tokens set the values of parameters that are passed to the swfobject.embedSWF() JavaScript method, or are used in the <object> and <embed> tags in the <noscript> block of the template.

The following table describes the template tokens:

Token

Description

${application}

Identifies the SWF file to the host environment (a web browser, typically) so that it can be referenced by using a scripting language.

This token sets the value of the attributes.id and attributes.name properties in the SWFObject 2 logic.

${bgcolor}

Specifies the background color of the application. Use this property to override the background color setting specified in the application. This property does not affect the background color of the HTML page.

Valid formats for bgcolor are any #RRGGBB, hexadecimal, or RGB value.

This token sets the value of the params.bgcolor property in the SWFObject 2 logic.

${expressInstallSwf}

Enables Express Install for the embedded SWF file.

To enable Express Install, set this property to “playerProductIntsall.swf”. To disable Express Install, set this property to an empty string. If you enable Express Install, you must also deploy this SWF file with your application built with Flex.

This token sets the value of the xiSwfUrlStr property in the SWFObject 2 logic.

To toggle Express Install in Flex Builder, use the Use Express Install option on the Flex Compiler Properties dialog box.

${height}

Defines the height, in pixels, of the SWF file. Flash Player makes a best guess to determine the height of the application if none is provided.

The browser scales an object or image to match the height and width specified by the author.

You can set this value to a fixed number or a percentage value; for example, '100' or '50%'.

Lengths expressed as percentages are based on the horizontal or vertical space currently available, not on the default size of the SWF file.

You can also set the height of an application by setting the height property of the <s:Application> tag in an MXML file.

This token sets the value of the heightStr property in the SWFObject 2 logic.

${swf}

Specifies the location of the SWF file.

This token sets the value of the swfUrlStr property in the SWFObject 2 logic.

${title}

The title of the HTML page. This value appears in the browser’s title bar when the user requests the HTML page. The default value supplied by Flash Builder is the name of the application.

${useBrowserHistory}

Enables deep linking for the embedded SWF file.

To enable deep linking, set this property to “--”. To disable deep linking, remove the token and the <script> tags that follow it.

If you enable deep linking, youmust also deploy the files in the /templates/swfobject/history file with your application built with Flex.

To toggle deep linking in Flex Builder, use the Enable Integration with Browser Navigation option on the Flex Compiler Properties dialog box.

${version_major}

The required major version number of Flash Player. For example, 10. This token is one part of the swfVersionStr property in the SWFObject 2 logic. It is used for Express Install.

The value of this token is set in Flash Builder’s Flex Compiler Properties dialog box.

${version_minor}

The required minor version number of Flash Player. For example, 0. This token is one part of the swfVersionStr property in the SWFObject 2 logic. It is used for Express Install.

The value of this token is set in Flash Builder’s Flex Compiler Properties dialog box.

${version_revision}

The required revision version number of Flash Player. For example, 162. This token is one part of the swfVersionStr property in the SWFObject 2 logic. It is used for Express Install.

The value of this token is set in Flash Builder’s Flex Compiler Properties dialog box.

${width}

Defines the width, in pixels, of the SWF file. Flash Player makes a best guess to determine the width of the application if none is provided.

Browsers scale an object or image to match the height and width specified by the author.

You can set this value to a fixed number or a percentage value. For example, '100' or '50%'.

Lengths expressed as percentages are based on the horizontal or vertical space currently available, not on the natural size of the SWF file.

You can also set the width of an application by setting the width property of the <s:Application> tag in an MXML file.

This token sets the value of the widthStr property in the SWFObject 2 logic.

About SWFObject 2

SWFObject 2 is a standards-based library that embeds SWF files in HTML pages. It abstracts implementation details about Plugin detection, embedding, and other features so that you only need to call a single method to embed your SWF file. The default template included with Flex SDK and Flash Builder embeds the SWFObject 2 functionality with the following <script> tag:

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

To embed a SWF file built with Flex, the HTML wrapper creates a number of properties and objects, and then passes them to the swfobject.embedSWF() method.

The embedSWF() method has the following signature:
embedSWF( 
    swfUrlStr:String,  
    replaceElemIdStr:String,  
    heightStr:String,  
    widthStr:String,  
    swfVersionStr:String,  
    xiSwfUrlStr:String,  
    flashvars:Object,  
    params:Object,  
    attributes:Object 
)

The following is an example of the embedSWF() method in an HTML wrapper:

swfobject.embedSWF("TestProject.swf", "flashContent","100%", "100%", "10.0.0", "playerProductInstall.swf", flashvars, params, attributes);
You set the values of several of these arguments in the HTML wrapper’s script prior to passing them to the embedSWF() method. The following table describes these arguments.

Argument

Description

swfUrlStr

Defines the location of the application built with Flex. In most cases, this is the name of the output SWF file. If you use Flash Builder to generate a wrapper, the default value is “project_name.swf”.

replaceElemIdStr

The name of the alternative content that appears if Flash Player is not available.

You define the alternative content in a <div> tag. For an example, view the source of HTML wrapper that is generated by Flash Builder.

heightStr

The height of the application built with Flex.

If you use Flash Builder to generate a wrapper, this argument is the value of the {height} token.

widthStr

The width of the application built with Flex.

If you use Flash Builder to generate a wrapper, this argument is the value of the {width} token.

swfVersionStr

The minimum version of Flash Player that is required to run the application built with Flex. The default value is “10.0.0”. Set this property to “0” to disable version detection.

If you use Flash Builder to generate a wrapper, this value is made up of the {version_major}, {version_minor}, and {version_revision} tokens.

xiSwfUrlStr

Enables Express Install. Set this argument to the location of the playerProductInstall.swf file. The default value is “playerProductInstall.swf”. This SWF file is in the same directory as the HTML wrapper. If you deploy it to another location, change the value of the xiSwfUrlStr argument to the new path.

To disable Express Install, set the value of this argument to an empty string.

If you use Flash Builder to generate a wrapper, this argument is the value of the {expressInstallSwf} token.

flashvars

Adds flashVars variables to your template. To do this, attach dynamic properties to the flashvars object in the HTML template.

The following example adds firstName and lastName as dynamic properties to flashvars object:
var flashvars = {}; 
flashvars.firstName = "Nick"; 
flashvars.lastName = "Danger";

For more information about using flashVars variables in applications built with Flex, see Passing request data with flashVars properties.

params

Sets parameters for the SWF object. These properties typically define how it interacts with the HTML wrapper or appears in the browser.

You can set the values of the following properties by using the params argument:
  • menu

  • quality

  • scale

  • salign

  • wmode

  • bgcolor

  • base

  • flashvars

  • devicefont

  • allowscriptaccess

  • seamlessstabbing

  • allowfullscreen

  • allownetworking

For more information about these properties, see the property’s description in About the object and embed tags.

The following example adds several parameters to the params object in the HTML wrapper:
var params = {}; 
params.quality = "high"; 
params.bgcolor = "${bgcolor}"; 
params.allowscriptaccess = "sameDomain";

attributes

Sets attributes for the SWF object.

You can set the values of the following properties with the attributes argument:
  • id

  • name

  • class

  • align

The id and name properties are required.

For more information about these properties, see the property’s description in About the object and embed tags.

The following example adds the id, name, and align properties to the attributes object.
var attributes = {}; 
attributes.id = "${application}"; 
attributes.name = "${application}"; 
attributes.align = "middle";

For more information on SWFObject 2, see http://code.google.com/p/swfobject/wiki/documentation.

Using deep linking in the wrapper

Deep linking lets users navigate the history of their interactions within the application by using the browser’s Forward and Back buttons. Deep linking also lets users read and write to the browser’s address bar.

To enable or disable deep linking in the Flash Builder wrapper:
  1. Select Project > Properties.

  2. Select Flex Compiler from the list on the left of the Project Properties dialog box.

  3. Select the Enable Integration With Browser Navigation option to enable deep linking. Deselect this option to disable deep linking.

  4. Click OK to save your changes.

When you deploy an application that uses deep linking, you must deploy the files in the /templates/swfobject/history directory with that application.

Using Express Install in the wrapper

The recommended method of ensuring that Flash Player can run the application on the client is to use Express Install. With Express Install, you can detect when users do not have the latest version of Flash Player, and you can initiate an update process that installs the latest version of the player. The updated Player can be installed from the Adobe website or from a local intranet site. When the installation is complete, users are directed back your website, where they can run your application.

Express Install runs a SWF file in the existing Flash Player to upgrade users to the latest version of the player. As a result, Express Install requires that Flash Player already be installed on the client, and that it be version 6.0.65 or later. The Express Install feature also relies on JavaScript detection logic in the browser to ensure that the player required to start the process exists. As a result, the browser must have JavaScript enabled for Express Install to work. If the player on the client is not new enough to support Express Install, you can display alternate content, redirect the user to the Flash Player download page, or initiate another type of Flash Player upgrade experience.

By default, Express Install is enabled in the wrapper generated by Flash Builder.

To enable or disable Express Install in Flash Builder:

  1. Select Project > Properties.

  2. Select Flex Compiler from the list on the left of the Project Properties dialog box.

  3. Select the Use Express Install option to enable Express Install. Deselect the option to disable Express Install.

  4. Click OK to save your changes.

When you deploy an application with a wrapper that supports Express Install, you must also deploy the playerProductInstall.swf file. This file is located in the /templates/swfobject directory.