Using the html-wrapper task

The html-wrapper Ant task generates files that you deploy with your applications. An HTML wrapper consists of a generated HTML page and a JavaScript file that defines embed logic. The output can also include files that support features such as deep linking and Express Install.

The html-wrapper task outputs the index.html and swfobject.js files for your application. The swfobject.js file defines the SWFObject 2 logic that embeds SWF files in HTML.

If you enable deep linking support, the html-wrapper task also outputs the deep linking files such as historyFrame.html, history.css, and history.js. If you enable express installation, the html-wrapper task also outputs the playerProductInstall.swf file.

You typically deploy these files, along with your application's SWF file, to a web server. Users request the HTML wrapper, which embeds the SWF file. You can customize the output of the wrapper and its supporting files after it is generated by Ant.

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

Supported attributes

The attributes of the html-wrapper task correspond to some of the arguments in the swfobject.embedSWF() method of the default HTML wrapper.

The following table describes the supported attributes of the html-wrapper task:

Attribute	Description
application	The name of the SWF object in the HTML wrapper. You use this name to refer to the SWF object in JavaScript or when using the ExternalInterface API. This value should not contain any spaces or special characters. This attribute sets the value of the `<embed>` tag's `name` attribute and the `<object>` tag's `id` attribute.
bgcolor	Specifies the background color of the application. Use this property to override the background color setting specified in the SWF file. This property does not affect the background color of the HTML page. This attribute sets the value of the `params.bgcolor` argument in the `embedSWF()` method. The default value is `white`.
`express-install=false\|true`	Determines whether to include Express Install logic in the HTML wrapper. When set to `true`, the Ant task copies the playerProductInstall.swf file to the output directory and referenced in the wrapper file. If you set this option to `true`, the `version-detection` option is also assumed to be `true`. For more information, see Using Express Install in the wrapper. The default value is `false`.
file	Sets the file name of the HTML output file. The default value is "index.html".
height	Defines the height, in pixels, of the SWF file. Adobe® Flash® Player makes a best guess to determine the height of the application if none is provided. This attribute sets the value of the third argument in the `embedSWF()` method. The default value is 400.
history	Set to `true` to include deep linking support (also referred to as history management) in the HTML wrapper. Set to `false` to exclude deep linking from the wrapper. When you set this attribute to true, Ant creates a history directory and stores the historyFrame.html, history.css, and history.js files in it. The default value is `false`. For more information on deep linking, see Deep linking.
output	Sets the directory that Ant writes the generated files to. If you do not set the value of this option, Ant creates the wrapper files in the same directory as the build file.
swf	Sets the name of the SWF file that the HTML wrapper embeds (for example, Main). Do not include the *.swf extension; the extension is appended to the name for you. This attribute sets the value of the attributes.name and attributes.id arguments in the `embedSWF()` method. It also sets the value of the first argument in that method call. This SWF file does not have to exist when you generate the HTML wrapper. It is used by SWFObject 2 to point to the location of the SWF file at deployment time.
title	Sets the value of the `<title>` tag in the head of the HTML page. The default value is `Flex Application`.
`version-detection=true\|false`	Determines whether to include version detection logic in the wrapper. Set this value to `false` to disable all Player version logic in the HTML wrapper. The default value is `true`.
version-major	Sets the value of the `swfVersionStr` variable in the HTML wrapper. The default value is 10. The value of this attribute only matters if you include version detection in your wrapper by setting the `template` attribute to `express-installation` or `client-side-detection`.
version-minor	Sets the value of the `swfVersionStr` variable in the HTML wrapper. The default value is 0. The value of this attribute only matters if you include version detection in your wrapper by setting the `template` attribute to `express-installation` or `client-side-detection`.
version-revision	Sets the value of the `swfVersionStr` variable in the HTML wrapper. The default value is 0. The value of this attribute only matters if you include version detection in your wrapper by setting the `template` attribute to `express-installation` or `client-side-detection`.
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. This attribute sets the value of the fourth argument in the `embedSWF()` method. The default value is 400.

Required attributes

The html-wrapper task requires the swf attribute. If you specify only the swf attribute, the default wrapper will have the following settings:

title="Flex Application" 
swfVersionStr = "10.0.0"; 
params.quality = "high"; 
params.bgcolor = "white"; 
params.allowscriptaccess = "sameDomain"; 
params.allowfullscreen = "true"; 
attributes.align = "middle"; 
height="400" 
width="400"

Be sure to use the filename only and not the filename plus extension when specifying the value of the swf attribute. The html-wrapper task appends .swf to the end of its value before passing it to the embedSWF() method.

For example, do this:

swf="Main"

Do not do this:

swf="Main.swf"

Unsupported options

The html-wrapper task does not support all properties used by SWFObject 2 to embed a SWF file in an HTML wrapper. Parameters you cannot set include quality, allowScriptAccess, classid, pluginspage, and type.

Example

The following example project includes a wrapper target that uses the html-wrapper task to generate a wrapper with deep linking, Player detection, and Express Install logic. This target (wrapper) also sets the height and width of the SWF file. The project also includes a clean target that deletes all the files generated by the wrapper target.

<?xml version="1.0" encoding="utf-8"?> 
<!-- myWrapperBuild.xml --> 
<project name="My Wrapper Builder" basedir="."> 
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/lib/flexTasks.jar"/> 
    <property name="FLEX_HOME" value="C:/p4/flex/flex/sdk"/> 
    <property name="APP_ROOT" value="c:/temp/ant/wrapper"/> 
    <target name="wrapper"> 
        <html-wrapper 
            title="Welcome to My Flex App" 
            file="index.html" 
            height="300" 
            width="400" 
            application="app" 
            swf="Main" 
            history="true" 
            express-install="true" 
            version-detection="true" 
            output="${APP_ROOT}"/> 
    </target> 
    <target name="clean"> 
        <delete> 
            <!-- Deletes playerProductInstall.swf --> 
            <fileset dir="${APP_ROOT}" 
                includes="playerProductInstall.swf" 
                defaultexcludes="false"/> 
            <!-- Deletes the swfobject.js file --> 
            <fileset dir="${APP_ROOT}" includes="*.js" defaultexcludes="false"/> 
            <!-- Deletes the previously-generated HTML wrapper file --> 
            <fileset dir="${APP_ROOT}" includes="*.html" defaultexcludes="false"/> 
            <!-- Deletes the history files --> 
            <fileset dir="${APP_ROOT}/history" includes="*.*" defaultexcludes="false"/> 
        </delete> 
    </target> 
</project>