Communicating with the Browser Using Actionscript 3 (part 1)

Actionscript's ExternalInterface class

I know I keep saying the next topic will be loading external content using Actionscript 3, but I keep getting distracted. I'm still recovering from my sinus surgery and had not planned on writing anything until I could focus a little better. Somewhere between pain and drugs there's a lot of typos. A devigner friend of mine was asking me about different ways Flash communicated with other applications, so I am heading off on a tangent yet again.

In the earliest days of flash, about the only way a flash file communicated with the browser (or anything else for that matter) was as a hyperlink. These days, a Flash file can communicate with the browser, an http server, a streaming server for data or video or audio, with other flash files in the browser, with assets loaded into itself and Flash files to be loaded in the future (using a cookie-like feature called SharedObjects). That is a topic for another time (no pun intended).

One of features in the last couple of Flash versions has been the ExternalInterface class. The ExternalInterface class allows a flash file to run javascript functions in the browser and allows the browser to run Actionscript functions in the flash file, all the while allowing these functions to pass data as arguments much the way you would with any function call.

1. First we are going to create our Flash file. Add a new text field to the file and make sure it is dynamic. Give it an instance name. I called mine text_txt. I chose a font and made sure to Embed Uppercase, Lowercase, Numerals and Punctuation. Make sure your line type is set for Multiline and because I'm not going to take the time here to decorate the text field, I toggled on the Show Border Around Text button.


2. Add a button. You can make your own; or if you're lazy like I was you can get one from the common libraries. You'll find them under Window>Common Libraries>Buttons. I chose the rectangle flat grey and deleted the text layer so I could use it as a generic button. Add it to it's own layer just in case you have bigger plans for this file and give it an instance name. Mine was bm_btn, short for browser message. I know. Brilliant, Right? What can I say? I'm on medication.
That's it for the stage.

3. Add an actions layer; and in the actions for the first frame use the addEventListener() method on the button.
   
   bm_btn.addEventListener(MouseEvent.CLICK, browserAlert);
   
   Then add the function mentioned as responding to the CLICK event
   function browserAlert(e:MouseEvent):void
   {
   ExternalInterface.call("gimmeAlert", "Hello Flash");
   }

The call() function has one required argument. The name of the javascript function you are running is written here as a String. After that you can include as many arguments as needed for your javascript function. The function we are going to write will take one String variable, So I am passing in the String, "Hello Flash".

ExternalInterface is a "final" class, which means you cannot extend it in making your own classes. It's two non-inherited Methods, addCallback() and call(), are static methods. This means you do not need to create an instance of the ExternalInterface class to use it's methods. In this way it is much like the Math class. You might create a variable to store a random number generated by Math.random(), but you do not need to create a new Math object in order to use the random() method.

4. Publish your Flash file and either let flash build the HTML file, or add the SWF file to an HTML file in dreamweaver. I tend to add the flash file through Dreamwever (for several reasons I'll have to save for a later post).
5. Switch to the code view and find where your Flash file is added. You should see the javascript function AC_FL_RunContent() just before your <object> tag. This is the javascript function Dreamweaver(or Flash) adds to place the swf on the page. It's a bit of an odd function. It uses the arguments passed to it to create the parameters and properties added to the <object> or <embed> tags. The first argument is a parameter name, the second is it's value. They just keep alternating that way. We need to add two(four) more at the end. Find where the parenthesis close at the end of the function and add 'id', 'eiexample', 'name', 'eiexample'. This will add the attributes or parameters id and name, and give them both the value eiexample. That way all the current browsers will be happy.
   
6. Lastly we need to add our javascript function. This is the one that is going to be run from within the flash file. We are going to be adding the javascript to the head of the document just to make the process easier. Before the closing </head> tag add this code...
   
   <script language="javascript">
   function gimmeAlert(someText)
   {
   alert(someText);
   }
   </script>


7. Upload your flash and HTML files and test. When you click the button in the flash file you should get a browser alert message "Hello Flash". If not, make sure that javascripts are allowed in your browser. If you get the Alert message, then you have successfully gotten flash to run a script through the browser.

Since this has become a very long entry, I'm going to call it part 1 and go over the second half in the next post.

'til then
--Rich

For more information on the ExternalInterface class see Adobe's livedocs entry on the topic...
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/external/ExternalInterface.html