Creating a wrapper

You typically embed an application built with Flex as a SWF file in an HTML page. The HTML page often includes script or external files that provide other functionality. Collectively, the HTML page and other external files are known as the wrapper.

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:

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 HTML template

Flex SDK includes an HTML template and supporting files in the flex_install_dir/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}. 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.

 
${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.

${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 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.

 
${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.

 
${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.

 
${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.

 
${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 embeds the SWFObject 2 functionality with the following tag: