Adobe Flex 3 Help

Customizing the template

When the web-tier compiler compiles an MXML file into a SWF file, it also generates an HTML wrapper that embeds that SWF file. The browser first loads the wrapper, which embeds the SWF file. This wrapper is generated from a template that is included in the web-tier compiler installation.

The template file is in the module_install_dir/templates folder. The default template is default.html.

You specify the location of the template in the compiler.conf configuration file by using the template property; for example:

template=default.html

For more information on editing the compiler.conf file, see Configuring the web-tier compiler.

The template uses several tokens as placeholders that the compiler replaces when it generates the final output. For example, the token ${swf} is replaced with the MXML file name (minus the MXML file extension).

You can customize the template, but you must adhere to several rules. The new template:

  • Must be a *.html file.
  • Must be in the module_install_dir/templates directory.
  • Must include at least the ${swf} token. You use this token to define the value of the movie parameter in the <object> tag and the value of the src attribute in the <embed> tag.
  • Must not use any external script or CSS files. For example, you cannot use code similar to the following in the template: 
    <script src="mysource.js"></script>

Limitations of the template

The web-tier compiler is not meant to be used in a production environment. The wrapper does not support the following features:

  • History management or deep linking
  • Player detection and deployment
  • Express Install

In addition, the template does not convert query string parameters to flashVars variables in the wrapper's <object> and <embed> tags. If you want to pass run-time data as a flashVars variable, you should hard-code it in the wrapper, or use some other method of inserting the values into the wrapper's <object> and <embed> tags.

Finally, you cannot include other script files or external CSS files in the template. The template must be a single flat file that embeds the Flex application. It can contain JavaScript or other client-side code.

In Internet Explorer version 6 and later, you must click somewhere in the browser's window before you can use the Flex application. You may be prompted to press the Spacebar or the Enter key to activate the control. This is because the wrapper returned by the web-tier compiler does not use an external JavaScript file to embed the SWF file. HTML wrappers that use external script files to embed SWF files do not exhibit this behavior. You cannot change this behavior because you cannot use external scripts in your template wrapper with the web-tier compiler.

For more information on HTML wrappers, see Creating a Wrapper.

About the template's tokens

The following table describes the tokens that you can use in the web-tier compiler's template:

Token

Description
${application}

Identifies the SWF file to the host environment (a web browser, for example) so that it can be referenced by using a scripting language such as VBScript or JavaScript in the wrapper.

This token is used by the id property of the <object> tag and the name property of the <embed> tag.
${bgcolor}

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

Valid format for bgcolor is any #RRGGBB, hexadecimal, or RGB value.

The Application container's style uses an image as the default background. This image obscures any background color settings that you might make. Therefore, to make the value of the {$bgcolor} token be displayed properly, you must clear the Application container's backgroundImage style property. To do this, you can set it to the value of a space character in the MXML source file, as the following example shows:

<mx:Style> Application { backgroundImage: " "; } </mx:Style>
$(height)

Defines the height of the application. The default value is 100%. You set the default value in the compiler.conf file. If this value is set in the MXML file, then the web-tier compiler uses that value.

This token is used by the height properties of the <object> and <embed> tags.

$(swf)

Defines the name of the MXML file, minus the extension. For example, if the MXML file is named Main.mxml, the web-tier compiler inserts Main where this token occurs.

This token is used by the movie parameter of the <object> tag and the src property of the <embed> tag.
$(width)

Defines the width of the application. The default value is 100%. You set the default value in the compiler.conf file. If this value is set in the MXML file, then the web-tier compiler uses that value.

This token is used by the width properties of the <object> tag and <embed> tags.