Recipe 19.1. Loading Variables

Problem

You want to load variables at runtime.

Solution

Use a LoadVars object. Call the load( ) method.

Discussion

There are many reasons you might want to load variables at runtime. Loading variables at runtime makes applications more dynamic than they would be if you had to hardcode all values into the file. For example, if your application displays a new quote or snippet of text every week or month, you will find that loading the quote or text snippet at runtime is preferable to hardcoding the value. If you hardcode the value, you have to reexport the file every time you want to update the value. However, if you load the data at runtime you can simply update a text file or database field, and the data that's loaded into the Flash file is also updated.

You can load runtime variables from any source that can return URL-encoded text. URL-encoded text looks like a query string from a URL. URL-encoded text is composed of name (exp 3pod.com)-value pairs delimited by ampersands (&). Each name (exp 3pod.com) and value is delimited by an equals sign. For example, the following URL-encoded string defines two variables, color and area:

	color=red&area=100

You can store URL-encoded data in a static text or HTML file, or you can output URL-encoded data from any valid resource, such as a PHP page or a ColdFusion page. Regardless of where the data resides, you use the same basic ActionScript code to load the data. You can use a LoadVars object to load URL-encoded data from an external resource. The first step is to construct the object as follows:

	var lvSampleData:LoadVars = new LoadVars(); 

Then you need to define an onLoad( ) event handler method for the LoadVars object. The data isn't loaded immediately when it's requested. That means that Flash needs a way to receive a notification when the data is loadedwhether that takes milliseconds or seconds. The onLoad( ) event handler method is the way in which Flash receives the notification. When the data loads, Flash will automatically call the onLoad( ) method you define. The following example defines an onLoad( ) method for a LoadVars object called lvSampleData:

	lvSampleData.onLoad = function(bSuccess:Boolean):Void { 
	  trace("data loaded"); 
	};

Note that the onLoad( ) method is automatically passed a Boolean parameter indicating whether Flash was able to parse the data. The onLoad( ) method is always called as long as Flash was able to load data. Therefore, the Boolean parameter does not tell you whether the data loaded. Rather, it tells you whether Flash was able to parse the data into variables. If the parameter is TRue, each of the variables from the URLencoded data is parsed into a property of the LoadVars object with the same name (exp 3pod.com). For example, if you load the sample URL-encoded data (color=red&area=100), the LoadVars object will have properties called color and area. The following onLoad( ) method traces the values of those two properties.

	lvSampleData.onLoad = function(bSuccess:Boolean):Void {
	  if(bSuccess) {
	    trace('color = ' + this.color);
	    trace('area = ' + this.area);
	  }
	else {
	    trace('There is an error with the data.'); 
	  } 
	};

After you've constructed the LoadVars object and defined the onLoad( ) event handler method, the next step is to tell Flash to load the data from the external resource. You can accomplish that by calling the load( ) method of the LoadVars object. The load( ) method requires one parameter specifying the URL of the resource. The following loads data from a file called variables.txt in the same directory as the SWF:

	lvSampleData.load('variables.txt');

When the load( ) method is called, Flash initiates a request to the specified resource. It then continues to run any code that follows and (if applicable) play back the timeline. When a response is returned, the onLoad( ) method is called. That means that you should not assume that the data will have loaded immediately following the call to the load( ) method. Any code that requires the values loaded from the external resource needs to be placed within the onLoad( ) method or within a function that is called by the onLoad( ) method.

This recipe describes how to load variables from URL-encoded data in external resources, such as HTML files, text files, PHP files, and so on. Generally, this works best when the values for the variables are fairly simple and short. The example values of red and 10 are good examples. When you want to load large blocks of text, it is generally much more convenient to load the data in the manner described in Recipe 19.3.