Table of Contents

loadVarsObject.onLoad(success)

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( )

Table of Contents