The Flash/JavaScript Integration Kit was developed by Christian Cantrell and Mike Chambers at Macromedia. It was developed to make the communication between Flash and JavaScript easier to implement. This isn't a new technology, but it's a straightforward way to implement this type of communication between these different pieces of your application. This article discusses the benefits of this Integration Kit and gives a simple demonstration of how it can be used.
There are several unique features of this Integration Kit that give it value over traditional FSCommand. The first advantage is its ease-of-use. This kit has been designed to encapsulate many of the complicated aspects of Flash-to-JavaScript communication. Therefore, developers don't need to add large amounts of complicated JavaScript or VBScript to their pages. Instead, they just include the few lines of code it takes to implement the Integration Kit.
Another unique feature of this Integration Kit is its ability to transfer data types between Flash and JavaScript. The following data types can be successfully transferred: Object, Array, String, Number, Date, Boolean, null and undefined. It accomplishes this complex task by serializing the data into XML before sending it, then deserializing it back into the native language when it receives the data. And because it uses XML to serialize the data, you can nest data types too. So you could send a List component's data provider (Array of Objects) like the following: [{label:"One", date"1}, {label:"Two", date"2}].
This Integration Kit also works on a variety of browsers including Windows IE 6.0, Windows Firefox 1.0, Windows Opera 8.0, Macintosh Opera 8.0, Macintosh Firefox 1.0, Safari 1.2.4, Safari 2.0, and Linux Firefox 1.1.
More information on the Flash/JavaScript Integration Kit can be found at the following link: http://www.macromedia.com/go/flashjavascript.
To implement the Integration Kit into your project, the first thing you must do is download FlashJavascriptGateway.zip and extract it to whatever directory you like.
Once you have downloaded and unzipped the Integration Kit, you can begin implementing it in your project. Start off by copying FlashJavascriptGateway\installation\JavaScriptFlashGateway.js and FlashJavascriptGateway\installation\JavaScriptFlashGateway.swf to the root directory of your project. If you want to use this Integration Kit across multiple projects, you'll need to put the preceding files in a location that is accessible to all of your projects. The code throughout this article assumes that these files are in the same directory as your HTML page.
You also need to get the ActionScript class files. These can be found in the following path in the downloaded package: FlashJavascriptGateway\source\flash\actionscript\com. Copy the com directory and all of its contents to the same directory as your Flash source file. Figure 1 shows how your project's directory structure should look if you've implemented it correctly.
Figure 1 The file and directory structure of the
Integration Kit files within your project's directory
The example application we are going to build is a simple interface that transfers list items from one list to the other. This is a pretty simple concept, but we are going to add a twist. One of our lists will be in Flash and the other will be in HTML/JavaScript.
We'll start by creating the Flash part of this interface.
Figure 2 The property inspector for our List
component
The first thing we must do is create an instance of the JavaScriptProxy class. This class handles sending and receiving data between Flash and JavaScript. When creating this instance we pass in two parameters to the constructor. The first is a unique identifier that will be passed into the SWF from the host page via FlashVars. This identifier will be used behind the scenes to enable proper communication with the LocalConnecton object. The second parameter is a reference to the object that will be receiving the method calls from JavaScript. In our case, the receiving functions are on the main timeline, so we will just pass in the this scope. The following code shows how this should look:
import com.macromedia.javascript.JavaScriptProxy;
var proxy:JavaScriptProxy = new JavaScriptProxy(_root.lcId, this);
Listing 1 Creating an instance of the JavaScriptProxy class
Next, we will create a function that adds items to our list. This function will be called from the JavaScript code through the JavaScriptProxy class. This function takes an object as its only argument. The object will have the display and value properties necessary to create a new list item. The following example shows how we will add items to our List component:
function addItem(item:Object):Void {
list.addItem(item);
}
Listing 2 This function adds items to the List component
The last piece of ActionScript code we need to create is the code that transfers an item from our Flash List component to JavaScript. The function first checks to make sure an item is selected in the list. If there is a selected item, then we call the JavaScript addItem function using the JavaScriptProxy.call method. We will pass the List component's selectedItem property as this function's only parameter. Finally, we must register our transferItemToJavaScript function as a listener to our transfer button. This allows our function to be called when the transfer button is clicked. The following example shows this final piece of code:
function transferItemToJavaScript():Void {
if(list.selectedItem != null) {
proxy.call("addItem", list.selectedItem);
list.removeItemAt(list.selectedIndex);
}
}
transferButton.addEventListener("click", mx.utils.Delegate.create(this, this.transferItemToJavaScript));
Listing 3 Calling the JavaScript addItem function from Flash
The transferItemToJavaScript function also removes the selected item from the List component using the List.removeItemAt method.
Now we will concentrate on the HTML page that contains the JavaScript code and houses the Flash and HTML interface elements. The first thing we need to do is include the JavaScriptFlashGateway.js file. This code goes in the <head> of our page:
<script type="text/javascript" src="JavaScriptFlashGateway.js"></script>
Listing 4 Including JavaScriptFlashGateway.js script in our page
The JavaScriptFlashGateway.js script actually is a container for the Exception.js, FlashTag.js, FlashSerializer.js, and FlashProxy.js. If you want more gainular control you can include each of these scripts in your page instead. These can be found in the source folder of the zip file you downloaded earlier.
Next, we need to create the unique identifier that is used to enable proper communication over LocalConnection. We will do this by creating a Date object and calling its getTime method. This returns the current time in milliseconds. It is important to note that if you use this technique for creating all your identifiers, they should all be unique.
We also need to create an instance of the FlashProxy class. This is a custom JavaScript class that is defined inside the JavaScriptFlashGateway.js file. The constructor of this class takes two parameters. The first is the unique identifier and the second is the path to JavaScriptFlashGateway.swf. The following example shows the code for creating the unique identifier and the FlashProxy instance:
var lcId = new Date().getTime();
var flashProxy = new FlashProxy(lcId, "JavaScriptFlashGateway.swf");
Listing 5 Creating the unique identifier and the FlashProxy instance
Next, we need to create the addItem function that is called from Flash. This function works similarly to the one we built earlier in ActionScript. It simply takes an item object as a parameter, and uses its properties to add a new item to the HTML <select> list:
function addItem(item) {
var selectList = document.listForm.list;
var len = selectList.options.length;
selectList.options[len] = new Option(item.label, item.value, false, false);
}
Listing 6 Adding items to the HTML select list
Next, we create the function that transfers the HTML list item to Flash. We'll call this function transferItemToFlash so that it is consistent with the ActionScript class we created earlier in this article. This function does the same thing as its ActionScript counterpart. The only difference is that it is interfacing with an HTML list element instead of the Flash List component. Note the highlighted line below. This is the code that actually calls the addItem method within the Flash code:
function transferItemToFlash() {
var selectList = document.listForm.list;
var index = selectList.selectedIndex;
if(index >= 0) {
flashProxy.call("addItem", {label:selectList.options[index].text, data:selectList.options[index].value});
selectList.options[index] = null;
}
}
Listing 7 Transferring an item from the HTML list element to the Flash List component
The last thing we need to do to is add the code that writes the Flash embed tags, and create the HTML form. We are simply going to create a two-column table that contains the two elements of our interface. In the first column we use the JavaScript FlashTag class that is included with the Integration Kit. This class simplifies the process of including the Flash movie (sample.swf) into our interface. We need to pass in to the class constructor the path to our SWF file and its dimensions. We will pass the unique identifier into Flash using the setFlashvars method. Finally, we output the HTML code using the FlashTag.write method.
The HTML form is very simple. We have two form elements to create: the list and the button. We will pre-populate the list with two items so we can test the application. We also need to call the transferItemToFlash method when the transfer button is clicked.
<table border="0" cellpadding="0" cellspacing="5" width="400">
<tr>
<td valign="top">
<script type="text/javascript">
var sample = new FlashTag("sample.swf", 200, 200, "7,0,14,0");
sample.setFlashvars("lcId=" + lcId);
sample.write(document);
</script>
</td>
<td valign="top">
<form name="listForm">
<select name="list" size="2" style="width:200px; height:170px;">
<option value="3">Three</option>
<option value="4">Four</option>
</select>
<input type="Button" value="transfer" onclick="javascript:transferItemToFlash();" />
</form>
</td>
</tr>
</table>
Listing 8 Embedding the Flash movie (sample.swf) and creating our HTML form
Paul Newman of Community MX recently wrote an interesting tutorial on Flash/JavaScript communication titled "Talking to Flash with JavaScript." It uses many of the same techniques as the Flash/JavaScript Integration Kit introduced by Macromedia. You can view the article here.
The Flash/JavaScript Integration Kit makes the complicated task of communicating between the two technologies much easier than it is by using FSCommand alone. It also adds in the ability to transfer nested data types between the Flash and JavaScript. With the recent explosion of AJAX, I think this Integration Kit is a will be a huge hit among developers.
It is important to note that the Flash/JavaScript Integration Kit is still in beta form and should be used with caution. Submit all bugs to Christian Cantrell and Mike Chambers at Macromedia.
Approximate download size: 392k
Keywords
Flash, JavaScript, Integration Kit, FSCommand, ActionScript, Communication, LocalConnection, chambers, cantrell
