| LoadVars.load( ) Method | Flash 6 |
| import URL-encoded variables from a text file or server-side application |
A string specifying the path to a variable source�either a server-side script that returns variables or a text file containing variables.
A Boolean indicating whether the method executed successfully. Note that the return value is less useful than it appears. The load( ) method returns false only if it is invoked with no arguments. Because loading is asynchronous, load( )'s return value indicates only whether the load was initiated successfully; it will return true even if the load operation eventually fails, in which case onLoad( ) is called with a false status.
The load( ) method initiates the download of URL-encoded variables from url, which can be a local or remote text file, or a server-side application. Download progress can be monitored with the getBytesLoaded( ) and getBytesTotal( ) methods. When the variables have finished downloading, they are parsed and converted into properties of loadVarsObject, and loadVarsObject.onLoad( ) is invoked. All properties are typed as strings. To intercept the loaded data before it is converted into properties, use LoadVars.onData( ). Note that no variables are accessible as loadVarsObject properties before onLoad( ) executes; all variables must be downloaded and parsed before any are available as properties. Likewise, all variables must be downloaded before they are available to ActionScript in the onData( ) event handler.
When url is a server-side application or script, the MIME type of the transmitted data must be set as "application/x-www-form-urlencoded". Here's a typical MIME-setting statement from a Perl script:
print "Content-type: application/x-www-form-urlencoded\n\n";
For more information on URL encoding in Flash, see the Description heading of the LoadVars class.
For security reasons, LoadVars.load( ) works only with hosts in the domain from which the movie was downloaded. For more information, see System.security.
In practice, the load( ) and sendAndLoad( ) methods may not trigger a download if the variables at url are cached by the browser hosting the Flash movie. To force the browser to always download variables (and bypass its cache) we can use a query string with a dummy variable that contains a unique value. By convention, the current time in milliseconds is used, as it is assumed to be sufficiently unique. For example:
theVars = new LoadVars();
theVars.load("http://www.site.com/vars.txt?cacheKiller=" + new Date().getTime());
The same effect can be achieved using the sendAndLoad( ) method to invoke an HTTP GET request with a dummy variable (cacheKiller):
varSender = new LoadVars();
varReceiver = new LoadVars();
varSender.cacheKiller = new Date().getTime();
varSender.sendAndLoad("http://www.yourserver.com/vars.txt", varReceiver, "GET");
In all cases, data should be verified inside the onLoad( ) handler before being used, because cached data can be corrupt or incomplete. See LoadVars.onLoad( ) for an example.
The following code uses a LoadVars object to retrieve the variable in the text file vars.txt, which looks like this:
msg1=hello+world
Two variations of load( ) are shown, one with a unique cache-prevention variable:
// Make a text field in which to display the loaded variable
this.createTextField("msg1_txt", 1, 200, 200, 100, 20);
// Create the LoadVars instance
externalVars = new LoadVars();
// Assign an onLoad() callback to tell us that the variable has arrived
externalVars.onLoad = function () {
// When the variable arrives, display it in our text field
msg1_txt.text = this.msg1;
}
// Now load the text file
externalVars.load("http://www.site.com/vars.txt");
// Or, to bypass browser cache, append a unique dummy variable to the query string
externalVars.load("http://www.site.com/vars.txt?cacheKiller="
+ new Date().getTime());
loadVariables( ), LoadVars.getBytesLoaded( ), LoadVars.onData( ), LoadVars.sendAndLoad( )