Recipe 19.3. Loading Text

Problem

You want to load a block of text at runtime.

Solution

Use a LoadVars object. Use an onData( ) event handler method.

Discussion

Although you can load a large block of text as the value of a variable in the manner described in Recipe 19.1, it's frequently more convenient to load the text slightly differently. When a response is returned from a load( ) or sendAndLoad( ) method call, Flash automatically calls the onLoad( ) event handler method for the LoadVars object handling the response. However, there are a few steps that occur before the onLoad( ) method is called. First, the onData( ) event handler method is called. The onData( ) method is defined (by default) to parse the loaded data into properties of the LoadVars object and then call the onLoad( ) method. Therefore, if you use the default behavior, you must load only URL-encoded data, or you will have no way to retrieve the data that was loaded, because Flash will not be able to correctly parse the data unless it is property encoded. However, if you override the default behavior, you can retrieve the data that's loaded before it's parsed. That means that you can load a block of (non-URL-encoded) text and assign it to a variable or display it in a text field, and so on.

You can override the onData( ) method by assigning a new anonymous function to the onData property. The onData( ) method is automatically passed a string parameter that contains the data that was loaded. The following example constructs a new LoadVars object, defines an onData( ) method that traces the loaded data, and loads the data from a text file:

	var lvExample:LoadVars = new LoadVars();
	lvExample.onData = function(sText:String):Void {
	  trace(sText);
	};
	lvExample.load('example.txt');

When you override the onData( ) method, the default behavior does not occur. That means that when you define a new custom onData( ) method, it no longer attempts to parse the loaded data and call onLoad( ). If you define both an onLoad( ) and an onData( ) method, only the onData( ) method is called by default.