Create a custom wrapper

You can write your own wrapper for your SWF files rather than use the wrapper generated by Flash Builder. Your own wrapper can be simple HTML, or it can be a JavaServer Page (JSP), a PHP page, an Active Server Page (ASP), or anything that can return HTML that is rendered in your client’s browser. Typically, you integrate wrapper logic into your website’s own HTML templates.

You can create a simple wrapper that uses SWFObject 2 but not other features such as deep linking and Express Install. You do this by creating an HTML file that imports the swfobject.js file. You then call the swfobject.embedSWF() method. The following is a simple wrapper that uses SWFObject 2:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- saved from url=(0014)about:internet -->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <title>wrapper/SimpleSwfObjectWrapper.html</title>
        <script type="text/javascript" src="swfobject.js"></script>
        <script type="text/javascript">
            var swfVersionStr = "0";
            var xiSwfUrlStr = "";
            var flashvars = {};
            var params = {};
            params.quality = "high";
            params.bgcolor = "#ffffff";
            params.allowscriptaccess = "sameDomain";
            var attributes = {};
            attributes.id = "TestProject";
            attributes.name = "TestProject";
            attributes.align = "middle";
            swfobject.embedSWF(
                "TestProject.swf", "flashContent",
                "100%", "100%",
                swfVersionStr, xiSwfUrlStr,
                flashvars, params, attributes);
        </script>
    </head>
    <body>
        <div id="flashContent"/>
   </body>
</html>

This wrapper sets the swfVersionStr property to 0 and the xiSwfUrlStr property to an empty string. Doing this disables Express Install and deep linking functionality. These features improve the user experience and should be omitted only after careful consideration.

When you deploy this example wrapper, you must also deploy the swfobject.js file from the /templates/swfobject directory.

To write an even simpler wrapper, you can use just the <object> and <embed> tags rather than the SWFObject 2 JavaScript code.

A basic wrapper consists of the following files:

HTML page
This is the file that the client browser requests directly. It typically defines two possible experiences (one for users with JavaScript enabled and one for users without JavaScript enabled). This page also references a separate JavaScript file in a <script> tag.

JavaScript file
The JavaScript file referenced by the <script> tag in the HTML page defines the following:
  • <object> tag This tag embeds the SWF file for Internet Explorer.

  • <embed> tag This tag embeds the SWF file for Netscape-based browsers.

In the default HTML template, the JavaScript file is named swfobject.js. This JavaScript file contains the SWFObject 2 logic. If you want to create your own basic wrapper, you can load a different JavaScript file that only has <object> and <embed> tags in it.

The client first requests the HTML page. If the user’s browser has JavaScript enabled, the HTML page then loads the JavaScript file. The JavaScript file embeds the application’s SWF file.

To make your application respond immediately without user interaction, use a <script> tag to load the JavaScript file that contains the embedding logic. Do not write the embed logic directly in the HTML file. Controls that are directly loaded by the embedding page require activation before they will run in Microsoft Internet Explorer 6 or later. If you load the controls directly in the HTML page, users will be required to activate those controls before they can use them by clicking on the control or giving it focus. This is undesirable because you want your application to run immediately when the page loads, not after the user interacts with the control.

The following example illustrates a typical series of requests that a JavaScript-enabled client browser makes when requesting a simple HTML wrapper:

The following example shows a simple HTML page and JavaScript file that embeds an application named MyApp:

<!-- index.html --> 
<!-- saved from url=(0014)about:internet --> 
<html> 
    <body> 
        <script src="mysource.js"></script> 
    </body> 
</html> 
  
<!-- mysource.js --> 
document.write("<object id='MyApp' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' height='100%' width='100%'>"); 
document.write("<param name='movie' value='MyApp.swf'/>"); 
document.write("<embed name='MyApp' src='MyApp.swf' height='100%' width='100%'/>"); 
document.write("</object>");

The first line in the index.html page is called the Mark of the Web (MOTW). Adding the MOTW to your wrapper is optional. However, if you do not add the MOTW to your wrapper, your application might not open in the expected security zone within Internet Explorer. The following example MOTW forces Internet Explorer to open the page in the Internet zone:

<!-- saved from url=(0014)about:internet -->

In general, add a MOTW when you are previewing pages locally before publishing them on a server. For more information about the MOTW, see http://msdn.microsoft.com/en-us/library/ms537628%28VS.85%29.aspx.

To support browsers that do not have scripting enabled, you can add a <noscript> block to your simple wrapper. The tags in this block of code usually mirror the output of the document.write() methods in the embedded JavaScript file. The following example adds the <noscript> block:

<!-- index.html --> 
<!-- saved from url=(0014)about:internet --> 
<html> 
    <body> 
        <script src="mysource.js"></script> 
        <noscript> 
            <object id='MyApp' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' 
                height='100%' width='100%'> 
                <param name='src' value='MyApp.swf'/> 
                <embed name='MultipleButtons' src='MyApp.swf' height='100%' 
                    width='100%'/> 
            </object> 
        </noscript> 
    </body> 
</html>

This simple wrapper does not include any assurances that the client can run the application. If they do not have a minimum version of Flash Player, their attempt to run this application will fail and they might be prompted to upgrade. The upgrade experience is considerably better with Express Install. If the user’s Player does not meet the minimum requirements, the new player is automatically installed for them. You add Express Install by editing your wrapper. For more information, see Adding Express Install to a custom wrapper.

With a generic wrapper, a user who clicks the Back and Forward buttons in their browser navigates the HTML pages in the browser’s history and not the history of their interactions within the application. Deep linking lets users navigate their interactions with the application by using the Back and Forward buttons in their browser. You can add deep linking by editing your wrapper and deploying additional files with it. For more information, see Adding deep linking to a custom wrapper.

For more information about using the <object> and <embed> tags, see About the object and embed tags.

About customizing a wrapper

Use the following guidelines when you create a custom wrapper.

  • You can use the HTML template in the /templates/swfobject directory as a guide to adding new features to the wrapper. For information about the template, see About the HTML template.

  • You must embed the SWF file and not the MXML file of an application built with Flex. Set the value of the src property to mxml_filename.swf.

    The following example defines the src property of the <object> tag for an MXML application called MyApp.mxml:

    <param name='src' value='MyApp.swf'>

    The <embed> tag uses the src property to define the source of the SWF file:

    src='MyApp.mxml.swf'
  • Do not include periods or other special characters in the id and name properties of the <object> and <embed> tags. These tags identify the SWF object on the page, and you use them when you use the ExternalInterface API. This API lets Flex communicate with the wrapper, and vice versa. For more information about using the ExternalInterface API, see Communicating with the wrapper.

  • Do not put the contents of the JavaScript file directly in the HTML page. This causes Internet Explorer to prompt the user before enabling Flash Player. If the client has “Disable Script Debugging (Internet Explorer)” unchecked in Internet Explorer’s advanced settings, the browser still prompts the user to load the ActiveX plug-in before running it.

  • If you use both the <object> and the <embed> tags in your custom wrapper, use identical values for each attribute to ensure consistent playback across browsers. For more information about the <object> and the <embed> tags, see About the object and embed tags.

  • To add support for deep linking, follow the instructions in Adding deep linking to a custom wrapper.

  • To add support for Flash Player detection, follow the instructions in Adding Express Install to a custom wrapper.

  • When using Flash Builder, the default wrapper includes deep linking and Express Install support. You can disable one or both of these features by using the Compiler Properties dialog box. You can also use this dialog box to set the minimum required version of Flash Player.

Adding Express Install to a custom wrapper

Express Install uses the existing Flash Player to upgrade users to the latest version of the Player when it is required for viewing content. Express Install requires that the user has Flash Player 6.0.65 or later installed on a Mac or Windows operating system. Express Install also requires the user to have JavaScript enabled in the browser.

Support for Express Install is included in the wrapper that is generated by Flash Builder. You can enable or disable it in Flash Builder prior to generating the wrapper in Flash Builder’s Flex Compiler Properties dialog box.

If you write your own custom wrapper and want to use Express Install, you must add support for it manually. Adobe recommends that you use the Express Install functionality in the wrapper template at /templates/swfobject directory as a base.

Adding Express Install support from the wrapper template involves adding JavaScript to your main wrapper file, as well as deploying the swfobject.js file. In addition, you must deploy the playerProductInstall.swf file with your application. This file is located in the SWF file’s output directory when you build a project in Flash Builder, or the /templates/swfobject directory if you use the SDK.

You can also use the Flash Player Detection Kit to add Express Install support to your custom wrapper.

Adding deep linking to a custom wrapper

Support for deep linking, also known as history management, is included by default in the HTML that is wrapper generated by Flash Builder. If you write your own wrapper, however, you must add it manually or use the HTML template file as a base.

To add deep linking support, you reference the history.js and history.css files in your wrapper. The following sample wrapper references these files in the /history subdirectory:
<!-- index.html --> 
<!-- saved from url=(0014)about:internet --> 
<html> 
<body> 
    <link rel="stylesheet" type="text/css" href="history/history.css" /> 
    <script type="text/javascript" src="history/history.js"></script> 
    <script src="mysource.js"></script> 
</body> 
</html>

The history.js file records actions for deep linking. The history.css file defines styles for the history files. To support deep linking in your application built with Flex, you must deploy the following files with your wrapper:

  • history.js

  • historyFrame.html

  • history.css

These files are generated by Flash Builder in the /history directory. If you are using the SDK, you can get these files from the /templates/swfobject/history directory.

If you do not add deep linking support to your wrapper, you cannot use the BrowserManager class in applications built with Flex.