Using Flex/Deploying application / Creating a wrapper/About the wrapper

A simplewrapper 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 linkingand 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 passflashVars variables into your applications and to use the ExternalInterface API. These topics are describedinCommunicating with the wrapper.

一个简单的包装器用于在一个web页面中嵌入应用程序的SWF文件，这些web页面包括HTML，JSP，或者Adobe ColdFusion页面。在一些更复杂的包装器中，你可以开启深度链接和快速安装的特性。包装器也可以确保用户浏览器支持不支持JavaScript都能够使用户获取你由Flex建立的应用程序。同样你也可以使用包装器向你的应用程序传递flashVars变量并条用ExternalInterface API。

There are several ways to create a wrapper:

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

• 使用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.

• 用Flash Builder生成一个HTML包装器。这个包装器默认包含深度链接和快速安装的特性。
  

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

• 使用html-wrapper Flex Ant task。详情请见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.

Mxmlc 命令行编译器也可以生成包装器。当你使用mxmlc，通常手动编写包装器或者使用既存的模板作为参考。你可以一个仅有嵌入你的应用程序的SWF文件功能的包装器开始。

然后再往你的包装器中添加如深度链接和快速安装支持等特性。

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.

Adobe® Flash® Builder™生成一个可以嵌入由Flex建立的应用程序。Flash Builder生成的包装器默认包含快速安装支持和深度链接功能，不过你可以禁用这些功能或者根据你的规范来配置它们。

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.

如果你想查看Flash Builder生成的包装器，运行当前项目(...)。Flash Builder在与项目SWF文件相同的路径内生成一个HTML页面。这个路径也包括包装器的支持文件如swfobject.js和playerProductInstall.swf文件。

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

你可以通过Flex Compiler属性对话框进行配置包装器。

• Enable or disable wrapper generation

• 启用或者禁用包装器生成
  

• Set the minimum required version of Flash Player

• 设置Flash Player最低版本
  

• Use Express Install

• 使用快速安装
  

• Enable deep linking support

• 启用深度链接支持
  

For more information, see Flexcompiler 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 theinstall_dir/sdks/4.6.0/templates/swfobjectdirectory. The file name is index.template.html.

Flex SDK在Flex安装路径/templates/swfobject路径下包含一个HTML末班和支持文件。对于Flash Builder，这些文件位于安装路径/sdks/4.6.0/templates/swfobject路径下。该HTML模板文件的名字是index.template.html。

For clients with scripting enabled, the template uses SWFObject2 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.

对于启用脚本的用户，该模板使用SWFObject2来嵌入Flex下建立的SWF文件。对于禁用脚本的用户，该模板提供了一个<noscript>部分使用<object>和<embed>标签来嵌入SWF文件。

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.

对于部署，重命名这个模板为index.html或者其他任何文件名来配合你网站的配置。如果你已经为你的站点创建了HTML并将由Flex生成的应用程序整合到该站点，你只需要从模板中拷贝和粘贴相应代码到你已经存在的web站点文件中。这个模板HTML同样可以与PHP，ASP或者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.

该模板使用诸如${height} 、 ${title}的标记。Flash Builder在编译一个项目时会以适当的值来替换这些标记。如果你正在手动的编辑包装器并部署一个由SDK建立的应用程序，你需要手动将这些标记替换成适当的值。

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.

很多情形下，这些标记设置传递给JavaScript(文件)的swfobject.embedSWF()方法参数值，或者被用在模板中<noscript>块下的<object>和<embed>标签。

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 andattributes.name properties in the SWFObject 2 logic.

为主机环境识别SWF文件以便被脚本语言引用。这个标记在SWFObject2中的逻辑方法中设置attributes.id和attribute.name。

${bgcolor}

Specifies the background color of the application. Use this property to overridethe 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 propertyin the SWFObject 2 logic.

指定应用程序的背景颜色。使用这个属性可以覆盖在应用程序中设定的背景颜色。这个属性不影响HTML页面的背景颜色。有效的bgcolor格式为#RRGGBB，十六进制，或者RGB值。这个标记在SWFObject2的逻辑方法中设置params.bgcolor的值。

${expressInstallSwf}

Enables Express Install for the embedded SWF file.

To enable Express Install, set this property to “playerProductIntsall.swf”. To disable Express Install, set thisproperty to an empty string. If you enable Express Install, youmust 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.

为嵌入的SWF文件启用快速安装功能。启用快速安装，设置这个属性值为“playerProductIntsall.swf”。禁用这个功能，设置这个属性为空。如果你启用快速安装，你需要为你的应用程序部署playerProductIntsall.swf。这个标记在SWFObject2的逻辑方法中设置xiSwfUrlStr属性的值。

在Flex Builder下 触发快速安装功能，需要在Flex Compiler属性对话框中使用Use Express Install选项。

${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 propertyof the <s:Application> tag in an MXML file.

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

规定SWF的高度，单位为像素。如果没有指定Flash Player会对该应用的高度做出一个最好的尝试。浏览器通过缩放一个对象或者图片来符合应用程序作者的指定宽和高。你可以指定一个固定的值或者一个百分值，如‘100’或者‘50%’。由百分比表示的长度是基于当前的可用的水平或垂直空间，而不是基于SWF文件默认的尺寸。你也可以通过在一个MXML文件中设定<s:Application>标签的height属性来设置一个应用程序的高。

这个标记在SWFObject2逻辑方法中设置heightStr属性。

${swf}

Specifies the location of the SWF file.

This token sets the value of the swfUrlStr propertyin the SWFObject 2 logic.

指定SWF文件的路径。这个标记在SWFObject2的逻辑方法内用来设置swfUrlStr属性的值。

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

HTML页面的标题。当你请求这个HTML页面时该值出现在浏览器的标题栏。Flash Builder提供的默认值为应用程的名字。

${useBrowserHistory}

Enables deep linking for the embedded SWF file.

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

If you enable deep linking, you must 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.

为嵌入的SWF文件启用深度链接。启用深度链接，将该值设为“--”。禁用深度链接，移除这个标记还有该标记后面的<script>标签。如果你启用深度链接，你必须为你的应用程序部署这些文件(history.css，history.js等)到/templates/swfobject/history路径下。在Flex Builder中触发深度链接，在Flex Compiler属性对话框内使用Integration with Browser Navigation 选项。

${version_major}

The required major version number of Flash Player.This token is one part of theswfVersionStr 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.

必须的Flash Player最高版本号。这个标记属于SWFObject2逻辑函数内swfVersionStr属性的一部分。它用于快速安装。这个值在Flex Compiler属性对话框中设置。

${version_minor}

The required minor version number of FlashPlayer. This token is one part of theswfVersionStr property in the SWFObject 2 logic. It is used for Express Install.

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

必须的最低版本号。这个标记属于SWFObject2逻辑函数内swfVersionStr属性的一部分。它用于快速安装。这个值在Flex Compiler属性对话框中设置。

${version_revision}

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

Thevalue of this token is set in Flash Builder’s Flex Compiler Propertiesdialog box.

必须的修订版本号。…………………………

${width}

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

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

Youcan set this value to a fixed number or a percentage value. Forexample, '100' or '50%'.

Lengthsexpressed as percentages are based on the horizontal or verticalspace currently available, not on the natural size of the SWF file.

Youcan also set the width of an application by setting the width propertyof the <s:Application> tag in an MXML file.

Thistoken sets the value of the widthStr property inthe SWFObject 2 logic.

参见${height}。

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:

SWFObject2是一个基于标准的库用来在HTML页面中嵌入SWF文件。SWFObject2将插件检测，嵌入，和其他功能的细节进行了抽象，所以你只需要条用一个简单的方法来嵌入你的SWF文件。Flex SDK和Flash Builder 自带的默认模板通过以下的<script>标签来嵌入SWFObject2的功能。

<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 theswfobject.embedSWF() method.

为了嵌入由Flex创建的SWF，HTML包装器生成了一些属性和对象，让后把它们(作为参数)传递给swfobject.embedSWF()方法。

The embedSWF() method has the following signature:

embedSWF()方法有如下的签名:

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() methodin an HTML wrapper:

下面是HTML 包装器中embedSWF()方法的使用例子：

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 theembedSWF() method.The following table describes these arguments.

你在传给embedSWF()方法之前现在HTML包装器的脚本中对它们进行赋值。下面的表格描述了这些参数。

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

规定由Flex建立的应用程序的路径。大多情况下，这是输出的SWF文件的名字。如果你使用Flash Builder来生成一个包装器，默认值为“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.

Flash Player不可用时替代的内容。用<div>标签来定义一个替换的内容。

heightStr

The height of the application built withFlex.

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

应用的高度。如果你使用Flash Builder生成一个包装器，这个参数是{height}标记的值。

widthStr

The width of the application built withFlex.

If you use Flash Builder to generate a wrapper, thisargument 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.

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

运行Flex生成的应用程序所需的Flash Player最低版本。默认值为10.0.0。将该属性设为0则禁用版本检测。如果你使用Flash Builder来生成一个包装器，这个值由{ {version_major}, {version_minor},和{version_revision}标记组成。

xiSwfUrlStr

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

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

If you use Flash Builderto 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 informationabout using flashVars variables in applications built with Flex, seePassing request data with flashVars properties.

为你的模板添加flashVars变量。为了实现这个功能(上一句)，需要在HTML模板中为flashvars对象添加动态属性。下面的例子为flashvars对象添加firstName和lastName作为动态属性。

params

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

为SWF对象设置参数。这些属性通常用来定义SWF如何同HTML包装器交互或者呈现在浏览器中。

You can set the values of the followingproperties by using the params argument:

• menu

• quality

• scale

• salign

• wmode

• bgcolor

• base

• flashvars

• devicefont

• allowscriptaccess

• seamlessstabbing

• allowfullscreen

• allownetworking

Formore information about these properties, see the property’s descriptionin About the object and embed tags.

The following example addsseveral parameters to the params object in theHTML wrapper:

var params = {}; params.quality = "high"; params.bgcolor = "${bgcolor}"; params.allowscriptaccess = "sameDomain";

attributes

Sets attributes for the SWF object.

为SWF对象设置属性。

Youcan set the values of the following properties with the attributes argument:

• id

• name

• class

• align

The id and name propertiesare required.

id和name是必须的。

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

The following example addsthe id, name, and align propertiesto 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

Deeplinking lets users navigate the history of their interactions with in 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 ProjectProperties 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.

当你部署一个使用深度链接的应用时，你必须为该应用部署路径/templates/swfobject/history下的文件。

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. WithExpress Install, you can detect when users do not have the latestversion of Flash Player, and you can initiate an update processthat installs the latest version of the player. The updated Playercan be installed from the Adobe website or from a local intranetsite. When the installation is complete, users are directed backyour website, where they can run your application.

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

By default, Express Install is enabled in the wrapper generatedby 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 ProjectProperties 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 ExpressInstall, you must also deploy the playerProductInstall.swf file.This file is located in the /templates/swfobject directory.