Tutorial details:
Written by: Jesse Stratford [email:jessestratford@actionscript.org]
Time: 25 minutes
Difficulty Level: Intermediate
Requirements: Flash MX
Topics Covered: How to use the new LocalConnection Objects in Flash MX to interact between SWF files.
Assumed knowledge: Variables, Paths, Objects, Methods, Flash MX Event Model.

Many of you will be familiar with the FSCommand Library of JavaScript methods, described in a tutorial on this site as well as elsewhere, which, until Flash MX was the best method for interacting between concurrently open SWF files. Many of you will also be aware of the many pitfalls of using FSCommands for this purpose, including incompatibility with certain browsers and operating systems. Local Connection Objects, like the FSCommand Library allow us to communicate between concurrently playing SWF files, but without the incompatibility issues, and with a lot less hassle.

When does such communication become useful? Consider the case of a website which uses HTML frames to separate the SWF navigation from the content loaded in another frame (or even a popup window). A common problem with such systems is that navigational decisions made by the user in the content frame are often not reflected in the navigation frame. For instance, if you visit the 'Profile' section of a site using the navigation, which highlights the 'Profile' button to indicate that's where you are, then you skip to the 'Pricing' section of the same site via a link in the content frame, how do you prompt the navigation SWF to deselect the 'Profile' button and highlight the 'Pricing' button to indicate the transition? Well, if you're lucky enough to own Flash MX, you use Local Connection Objects.

Here's a simple example. As you can see the table below contains two separate SWF files. When you type a string into the first and click 'Say!' it will send the same string to the second. This isn't exactly Earth-shattering stuff but it does illustrate the concept.

This SWF contains an input field with the variable name 'speech', and a button with the following code: [as]on (release) {  talkingLC = new LocalConnection();  talkingLC.send("simple_lc", "comeBack", speech); }[/as] The purpose of the code is explained below.

This SWF contains an dynamic field with the variable name 'tmp', and has the following code on frame 1: [as]listeningLC = new LocalConnection(); listeningLC.comeBack = function(speech) {  tmp = speech; }; listeningLC.connect("simple_lc");[/as] See below for and explanation.

Let's examine the receiving SWF first. We begin by defining a new Local Connection Object called listeningLC. We can then attach to this object any methods (functions) we wish. In the example above I created a comeBack method which simply takes one argument and passes it into the text field on the stage - the name comes from the film Contact which I watched again last night. Finally we use the built in method connect to specify which other SWF we want to create a local connection with. Here, simple_lc is an arbitrary connection name I gave to the connection between my SWF files. We'll discuss connect in more detail below.

Continued overleaf...

The first line of the sending code simply establishes a new Local Connection Object as before. Note that the name is not the same (and does not have to be the same) as the Local Connection Object in the receiving SWF. The connection name is what tells Flash which SWFs are to communicate with each other; notice it is the same in the connect method for the receiver as in the send method (below) for the sender; this is required for the Local Connection to execute successfully. The second line is what does all the work. The built in send method accepts multiple arguments; the first is the name of the connection between the SWF files, which in this case is simple_lc as defined above; the second is the name of the method you wish to invoke in the receiving SWF, in this case comeback; the remaining arguments are passed as arguments to the method you name. For instance, in the above example, the variable speech is passed to the comeback method in the receiving SWF, which results in the speech variable being displayed in the tmp text field.

Sometimes a connection will fail, due to improper coding or perhaps a domain conflict (see below). Defensive programming teaches us to check for such cases so we don't continue as though everything is OK when it is in fact not, and Macromedia provide us with the onStatus handler which is perfect for performing such checks. The onStatus handler for Local Connections is invoked upon the sending Local Connection after a send command. It returns an object with a level property which can help us determine if our send command was successful. If the level property is equal to the string "error" then something has gone wrong. Change the code in your talking SWF to this:

[as]on (release) {
 talkingLC = new LocalConnection();
 talkingLC.send("simple", "comeBack", speech);
 // Note in the line above the connection name is wrong
 // "simple" should be "simple_lc" as before. This is intentional.
 talkingLC.onStatus = function(result) {
  if (result.level == "error") {
   speech = "Connection failed!";
  }
 };
}[/as]

When you execute this code it will inform you that your connection failed, in this case it's because your connection name is not the same in your sending and receiving SWFs.

There are two other aspects of Local Connections which you should know about. The first is the close method and you get no points for guessing what it does. Closing a Local Connection when it's no longer needed is good form. Can you figure out what would happen if I changed my receiver code to that below?

[as]listeningLC = new LocalConnection();
listeningLC.comeBack = function(speech) {
 tmp = speech;
 this.close();
};
listeningLC.connect("simple_lc");[/as]

The answer is that, while in the working example above you can alter the text and click Say again in order to update the display in the receiver, if my code included a close reference the first string sent would be permanent and unchangeable. Deleting a receiving Local Connection object using delete has the same effect.

Finally, consideration needs to be given to cases where both files do not reside in the same domain. Macromedia have gone to great lengths to ensure the Flash MX player is secure while at the same time allowing us to interact selectively between files across domains, especially in the case of Local Connections. If you find that your Local Connections are not performing (and even if they are) you should read the MX Security Whitepaper (PDF), specifically the section on domains and interaction between them. It will take you five minutes and save you lots of headaches in the future. If you've established that you are indeed suffering from a domain conflict, you can resolve the issue using the allowDomain and domain Local Connection methods. These are described extensively in Macromedia's Local Connection documentation.

So there's a 25 minute crash course in Local Connections for you! Thanks to Macromedia for their good docs on this. If this tutorial helped you out please drop me an email and let me know. I'm open to corrections and suggestions as always.

Jesse Stratford [email:jessestratford@actionscript.org] is the Co-Master of ActionScript.org and a freelance Flash developer and teacher. He is based in Australia and enjoys all things Flash. NB: If you have comments or feedback please feel free to email me, but please do not email me Flash questions; the forums are provided for that purpose and you will get a faster answer by posting you question there.

If you have found this tutorial helpful, I hope that you will take 30 seconds to visit The Hunger Site where, with just one click you can make a free donation of food to a starving person in a third-world country. We do not benefit financially from this action; it is purely an act of charity.

This tutorial is protected by International Intellectual Property Rights laws and may not be reproduced or redistributed in full or part, without the prior written consent of the author. Unauthorized reproduction of this tutorial or its contents may result in prosecution. I've worked hard on this tutorial, please don't steal it.