Recipe 18.1 Loading Variables from a Text File

18.1.1 Problem

You want to load variables into your Flash movie from an external text file.

18.1.2 Solution

Use the LoadVars.load( ) method.

18.1.3 Discussion

You should use the LoadVars.load( ) method when you want to load URL-encoded data into your Flash movie from a text file. This technique allows your Flash movie to access values that change frequently without modifying the Flash movie itself.

The load( ) method requires a URL where it can find the text file. The URL can be an absolute or relative address.

// You must first create the LoadVars object.
myLoadVars = new LoadVars(  );

// This example loads values from a text file at an absolute URL.
myLoadVars.load("http://www.person13.com/myText.txt");

// This example loads values from a text file located at a relative URL, in this
// case, in the same directory as the Flash .swf file.
myLoadVars.load("myText.txt");

Here is an example of what the text file might contain:

someText=testing&myVariable=123

Once you invoke the load( ) method of a LoadVars object, Flash attempts to load the values from that URL into the same LoadVars object. After the data loads, Flash attempts to decode the values and invokes the object's onLoad( ) method. It is up to you to define the onLoad( ) method so that the object can do something useful once the data is loaded and decoded.

You should define an onLoad( ) method that expects a Boolean parameter indicating whether Flash was able to load the values. If Flash cannot load the values, such as if the file (or script) is unreachable, the onLoad( ) method is passed a value of false.

When playing the movie in the Test Player, you will also receive an error message in the Output window if the specified URL is unreachable.

Here is an example onLoad( ) handler:

myLoadVars.onLoad = function (success) {
  // If the data didn't load, write a message to a text field and assign some default
  // values to the variables that would otherwise have been loaded.
  if (!success) {
    _root.output_txt.text = "Flash is using the default values.";
    this.title = "Loading Variables For Fun and Profit";
    this.author = "Anonymous";
    this.articleBody = "You too can enjoy the fun of loading variables.";
  } else {
    // Process the loaded variables.
  }
};

If loading is successful, Flash stores the loaded variables as properties of the LoadVars object and invokes onLoad( ), passing it the value true. Here is an example that accesses a known property. It assumes that there was a variable named title in the text file from which the data was loaded.

myLoadVars.onLoad = function (success) {
  // If the loaded data was decoded, display the title property. 
  if (success) {
    trace(this.title);
  } else {
    trace("Unable to load the title.");
  }
};

Here is what the text file might look like:

title=ActionScript+Cookbook

In most cases, you already know the names of the variables that are loaded from the external file or script. For example, you might use a LoadVars object to load a daily article from a server-side script or file, and regardless of the article's content, you expect three variables—title, author, and articleBody—to be loaded. You know which variables to expect because you wrote the server-side script, work with the person who wrote the script, or have access to documentation on the script. However, there are some situations in which you might not know all the variables that are being loaded. In such cases, you can use a for . . . in statement to enumerate all the variables that have loaded. Remember that a for . . . in statement loops through all the custom properties and methods of an object, including the variables loaded from the script or file; the built-in methods and properties of the LoadVars class don't show up. Since your onLoad( ) method is stored as a custom property, that method shows up in a for . . . in statement. You can use an if statement to filter out onLoad( ) from the display. This principle also holds true for other custom properties or methods you might have defined for the object that you don't want to appear (in order to display the loaded variables only). For example:

myLoadVars.onLoad = function (success) {
  if (success) {
    // Use a for . . . in statement to enumerate the elements of this, which is the
    // LoadVars object, myLoadVars.
    for (var prop in this) {
      // Display the property only if it is not "onLoad". To omit other properties or
      // methods, add them to the conditional expression with &&'s. For example:
      // (prop != "onLoad" && prop != "aCustomProperty")
      if (prop != "onLoad") {
        _root.output_txt.text += prop + ": " + this[prop] + newline;
      }
    }
  }
};

If the LoadVars object already has properties with the same names as any of the loaded variables, those properties are overwritten. Therefore, avoid variables with the same names as any of the properties or methods of the LoadVars class (including the undocumented onData( ) and decode( ) methods). Here is an example of a text file that includes a variable named onLoad:

onLoad=test&myVariable=abc

If you load these values into a Flash movie, the onLoad( ) method is never invoked because once the data is loaded and decoded, the onLoad( ) method is overwritten with the value "test".

18.1.4 See Also

Recipe 18.2. See Recipe 6.13 for details on for . . . in loops.