The LoadVars Object

I l @ ve RuBoard

You are lucky to be learning Flash-server communication with Flash MX. In earlier versions of Flash, you had to create awkward movie clips to be able to send information to the server. But with Flash MX, you can use the LoadVars object.

The LoadVars object is a series of commands and a special type of variable object that allows you to send information to the server just like a post form in HTML. You can create a LoadVars object in the same way that you create a variable object, like the ones in Hour 12, "Objects and Arrays."

Loading Data

Here is an example. Instead of using new Object() , you simply use new LoadVars() . This creates an empty LoadVars object.

 myVars = new LoadVars(); 

You can do one of two things with a LoadVars object. You can use it to get data from the server or send data to the server. Getting data from the server is done with the load command. All you need to do is specify the URL where the data needs to be loaded:

 myVars.load("myURL.txt"); 

This works similarly to the LoadVariables command in Hour 10, "Creating and Controlling Text." However, the LoadVariables command just created or replaced variable values at the same level as the command. The LoadVars object populates itself with those variables as properties of the object.

For instance, suppose that you have a data file that looks like this:

 name=George&ID=47 

When you use load to get these variables into the myVars object, you end up with properties myVars.name and myVars.ID with the values "George" and "47".

Like the LoadVariables command, the load command in the LoadVars object only works if the data file is at the same subdomain as the Flash movie. The only exception is in projectors or the Flash test window. Otherwise, you just can't get data from a different server.

Sending Data

You can also send data with your LoadVars object. First, you need to put some data in the object. Then, you can use the send command to send it along to the server in the same format as an HTML form.

 myVars = new LoadVars(); myVars.name = "George"; myVars.ID = 47; myVars.send("serverprogram.cgi", "_self"); 

This code creates the variable myVars as a LoadVars object. It then adds two properties to it. Finally, it sends this information to the server, specifically to the CGI program named echo.cgi.

The send command works much like an HTML form. As a matter of fact, if you include the optional _self parameter, it will even replace the entire Web page with the results from the server, just like posting with an HTML form will replace the entire page with the results of the operation.

You can vary this a little by specifying another target frame or window with a second parameter to send. Then the results of the post are returned in another window, and the page with the Flash movie on it remains. You can use _blank , _top , or _parent as well as a specific window or frame name. If you omit the second parameter altogether, no response is sent.

However, there is another alternative. You can use the sendAndLoad command. This is a combination of both the send and the load commands. It sends the variables from one LoadVars object and loads the resulting variables into another. Here is an example:

 mySendVars = new LoadVars(); myLoadVars = new LoadVars(); mySendVars.name = "George"; mySendVars.ID = 47; mySendVars.sendAndLoad("serverprogram.cgi", myLoadVars); 

When using the sendAndLoad command, no HTML page is replaced at all. The results of the server program need to be in the special format that load and LoadVariables use so that they can be read in and used to populate the second LoadVars object.

Load Status

Keep in mind that the load , send , and sendAndLoad commands do not happen immediately. The process starts when you issue the command, but then continues on independently of the rest of your code. So the next ActionScript line after a load command executes immediately, but the load command itself is just starting. The server is contacted, and the information is sent. This takes some time. How long depends on the responsiveness of the server and the speed of the network. It could be a fraction of a second or several whole seconds.

This means that you will not want to try to use the results of the load or sendAndLoad command right away. Instead, you'll need to detect when the process is complete. There are several ways to do this. The simplest way is to examine the loaded property of the LoadVars object. This will be true only when the process is complete.

You can have a looping movie clip that checks the loaded property, or perhaps just use it to deter the user from clicking a Next button until it is true.

If you want to check the status of the process, you can use the getBytesLoaded and getBytesTotal properties of the LoadVars object to see how far the process has gotten. However, this would only make sense if there is a large amount of data or a very slow network.

You can also define a function to be called when the process is complete. You do this in a similar way to creating a listener for other objects. Here is an example:

 myLoadVars.onLoad = function(success) {  if (success) {   gotoAndStop("load done");  }  else {   gotoAndStop("load problem");  } } 

As you can see by this example, the success parameter gets either a true or false depending on whether the operation was a success.

But what exactly happens on the server side of things? The preceding examples include serverprogram.cgi as the name of the place where the LoadVars object gets sent, but what, exactly, happens on the server?

I l @ ve RuBoard