LoadVars.onLoad( ) Event Handler

Arguments

success

A Boolean value indicating whether loading was successful ( true ) or unsuccessful ( false ).

Description

The onLoad( ) handler executes automatically whenever external variables have finished loading and have been converted (parsed) into loadVarsObject properties. We rely on onLoad( ) to tell us when it's safe to process loaded variables; if onLoad( ) is triggered, we know that we can access our loaded content. By default, the onLoad( ) handler of a LoadVars object is an empty function. To use onLoad( ) , we must assign it a callback function. For example:

// Create the


LoadVars


instance
varReceiver = new LoadVars();
   
// Assign the callback function to


onLoad()


varReceiver.onLoad = handleLoad;
   
// Define the callback function
function handleLoad (success) {
  // Process variables as desired here... 
}

This syntax, which uses a function literal, is also common:

varReceiver.onLoad = function (success) {
  // Process variables as desired here... 
}

From inside our callback function, we access loadVarsObject 's properties via the this keyword. For example:

function handleLoad (success) {
  // Display the value of the loaded variable


score


in the Output window
  trace(this.score);
}

The success parameter tells us whether any variables were actually loaded. If the data loaded from the server was empty, success is false ; otherwise , it's true . We can use success to provide basic verification that something useful was actually loaded, as follows :

function handleLoad (success) {
  if (success) {
    // Display the value of the loaded variable


score


in the Output window
    trace(this.score);
  } else {
    trace("No variables were found");
  }
}

Note, however, that a success of true does not guarantee that the variables were properly formatted or useful, it merely indicates that the HTTP response's content was not empty. Occasionally, variable data is not received properly even when success is true . For example, a server-side script may have sent the wrong data, or stale data may have been read out of the browser cache. It is good practice to test explicitly for the variables we expect to receive before using them. For example, here we test for the variable msg before using it:

function handleLoad (success) {
  if (success) {
    // Check for


msg


if (this.msg != undefined) {
      // It's safe to proceed...
    } else {
      //


msg


didn't arrive...abort, or try loading the variables again...
    }
  } else {
    trace("No variables were found");
  }
}

The onLoad( ) handler alleviates the need to write custom polling code that waits for data to arrive after invoking load( ) or sendAndLoad( ) . For a complete example showing onLoad( ) and variable preloading techniques, see LoadVars.getBytesLoaded( ) and LoadVars.sendAndLoad( ) .

See Also

LoadVars.getBytesLoaded( ) , LoadVars.load( ) , LoadVars.onData( ) , LoadVars.sendAndLoad( )

Arguments

url

A string specifying the absolute or relative location of the external script or application that receives the variables.

target

A string specifying the name of the browser window or frame into which to load results. Can be a custom name or one of the four presets: "_blank" , "_parent" , "_self" , or "_top" .

method

An optional string specifying the HTTP method by which to send the properties of loadVarsObject to an external script—either "GET" or "POST" . If omitted, it defaults to "POST" . The Standalone Flash Player for Windows always uses the "GET" method, regardless of the method specified. See Appendix F for details on support for GET and POST.

Returns

A Boolean indicating whether the method executed successfully. Note that the return value is less useful than it appears. When passed any value for url (including undefined !), send( ) returns true . When invoked with no arguments, send( ) returns false .

Description

The send( ) method converts all properties of loadVarsObject to a string of URL-encoded variables, which it then sends to url in an HTTP request, using the method specified by method . If the script or application at url outputs a result, it is displayed in the browser frame or window specified by target . If the movie is running in the Standalone Player, the system's default browser is launched. See the global getURL( ) function for a detailed explanation of the target and method parameters. For an explanation of URL encoding, see the Description heading of the LoadVars class. The URL-encoded string sent to url can be viewed locally via the LoadVars.toString( ) method.

Note that the getURL( ) function also can pass variables to a remote script, but it is less convenient than LoadVars.send( ) because it requires the use of a movie clip to hold the variables.

Bugs

Macromedia's documentation states that when the target parameter is not specified, the script at url is executed, but the results are discarded. However, in Flash Player 6, tests show that when target is not specified, the send( ) the method fails to execute the script at url .

Example

The following code uses a LoadVars object to send the properties name and age as URL-encoded variables to the script userFind.pl :

// Create the


LoadVars


object
varSender = new LoadVars();
   
// Assign properties to the


varSender


object
// These are the variables sent to the server
varSender.name = "Bruce";
varSender.age = "13";
   
// Send variables to server, and catch reply in a new browser window
varSender.send("http://www.someserver.com/cgi-bin/userFind.pl", "_blank", "GET");

See Also

getURL( ) , LoadVars.onLoad( ) , LoadVars.sendAndLoad( ) , LoadVars.toString( )