Recipe 19.2. Sending Variables

Problem

You want to send variables to the server at runtime.

Solution

Use a LoadVars object. Call the send( ) method. Note that the send( ) method doesn't send values and always opens the response in a browser window. Optionally, to both send and load variables or to send variables transparently use the sendAndLoad( ) method.

Discussion

You can send variables to a script by way of the send( ) method of a LoadVars object. Sending data is useful when you want to record user or application events on the server. For example, when the user submits a form, you may want to send the data to a script running on a server.

The first step is to construct a new LoadVars object, as in the following example:

 var lvDataSender:LoadVars = new LoadVars(); 

You then need to define values for custom properties of the object. Each property ought to have the name of the variable you want to send to the script. For example, the following code defines two custom properties for lvDataSender and assigns the values from two text input components called ctiCity and ctiState:

 lvDataSender.city = ctiCity.text; lvDataSender.state = ctiState.text; 

When you've defined the custom properties, call the send( ) method. The send( ) method requires at least two parameters, specifying the URL of the resource to which you want to send the data (generally a script on a server) and the name of the window in which to open the response. The window name parameter is the name of an existing window, the name of a new window, or one of the following:

_blank

A new window

_self

The current frame

_parent

The parent frame

_top

The top-level frame

The send( ) method always opens the response in a browser window. If you don't want to open the response in a window, use the sendAndLoad( ) method.

The following example sends the variables to a script called form.cgi running in the same directory as the SWF. It opens the response in a new window.

 lvDataSender.send('form.cgi', '_blank'); 

By default, the variables are sent using the GET method. The LoadVars class enables either GET or POST. If you want to specify the method, you can do so with a third parameter to the send( ) method. The parameter must be a string with the value of GET or POST. The following sends the data using POST:

 lvDataSender.send('form.cgi', 'blank', 'POST'); 

The send( ) method always opens the response in a browser window. That may be appropriate in some cases. However, there are many cases in which you want the sending or data to be transparent to the user. The sendAndLoad( ) method sends (and loads) data transparently, and it does not open the response in a browser window. Much of how the sendAndLoad( ) method works is very similar to how the send( ) method works. You must still construct a LoadVars object and define custom properties. Additionally, when you call the sendAndLoad( ) method, you must pass it a parameter specifying the URL of the resource to which you want to send the variables. However, because the sendAndLoad( ) method does not open the response in a browser window, you do not need to specify a window name. Rather, you must specify a LoadVars object that handles the response. The response LoadVars object is an object for which you've defined an onLoad( ) (or onData( ) (see Recipe 19.3) event handler method, as described in Recipe 19.1. The following example uses the same city and state variables and sends them to a script (form.cgi). However, it uses sendAndLoad( ), and when the response is returned, the onLoad( ) method of lvReceipt is called:

 var lvDataSender:LoadVars = new LoadVars(); lvDataSender.city = ctiCity.text; lvDataSender.state = ctiState.text; var lvReceipt:LoadVars = new LoadVars(); lvReceipt.onLoad = function(bSuccess:Boolean):Void {   trace('server response'); }; lvDataSender.sendAndLoad('form.cgi', lvReceipt); 

The sendAndLoad( ) method sends data via GET by default. As with the send( ) method, you can optionally pass the sendAndLoad( ) method a third parameter specifying whether to use GET or POST.

The Test Player always sends data using GET even if you specify POST. If you want to test sending data via POST, you must test in a browser.