Using The LoadVars Class | Macromedia Flash MX 2004 ActionScript: Training from the Source

You use the LoadVars class when working with data in the URL string format. This class enables you to load variable data from a text file, or to send and load variable data to and from a server-side script.

NOTE

While variable data contained in a text file can be loaded into Flash, Flash cannot save data to a text file directly; you must use a server-side script to do that.

Creating a LoadVars object in Flash is simple. Look at the following example:

 var container:LoadVars = new LoadVars();

This creates a new LoadVars object named container. To load variables from a URL into a LoadVars object, use the load() method:

 container.load("http://www.myDomain.com/myFile.txt");

TIP

You can get the total number of bytes loaded so far or the total bytes that will be loaded by using the getBytesLoaded() and getBytesTotal() methods of the LoadVars object.

When data has been loaded into a LoadVars object, you can access it by referencing the name of the particular LoadVars object that contains the data you want, followed by the variable name of that piece of data. For example, if you were to load the following string into a LoadVars object named myData:

 name=Jobe&age=28&wife=Kelly

these variable values could be referenced as follows:

 myData.name myData.age myData.wife

For example:

 userAge = myData.age;

Here, userAge would have a value of 28. In the same manner, a variable value in a LoadVars object can be set from within a script in Flash like this:

 myData.age = 45;

A variable value inside a LoadVars object therefore can be set not only by loading external data into the object, but by setting the value internally (using a script inside the movie).

NOTE

When loading variables into a LoadVars object, Flash will overwrite existing variable values in the object or append new variable values.

If you want to send the variables in a LoadVars object to a server-side script for processing, use the send() method. That syntax is as follows:

 myLoadVarsObject.send("http://www.mydomain.com/process.asp");

No response is sent back to Flash when you use this method, so you would use it only to send variable data to the server for processing.

The sendAndLoad() method allows you to specify a LoadVars object whose contents you want to send, and the LoadVars object in which you want the response to load:

 myLoadVarsObject.sendAndLoad("http://mydomain.com/process.asp", receivingLoadVarsObject);

In this case, the variables in myLoadVarsObject are sent to the specified URL for processing. The server sends data back to Flash, and that data is loaded into receivingLoadVarsObject. At that point, you can work with the receivingLoadVarsObject to extract the data that the server sent back. If you want to send variables in a LoadVars object and have that same object receive the data that the server sends back, simply use the load() method described in the following exercise.

Using the toString() method of the LoadVars class, you can create a URL-formatted string that represents the variables/values contained in the object.

graphics/11inf04.gif

The LoadVars class has two properties: contentType and loaded. The contentType property can be changed before sending out variables, simply giving you the mime type specified in the HTTP header of the loaded document. The loaded property returns true if data has finished loading into the object, false if it has not, and undefined if a load() method has not yet been invoked.

There is only one event available to the LoadVars class: onLoad. Use this event to call a function when data has finished loading into the object. Each time data is loaded into the object, this event is fired again.

To load variables from a specified URL into a LoadVars object and then call a function when loading is complete, you must:

Define a function.
Create a new LoadVars object, using the new LoadVars constructor.
Specify the function to be called when the loading has completed.
Invoke the load() method of the LoadVars object.

For example:

 function myFunction(){   trace("Data is loaded"); } var container:LoadVars = new LoadVars(); container.onLoad = myFunction; container.load("http://www.somedomain.com/myFile.asp");

In this example, myFunction() is called when a string of data from the specified URL has been completely loaded into the container LoadVars object.

In the following exercise, you'll create a simple polling system using a LoadVars object. This object will send data to and load data from an ASP page in the URL string format. The ASP page contains a server-side script that enables it to read and write to a Microsoft Access database. When variable data is sent to the ASP page, the page interprets the data and updates the values in the database accordingly. When a LoadVars object requests that data be loaded into it from the ASP page, the page is set up so that it gets the data from the various fields in the database, encodes that data into the URL string format, and sends that data to the LoadVars object.

You will find this scripted page (Poll.asp) and the accompanying database (Poll.mdb) in the Lesson11/Assets folder on your CD-ROM. To complete this lesson successfully, you will need access to a Windows server running IIS so that the server-side script on the ASP page can be executed. Before you begin this exercise, upload Poll.asp and Poll.mdb to a Windows server and make a note of their location (URL).

Open poll1.fla in the Lesson 11/Assets folder.

We've already created the layers, frames, frame labels, and movie clips you'll need so that you can focus on the ActionScript.
With the timeline at Frame 1, you'll notice the text, "What was the best movie of 2003?" Below this text is some space and a Submit button. You will place four Radio Button components in the empty space between these two elements. These radio buttons will represent the selection method for your choice of the best movie of 2003. When a user presses the Submit button, the movie will execute a script, sending data to the server (based on which radio button is selected) and at the same time move the playhead to Frame 3, Waiting, where it will wait for a response from the server. When a response is received (data is loaded into a LoadVars object), the movie will move to the frame labeled Display. This frame will contain a script used to interpret the response from the server (data will be extracted from the LoadVars object). The data will be used to determine the percentage of the total number of votes that each of the four movies has received. Each movie's overall percentage value will then be displayed in a text field as well as graphically, using simple bar graphs.
Move the playhead to Frame 1, and select the frame in the layer called Text and Buttons.
You will add four instances of the Radio Button component to this layer (beneath the question but above the Submit button).
Open the Components panel. Locate the Radio Button component and drag four instances of it onto the stage. Align these four components in a vertical column under the question on the screen.

You have just added four Radio Button components to the stage. If you select one of them and look at the Property Inspector, you'll see a list of the component's properties/parameters, all of which are editable.

NOTE

Although the Property Inspector lists what you see as parameters, from an ActionScript standpoint they represent properties of the component. Since this is an ActionScript book, we identify them as properties.

The first property, data, should be blank. The data property associates a data value with the selected radio button instance. When the radio button instance is selected by the user as the movie plays, this value can be used by a script to perform a task based on that value.

The next property shown on the Property Inspector is groupName. As you learned in Lesson 10, "Scripting UI Components," radio button instances are designed to work in groups, allowing only a single radio button within a group to be selected at any time. This property setting enables you to assign the instance to a particular radio button group. You'll use the radioGroup default value for this property; therefore, the four radio button instances we've dragged onto the stage belong to the radioGroup group.

The label property represents the text displayed next to the radio button instance.

Next is the labelPlacement property. You can click the value of this property to display a drop-down list of label placement options. Each option specifies where the label text should be placed relative to the button itself. The default setting is right, which means that the text is shown to the right of the button.
The final property in the Property Inspector is selected. This is a Boolean value that determines whether a radio button should start off with a dot, indicating that the button is selected. By default, all radio button instances start with a selected value of false, meaning that the button is not selected. If you want one of your radio buttons to start off selected, you would change the value here to true.
Select the top radio button and change its label property to "Pirates of the Caribbean". Change the label properties of the next three radio buttons to Seabiscuit, Bend it Like Beckham, and American Wedding, respectively.

As you change the label names of the radio buttons (from top to bottom on the screen), you should see the text updated in the component itself.

NOTE

If the text in the component isn't updated, choose Control > Enable Live Preview.
You may need to resize a couple of instances vertically to avoid truncating the appearance of the label text.
Change the data property of the four radio buttons to 1, 2, 3, and 4, from top to bottom.
When the movie is published and a radio button is selected, its data property value is set as the data value of the radioGroup. You retrieve this data value for use at any time by accessing the selectedData property of the RadioButtonGroup class. For example, if a radio button with a data property value of 3 was selected, and this radio button was part of a group of radio buttons with a group name of radioGroup, the following syntax would assign a value of 3 to myValue:
```
 var myValue:Number = radioGroup.selectedData; 
```
With the Actions panel open, select Frame 1 in the Actions layer and add stop();.
This stop() action prevents the movie from playing past Frame 1 until you instruct it to do so.
With Frame 1 still selected, add the following line of script:
```
 var pollURL:String = "http://www.myDomain.com/poll.asp"; 
```
This creates a variable named pollURL and assigns it a value that represents the location (URL) of the Poll.asp page you uploaded to your server at the beginning of this exercise. (The URL shown should be replaced with the actual location where Poll.asp resides on your server.)
Add the following line of script:
```
 var poll:LoadVars = new LoadVars(); 
```
This creates a new LoadVars object. With this object, we can load data from a remote location and make use of the convenient methods and properties described earlier in this lesson.
Define the pollLoaded() function by adding the following script at the end of the current script:
```
 function pollLoaded() {   gotoAndStop("Display"); } 
```
This function is used to move the playhead to the frame labeled Display. (The next step explains when this function gets called.)
To associate the function we just defined with the onLoad event of the poll LoadVars object, add the following line of ActionScript:
```
 poll.onLoad = pollLoaded; 
```
This script says that when the last byte of data is completely loaded into the poll LoadVars object, the pollLoaded() function will be called; therefore, when the data has finished loading, the timeline will move to the frame labeled Display, as set up in Step 9. In a moment, we'll add a script at the Display label that will use the loaded data to display the results in several bar graphs.
Add the following function definition just below the last line of script:
```
 function submitChoice() {   var choice:Number = radioGroup.selectedData;   poll.load(pollURL + "?choice=" + choice);   gotoAndStop("Waiting"); } 
```
This function, which is used to submit the user's choice for best movie of 2003, is called when the Submit button is clicked.

The first line of the function definition creates a local variable named choice. This variable is assigned the current data value of the radioGroup group of radio buttons by accessing the selectedData property of the RadioButtonGroup class. If the user selected the second radio button, choice would have a value of 2.

The next line of ActionScript invokes the load() method of the poll LoadVars object. Using an expression, the URL of the Poll.asp page is specified (pollURL), and the variable choice is added to the end of the string to send this to the server using the GET method of transferring variable data. If the user clicked the third radio button, this argument would look something like this:
```
 "http://www.mydomain.com/poll.asp?choice=3" 
```
Remember, everything after the question mark in the argument is a variable. In this case, we're sending a vote (choice=3) to the Poll.asp page. That page will then update the values in the database based on this vote and load the results into the poll LoadVars object. Those results are used in the actions described in Step 14.

The final line of script in this function tells Flash to go to the frame labeled Waiting. The movie will stay on this frame until the data is loaded back into Flash from the server. At that point, the pollLoaded() function will be called (as described in Step 10), moving the timeline to the frame labeled Display.
Add the following onRelease event handler for the Submit button at the end of Frame 1:
```
 submit_btn.onRelease = function() {   submitChoice(); }; 
```
The submitChoice() function defined in Step 11 is executed when the Submit button is clicked.
Move the playhead to the frame labeled Display.
On this frame are four movie clip instances with horizontal bars one bar graph for each movie on which the user is voting. All of these are instances of the same movie clip: their instance names are barGraph1_mc, barGraph2_mc, barGraph3_mc, and barGraph4_mc. Notice that all of these instance names include numbers. These numbers are used to associate one bar graph movie clip for each movie in the poll. Each of these instances also includes two text fields topPercent_txt and bottomPercent_txt that are used to display a textual representation of the percent. Both of these text fields display the same text; bottomPercent_txt is simply there to provide a slight shadow effect behind topPercent_txt. This movie clip also contains a horizontal bar with an instance name of bar_mc. It will be scaled horizontally based on the percentage value.
Select the frame in the Actions layer and add the following loop:
```
 for (var i:Number = 1; i <= 4; ++i) {   var graphName:String = "barGraph" + i + "_mc";   var votes:Number = poll["item" + i + "total"];   var totalVotes:Number = poll.totalVotes;   var percent:Number = Math.round((votes / totalVotes) * 100);   _root[graphName].bar_mc._xscale = percent; } 
```
When the playhead has made it to this frame label (Display), the user has submitted his or her choice and the server has accepted it, added it to the current results, and loaded the resulting data into the poll LoadVars object. Remember that in Steps 9 and 10 we scripted our movie so that it would move to this frame label only after the resulting data from the server had been loaded completely into the poll LoadVars object. The script on this frame will now use that data. The variables loaded from the remote script into the LoadVars object are named totalVotes, item1total, item2total, item3total, and item4total. Obviously, totalVotes has a numeric value representing the total number of all votes submitted, and will be used to figure percentage values. The other variables hold the number of individual votes that each of the movies received. Because these variables have been loaded into the poll LoadVars object, you can access their values by using the following syntax:
```
 poll.totalVotes poll.item1total poll.item2total poll.item3total poll.item4total 
```
The loop calculates the percentage of votes received by each movie and scales the bar in the appropriate movie clip instance based on that number. The first line of script in the loop defines the variable graphName. Because the value of this variable is based on the concatenation of the string "barGraph" with the current value of i and the string "_mc", it's actually a reference to the name of the movie clip instance that will be used during the current loop (barGraph1_mc, barGraph2_mc, and so on). Again, using the value of i, the next action in the loop sets a variable called votes equal to the total number of votes for the current item (poll.item1total, poll.item2total, and so on). A variable called totalVotes is then assigned a value that represents the total number of votes cast for all of the movies. Next, the percent variable is calculated by dividing the current item's number of votes by the total votes and multiplying by 100. This is rounded using the Math.round() method of the Math class. Finally, the bar_mc clip in the current movie clip (as referenced by the current value of graphName) is scaled to match the percent value. This loop will repeat these actions four times, scaling each of the bar graphs in the process.

NOTE

For more information about loops, see Lesson 9, "Automating Scripts with Loops"
Add the following two lines of ActionScript at the end of but within the loop:
```
 _root[graphName].topPercent_txt.text = percent + "%"; _root[graphName].bottomPercent_txt.text = percent + "%"; 
```
The text to be displayed in the topPercent_txt and bottomPercent_txt text fields, above the scaled bar_mc movie clip instance, is set using the value of the percent variable and concatenating "%" at the end.
Choose Control > Test Movie to test your work. Select a movie radio button and click the Submit button.
When you click the Submit button, your choice is sent to the Poll.asp page, which updates the database and returns the results of the poll to the poll LoadVars object. Your movie then moves to the frame labeled Display and shows you the results.
Close the test movie and save your work as poll2.fla.
You have just completed a basic application that uses the LoadVars class to talk to external scripts. You can now use this knowledge to build more complex and useful applications.