loadVariables() and LoadVars

loadVariables() and LoadVars

External data from text files can provide an easy way to externalize application data that doesn't change very often. For example, you might have style information for how text should display in your application or schedule data that is published monthly or quarterly.

In the Flash application, we can request the file containing the text using its URL. The URL can be to a server-side application that generates the text file or a static text file stored on the server. When the call is returned to the Flash application, a special storage object grabs and retains the data in the application as long as the application is running. This model offers a suitable solution for small datasets when the data is maintained separately from the application.

First we will look at the data and then we will use the built-in Flash objects to access the data. There are three key elements for externalizing data in text files:

• The format of text in the file

• The file location

• The reading of data from the text file

Proper Format for the Text File

Text files loaded into a Flash application have to be created using a special syntax. The syntax is called name -value pairs . This means that each entry in the file will have a variable name and a variable value . The text must also be URL encoded. Multiple pairs are separated by & .

Listing 11.1 shows a sample from a text file where name , age , and color are the variable names , while Hank , 42 , and red are the values, respectively.

Listing 11.1. Name-Value Pairs

 name=Hank&age=42&colors=red 

The name-value pairs can include arrays of data. The data would be formatted as a set of comma delimited strings. Listing 11.2 shows an example of array data for the colors variable.

Listing 11.2. Name-Value Pairs with Array Data

 name=Hank&age=42&colors=red,blue,green 

N OTE

URL encoding is a replacement process for non- alphanumeric characters . For example, when a string is encoded, the spaces are replaced with a plus sign (+) and an exclamation point(!) and is encoded as %21. Most server-side applications, such as ColdFusion and Active Server Pages (ASP), have methods to encode text. For more information on URL encoding, see www.macromedia.com/support/flash/ts/documents/url_encoding.htm.

Where Can the File Be Located?

The Flash Player has a security model that is consistent with browser security models. That is, a movie running within a browser can access only external resources that are served from the same domain. Before Flash Player 7, accessing resources from a different domain required developers to use workarounds. With the new security model in Flash Player 7, the user decides to allow or deny data resources at runtime. For example, if a Flash movie is trying to access a text file from a different domain, the Flash Player will pop up a dialog box informing the user that the movie is trying to access data from a different domain. The user can choose to allow or deny the data access, as shown in Figure 11.1. Figure 11.1 shows two different dialog boxes. The first is showing a request to load data from a different domain. The second is requesting to load data from the same domain, but using a secure protocol.

Figure 11.1. Allow/Deny dialog box.

Reading Text Files

In Flash, there are built-in methods and objects that enable us to request and read external text files. There is an object called LoadVars and a method called loadVariables() . The LoadVars object has several methods for requesting and managing the data from text files while loadVariables() can be used globally or as a method of a movie clip. The LoadVars object offers a more robust solution because it has methods and event handlers for managing the loading process as well as the data after it is loaded.

N OTE

The loadVariables() method is not the preferred method for reading data from a text file. It is mentioned here because many legacy Flash applications were written using this method. The preferred solution uses an object, such as the LoadVars object (covered in this chapter) or the XML object (covered in Chapter 12), for loading data.

The loadVariables() Method

The loadVariables() method reads data from an external file and sets the values for variables in the receiving movie clip. This method assumes that all the data in the text file is URL encoded.

There are two ways to use the loadVariables() method:

• Global function. Your code should look like the following: loadVariables (" url " , target [, variables ]) .

• Movie clip method. Your code should look like the following: movieclip.loadVariables (" url " [, variables ]) .

Listing 11.3 shows an example of their usages.

Listing 11.3. loadVariables() Method Invocation

 //global function loading into the current timeline loadVariables("http://www.myDomain.com/bankRates.txt", ""); or //global function loading into the movieclip - rates this.createEmptyMovieClip("rates",10) loadVariables("http://www.myDomain.com/bankRates.txt", "rates"); or //movieclip method this.createEmptyMovieClip("rates",10) rates.loadVariables("http://www.myDomain.com/bankRates.txt"); 

There are some shortcomings when using loadVariables() . If you are loading a text file that is more than a few data elements, you might need to wait until all the data is loaded to actually use the data. There is no mechanism to determine when the data has completely loaded into the application. The LoadVars object addresses this shortcoming. We discuss it next .

LoadVars Object

The LoadVars object is an alternative to the loadVariables() function for reading data from a server. The LoadVars object is also more object-oriented because LoadVars can be subclassed and the applications data access logic can be added and encapsulated in the subclasses object.

You can use the LoadVars object to obtain the following:

• Verification when data loading is complete

• Loading progress

The LoadVars object uses the methods load() , send() , and sendAndLoad() to access data from a server, as shown in Table 11.2 from the Flash 2004 Help Files. The LoadVars object expects data in the form of name-value pairs.

Table 11.2. Method Summary for the LoadVars Object from Flash 2004 Help Files

M ETHOD	D ESCRIPTION
LoadVars.load()	Downloads variables from a specified URL
LoadVars.getBytesLoaded()	Returns the number of bytes loaded from a load() or sendAndLoad() method
LoadVars.getBytesTotal()	Returns the total number of bytes that will be downloaded by a load() or sendAndLoad() method
LoadVars.send()	Posts variables from a LoadVars object to a URL
LoadVars.sendAndLoad()	Posts variables from a LoadVars object to a URL and downloads the server's response to a target object
LoadVars.toString()	Returns a URL encoded string that contains all the enumerable variables in the LoadVars object

You must use the constructor new LoadVars() to create an instance of the LoadVars object before calling its methods. Listing 11.4 shows the creating of a LoadVars object and the calling of the load() method.

Listing 11.4. Create a LoadVars Object

 var rateObject = new LoadVars(); rateObject.load("http://www.myDomain.com/bankRates.txt"); 

We mentioned earlier that the LoadVars object has methods that help us determine when the loading is complete. There is also an event that is triggered when the loading has finished. The event is called the onLoad event. We can use this event to manipulate the data after it is loaded. Listing 11.5 shows that when the data has loaded completely, it is used to populate a combo box in the loan calculator application.

Listing 11.5. onLoad() Used to Populate a Combo Box

 var rateObject:LoadVars = new LoadVars(); rateObject.load("http://www.haffnergraphic.com/bankRates.txt"); rateObject.onLoad = function(){       trace("number of bytes loaded = "+ this.getBytesLoaded());       populateBankList(rateObject); } populateBankList = function(bankData){       var bankArray:Array = bankData.banks.split(",");       var ratesArray:Array = bankData.rates.split(",");       for (var i =0; i<bankArray.length; i++){             var label = bankArray[i]+": "+ ratesArray[i]+"%";             var value = ratesArray[i];             this.bankList_cbx.addItem(label, value);       } } 

N OTE

The LoadVars object can be used to send data as well as to receive data. This chapter covers reading data into an application using LoadVars . The XML object is a better choice for sending data to a server. For more information on sending data from a Flash application using XML, see Chapter 12.