LoadVars.onLoad( ) Event Handler

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

LoadVars.onLoad( ) Event Handler

Flash 6

handler executed after external variables have been converted into object properties

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

Arguments

Description

See Also