Welcome to Particletree!

Introduction

The following feature was written to serve two purposes: to provide an easy-to-follow introduction to the Flash / JavaScript Integration Kit and to demonstrate a method for using Flash as an animation underlayer for enhancing web applications. While I have fallen in love with a variety of JavaScript animation libraries developed in the wake of the Web 2.0 buzz, I have never found an implementation that makes me feel like it could truly replace the animation abilities inherent within the Flash player.

While the complexity of the JavaScript files needed to create visual effects consistently across browsers grows ridiculously, I’m finding myself yearning for compromise. Programs like Measure Map and Yahoo Maps Beta show us that the great dynamic promise of Ajax is definitely compatible with the interactive capabilities of Flash. The following implementation illustrates a way to let JavaScript do what it does best—manipulate DOM and make calls to the server—and Flash do what it does best—dance.

See It in Action

In this demo we are using Flash as an animation underlayer to enhance an HTML form. Click on the text fields to see the Flash movie clip resize and move to the appropriate DIV.

Using CSS, we are absolutely positioning a container element over the flash animation layer that holds our SWF. Using JavaScript, we can make sure our Flash SWF is always the same size as our container DIV and, thanks to Peter-Paul Koch’s findPos functions, we can communicate the position of DOM objects we want to highlight with our Flash animation.

Note : The F/J Integration Kit is meant to be used with Flash MX (7) or lower. While you could follow along in a Flash 8 environment (the demos created here were actually created in Flash 8), you’d probably be better off using some of the new fancy pants features that are included in the new platform. If you want to get Flash and JavaScript talking in Flash 8, definitely check out the work done by Paul Colton on AFLAX. It’s good stuff.

How It Works

To follow along, download the F/J Integration Kit from Macromedia’s web site and download the source files for the Flash Underlayer Demo from ours. In this tutorial we’ll go over how to install the Kit and then explain all of the scripts used to create the Flash Animation Underlayer demo.

Installing the Integration Kit

While Macromedia states in their documentation that the “Installation of the JavaScript and Flash Integration Kit is very straightforward,” I could definitely see some places where a few Google queries might be needed to get started. For the most part, there are three steps to getting yourself set up to get Flash and JavaScript talking to one another with the Integration Kit.

1. Download the files.

2. Place JavaScriptFlashGateway.js and JavaScriptFlashGateway.swf in your web directory (I place them in a folder called “scripts”).

3. Install library files into your Flash Authoring or Flex classpath.

Oh, vile Step 3! What and where in the heck is the Flash classpath? For that answer, we’ll need to go to the official Flash MX documentation:

Flash has two classpath settings: a global classpath and a document-level classpath. The global classpath applies to external AS files and to FLA files, and is set in the Preferences dialog box (Edit > Preferences > ActionScript > ActionScript 2.0 Settings).

By default, the global classpath contains one absolute path and one relative path. The absolute path is denoted by $(LocalData)/Classes in the Preferences dialog box. The location of the absolute path is shown here:

(Windows 2000 or Windows XP) \Documents and Settings\user\Local Settings\ Application Data\Macromedia\Flash MX 2004\language\Configuration\Classes

(Windows 98) \Windows\Application Data\Macromedia\Flash MX 2004\ language\ Configuration\Classes

(Macintosh OS X) Hard Drive/Users/Library/Application Support/Macromedia/Flash MX 2004/language/Configuration/Classes

Global and Document-Level Classpaths

What we’re going to do is copy the folder “com” in “/source/flash/actionscript”, which contains the following directory structure:

com/macromedia/javascript/JavaScriptProxy.as
com/macromedia/javascript/JavaScriptSerializer.as

into the appropriate folders listed above for our operating system. And with that, we move on to the code.

Hackery

Before we can create an animation underlayer, we’ll need to tweak the F/J Integration Kit’s JavaScript a bit. Because the Kit needs to create the XHTML markup for inserting the Flash SWF for us, it doesn’t always set the presentation parameters we might need. For the Flash Animation Underlayer, we want our SWF’s background to be transparent and prevent scaling. Just open up the JavaScriptFlashGateway.js and do the following:

Around Line 182 you want to comment out

//flashTag += '<param name="bgcolor" value="#'+this.bgcolor+'"/>';

And add

flashTag += '<param name="wmode" value="transparent"/>'; //added
flashTag += '<param name="scale" value="noscale"/>'; //added  

And then go to the else statement around Line 196 you want to comment out

//flashTag += 'bgcolor="#'+this.bgcolor+'" ';

And add

flashTag += 'scale="noscale" '; //added
flashTag += 'wmode="transparent" '; //added

And done.

CSS and XHTML

Next, we’ll set up our markup and CSS to layer our XHTML content over our Flash Animation layer. In the head, we include the JavaScriptFlashGateway and our JavaScript file.

<script type="text/javascript" src="scripts/JavaScriptFlashGateway.js"></script>
<script type="text/javascript" src="scripts/underlayer.js"></script>

In the body, we need two DIVs. I’ve named one container for our XHTML information and followed it with another called flash.

<div id="container">
// All your XHTML Stuff goes in here ...
</div><div id="flash">
<script type="text/javascript">
    var uid = new Date().getTime();
    var flashProxy = new FlashProxy(uid, 'scripts/JavaScriptFlashGateway.swf');
    var tag = new FlashTag('underlayer.swf', '100%', '100%'); 
    tag.setFlashvars('lcId='+uid);
    tag.write(document);
</script>
</div>

In our CSS file, the only required set of rules is to absolutely position our container in the top left corner of the browser.

#container{
    position:absolute;
    top:0;
    left:0;
    padding:50px 0 0 0;
    z-index:1000;
    width:600px;
}

Inside our container div, I’ve created the following HTML structure for our demo:

`<div id="box1" class="box">1</div>
<div class="field">
<label>Text</label>
<input onfocus="flashHighlight('box1');" />
</div>`

I know, I know. Obtrusive JavaScript alert, but for this tutorial’s purposes it makes it easier to explain what’s going on. This can be easily changed to something more “appropriate” later on. Basically, what we’re doing here is telling the browser that when the input field is onfocus or selected, we want to run a JavaScript function called flashHighlight on an element with an id of box1, which is our numbered DIV.

JavaScript

While the Flash SWF expands to 100% of the flash DIV, there’s no way for the DIV or the SWF to match the size of our container since it is absolutely positioned above our Flash layer. To make this adaptive, we’ll use some DOM manipulation to find the size of our container DIV and have our flash DIV match it.

    function resizeFlash(){
        var oContainer = document.getElementById('container');
        var oFlash = document.getElementById('flash');
        var cHeight = oContainer.offsetHeight + 'px';
        var cWidth = oContainer.offsetWidth + 'px';
        oFlash.setAttribute('style', 'height:' + cHeight + '; width:' + cWidth);
    }

The next function will tell an Actionscript function called “moveBeacon” to manipulate a Flash movieclip to match the size and position of whatever element we give it. In Flash, we will have a corresponding Actionscript capable of receiving all the parameters we’ve just set with JavaScript.

    function flashHighlight(ID){
        var obj = document.getElementById(ID);
        flashProxy.call('moveBeacon', findPosX(obj), findPosY(obj), obj.offsetWidth, obj.offsetHeight);
    }

Inside Flash

After opening the underlayer.fla file, you’ll notice two layers on your timeline—one called Actionscript and another called Movieclips. In the first frame of the Actionscript layer, you’ll see two lines of code that enable the talk between JavaScript and Actionscript:

//Allows AS to call JS functions

import com.macromedia.javascript.JavaScriptProxy; var proxy:JavaScriptProxy = new JavaScriptProxy();

//Allows JS to call AS functions
var proxy:JavaScriptProxy = new JavaScriptProxy(_root.lcId, this);

Since we want our movieclips not to scale proportionally with the stage (since its being manipulated dynamically with JavaScript), the following code is also present. Notice

//Prevent movieclips from resizing proportionally to stage size.
Stage.scaleMode = "noScale";
Stage.align = "TL";

You’ll also notice this frame is also the location of our moveBeacon function referenced in our JS file above.

//Move the beacon. Tell desired size of highlighter.
function moveBeacon(px,py,pw,ph){
    beacon._x = px;
    beacon._y = py;
    targetWidth = pw;
    targetHeight = ph;
}

This function moves a “beacon” movieclip to the desired locating and sets two variables (targetWidth and targetHeight) to the size of the DIV identified in our corresponding JavaScript function.

In the movieclip layer, there are two movieclips you’ll need to make this work. One is a blank one that must be named “beacon.” This can be placed anywhere on the stage. It will be the initial position our highlighter will go to when the SWF is loaded up. And we’ll also need another movieclip (a square or what have you) that will act as our highlighter. To make this quick, I’m using the following Actionscript on that movieclip.

onClipEvent (enterFrame) {
    //Find distance to beacon clip.
    dx = _root.beacon._x - _x;
    dy = _root.beacon._y - _y;    //Find difference between highligher size and desired size.
    dw = _root.targetWidth - _width;
    dh = _root.targetHeight - _height;    //Close the distance.
    _x = _x + (dx/5);
    _y = _y + (dy/5);    //Adjust the dimensions.
    _width = _width + (dw/3);
    _height = _height + (dh/3);
}

This function turns on the ears of our “square” to listen to any position changes to our beacon movieclip and move it there. When we move the beacon, the highlighter will follow it. Our “square” will also adjust its dimensions according to any changes in targetWidth and targetHeight and morph accordingly to our desired numbers, which in our case will be the dimensions of the DIV we pass it.

Drawbacks to the Flash Underlayer Method

This technique makes creating centered fixed-width layouts rather complicated because the find position function by Peter-Paul Koch seems to always reference distance from the top left corner of the browser window (actually, I believe it’s much more complicated than that and I’m probably dead wrong about it, but just know that it requires making your Flash underlayer movie as large as all the html elements to make it work.

The other drawback is that in Safari, when a Flash movie is positioned underneath an input or textarea element, the element begins to blink in pace with the cursor. You can see this in the demo above. Looks smooth as ice on Mozilla and Internet Explorer, but blinks terribly in Safari. However, this only happens under form elements and so would be entirely okay to use under tables, regular DIVs, spans, etc.

Conclusion

This is a novel approach to injecting Flash into a web application and, while it’s mostly just an interesting experiment, the greater point I’m trying to make here is that there are avenues for integrating the interactivity of Flash that haven’t been discovered yet. With the new Flash 8 environment, this method is actually easier and more responsive thanks to what is essentially a built-in gateway on the Flash 8 player. Web 2.0 is all about mixing and matching technologies, and for those who can’t upgrade to the latest Flash environment, the F/J Integration Kit is a great way to get something dynamic going without any additional expenses. Definitely play with it and let us know if you do anything interesting.