| XML.onLoad( ) Event Handler | Flash 5 |
| executed when external XML data has been loaded and parsed |
A Boolean value indicating whether loading was successful (true) or unsuccessful (false).
The onLoad( ) handler of xmlDoc executes automatically whenever an external XML file is loaded into xmlDoc via the load( ) or sendAndLoad( ) methods. The specified xmlDoc must be the top-level node in an XML object hierarchy (i.e., an instance of the XML class, not the XMLnode class).
By default, the onLoad( ) handler of an XML document object is undefined. To use onLoad( ), we assign it a callback handler (i.e., a custom-made function). For example:
myDoc = new XML();
myDoc.onLoad = handleLoad;
function handleLoad (success) {
// Process XML as desired here...
}
We rely on onLoad( ) events to tell us when it's safe to process xmlDoc. If onLoad( ) is triggered, we know that the loading and parsing of external XML data have completed, so we can safely access that loaded content. Hence, the onLoad( ) handle alleviates the need to write preloading code to wait for data to arrive after the invocation of an XML load( ) function. For example, in the following code we load an XML document and then wait for our custom handleLoad( ) function to execute automatically when loading completes. If loading was successful, we process our XML content with the displayProduct( ) function. Otherwise, we show an error message by executing the displayError( ) function. (The displayProduct( ) and displayError( ) functions are custom functions that we've written to display information to the user, but they are not shown here.) Here is the code:
myDoc = new XML();
myDoc.onLoad = handleLoad;
myDoc.load("productInfo.xml");
function handleLoad(success) {
if (success) {
output = "Product information received";
displayProduct(); // Call custom display function
} else {
output = "Attempt to load XML data failed";
displayError(); // Call custom error display function
}
}
Notice that we assign our onLoad( ) callback before invoking load( ), which guarantees that the handler is available when the load( ) operation completes.
The value of the success argument sent to handleLoad( ) is set automatically by the interpreter to either true or false, indicating whether loading completed properly. In Flash 6, success is false for File Not Found (404) conditions and for security violations (see System.security.allowDomain( )). However, in Flash 5, the reception of an HTML error page from the server results in the parsing of that page into the target XML document object. Because the page parses properly, the load attempt is considered "successful" and success is set to true, even though the actual XML file may not have been found or some other server error may have been encountered.
In all cases, to be positive that you have the real data you requested, test its structure or content explicitly for some identifying characteristic, such as the nodeName of a particular child. Check XML.status to determine whether parsing succeeded. See also the XML.onData( ) event handler, which can be used to perform custom parsing.
XML.load( ), XML.onData( ), XML.sendAndLoad( ), XML.status
