Flash 8 ActionScript 2.0 Language Reference

Class LoadVars

Object

The LoadVars class lets you send all the variables in an object to a specified URL and to load all the variables at a specified URL into an object. It also lets you send specific variables, rather than all variables, which can make your application more efficient. You can use the LoadVars.onLoad handler to ensure that your application runs when data is loaded, and not before.

The LoadVars class works much like the XML class; it uses the load(), send(), and sendAndLoad() methods to communicate with a server. The main difference between the LoadVars class and the XML class is that LoadVars transfers ActionScript name and value pairs, rather than an XML Document Object Model (DOM) tree stored in the XML object. The LoadVars class follows the same security restrictions as the XML class.

contentType Property

public contentType : String

var my_lv:LoadVars = new LoadVars();
trace(my_lv.contentType);  // output: application/x-www-form-urlencoded

loaded Property

public loaded : Boolean

This property is similar to the XML.loadedproperty.

var my_lv:LoadVars = new LoadVars();
my_lv.onLoad = function(success:Boolean) {
    trace("LoadVars loaded successfully: "+this.loaded);
};
my_lv.load("http://www.helpexamples.com/flash/params.txt");

onData Event Handler

public onData = function(src:String) {}

The default implementation of LoadVars.onData invokes LoadVars.onLoad. You can override this default implementation by assigning a custom function to LoadVars.onData, but LoadVars.onLoad is not called unless you call it in your implementation of LoadVars.onData.

var my_lv:LoadVars = new LoadVars();
my_lv.onData = function(src:String) {
    if (src == undefined) {
        trace("Error loading content.");
        return;
    }
    content_ta.text = src;
};
my_lv.load("content.txt", my_lv, "GET");

onHTTPStatus Event Handler

public onHTTPStatus = function(httpStatus:Number) {}

The onHTTPStatus handler is invoked before onData, which triggers calls to onLoad with a value of undefined if the load fails. After onHTTPStatus is triggered, onData is always triggered, whether or not you override onHTTPStatus. To best use the onHTTPStatus handler, you should write a function to catch the result of the onHTTPStatus call; you can then use the result in your onData and onLoad handlers. If onHTTPStatus is not invoked, this indicates that the player did not try to make the URL request. This can happen because the request violates security sandbox rules for the SWF file.

If Flash Player cannot get a status code from the server, or if it cannot communicate with the server, the default value of 0 is passed to your ActionScript code. A value of 0 can be generated in any player (for example, if a malformed URL is requested), and a value of 0 is always generated by the Flash Player plug-in when it is run in the following browsers, which do not pass HTTP status codes to the player: Netscape, Mozilla, Safari, Opera, and Internet Explorer for the Macintosh.

var myLoadVars:LoadVars = new LoadVars();

myLoadVars.onHTTPStatus = function(httpStatus:Number) {
    this.httpStatus = httpStatus;
    if(httpStatus < 100) {
        this.httpStatusType = "flashError";
    }
    else if(httpStatus < 200) {
        this.httpStatusType = "informational";
    }
    else if(httpStatus < 300) {
        this.httpStatusType = "successful";
    }
    else if(httpStatus < 400) {
        this.httpStatusType = "redirection";
    }
    else if(httpStatus < 500) {
        this.httpStatusType = "clientError";
    }
    else if(httpStatus < 600) {
        this.httpStatusType = "serverError";
    }
}

myLoadVars.onData = function(src:String) {
    trace(">> " + this.httpStatusType + ": " + this.httpStatus);
    if(src != undefined) {
        this.decode(src);
        this.loaded = true;
        this.onLoad(true);
    }
    else {
        this.onLoad(false);
    }
}

myLoadVars.onLoad = function(success:Boolean) {
}
    
myLoadVars.load("http://weblogs.macromedia.com/mxna/flashservices/getMostRecentPosts.cfm");

onLoad Event Handler

public onLoad = function(success:Boolean) {}

This handler is undefined by default.

This event handler is similar to XML.onLoad.

var submitListener:Object = new Object();
submitListener.click = function(evt:Object) {
    var result_lv:LoadVars = new LoadVars();
    result_lv.onLoad = function(success:Boolean) {
        if (success) {
            result_ta.text = result_lv.welcomeMessage;
        } else {
            result_ta.text = "Error connecting to server.";
        }
    };
    var send_lv:LoadVars = new LoadVars();
    send_lv.name = name_ti.text;
    send_lv.sendAndLoad("http://www.flash-mx.com/mm/greeting.cfm", result_lv, "POST");
};
submit_button.addEventListener("click", submitListener);

LoadVars Constructor

public LoadVars()

var my_lv:LoadVars = new LoadVars();

addRequestHeader Method

public addRequestHeader(header:Object, headerValue:String) : Void

If multiple calls are made to set the same header name, each successive value will replace the value set in the previous call.

The following standard HTTP headers cannot be added or changed with this method: Accept-Ranges, Age, Allow, Allowed, Connection, Content-Length, Content-Location, Content-Range, ETag, Host, Last-Modified, Locations, Max-Forwards, Proxy-Authenticate, Proxy-Authorization, Public, Range, Retry-After, Server, TE, Trailer, Transfer-Encoding, Upgrade, URI, Vary, Via, Warning, and WWW-Authenticate.

my_lv.addRequestHeader("SOAPAction", "'Foo'");

The following example creates an array named headers that contains two alternating HTTP headers and their associated values. The array is passed as an argument to addRequestHeader().

var headers = ["Content-Type", "text/plain", "X-ClientAppVersion", "2.0"];
my_lv.addRequestHeader(headers);

The following example creates a new LoadVars object that adds a request header called FLASH-UUID. The header contains a variable that can be checked by the server.

var my_lv:LoadVars = new LoadVars();
my_lv.addRequestHeader("FLASH-UUID", "41472");
my_lv.name = "Mort";
my_lv.age = 26;
my_lv.send("http://flash-mx.com/mm/cgivars.cfm", "_blank", "POST");

decode Method

public decode(queryString:String) : Void

This method is used internally by the LoadVars.onData event handler. Most users do not need to call this method directly. If you override the LoadVars.onData event handler, you can explicitly call LoadVars.decode() to parse a string of variables.

// Create a new LoadVars object
var my_lv:LoadVars = new LoadVars();
//Convert the variable string to properties
my_lv.decode("name=Mort&score=250000");
trace(my_lv.toString());
// Iterate over properties in my_lv
for (var prop in my_lv) {
    trace(prop+" -> "+my_lv[prop]);
}

getBytesLoaded Method

public getBytesLoaded() : Number

var loadvars_pb:mx.controls.ProgressBar;
var my_lv:LoadVars = new LoadVars();
loadvars_pb.mode = "manual";
this.createEmptyMovieClip("timer_mc", 999);
timer_mc.onEnterFrame = function() {
    var lvBytesLoaded:Number = my_lv.getBytesLoaded();
    var lvBytesTotal:Number = my_lv.getBytesTotal();
    if (lvBytesTotal != undefined) {
    trace("Loaded "+lvBytesLoaded+" of "+lvBytesTotal+" bytes.");
    loadvars_pb.setProgress(lvBytesLoaded, lvBytesTotal);
    }
};
my_lv.onLoad = function(success:Boolean) {
    loadvars_pb.setProgress(my_lv.getBytesLoaded(), my_lv.getBytesTotal());
    delete timer_mc.onEnterFrame;
    if (success) {
    trace("LoadVars loaded successfully.");
    } else {
    trace("An error occurred while loading variables.");
    }
};
my_lv.load("[place a valid URL pointing to a text file here]");

getBytesTotal Method

public getBytesTotal() : Number

var loadvars_pb:mx.controls.ProgressBar;
var my_lv:LoadVars = new LoadVars();
loadvars_pb.mode = "manual";
this.createEmptyMovieClip("timer_mc", 999);
timer_mc.onEnterFrame = function() {
    var lvBytesLoaded:Number = my_lv.getBytesLoaded();
    var lvBytesTotal:Number = my_lv.getBytesTotal();
    if (lvBytesTotal != undefined) {
    trace("Loaded "+lvBytesLoaded+" of "+lvBytesTotal+" bytes.");
    loadvars_pb.setProgress(lvBytesLoaded, lvBytesTotal);
    }
};
my_lv.onLoad = function(success:Boolean) {
    loadvars_pb.setProgress(my_lv.getBytesLoaded(), my_lv.getBytesTotal());
    delete timer_mc.onEnterFrame;
    if (success) {
    trace("LoadVars loaded successfully.");
    } else {
    trace("An error occurred while loading variables.");
    }
};
my_lv.load("[place a valid URL pointing to a text file here]");

load Method

public load(url:String) : Boolean

The downloaded data must be in the MIME content type application/x-www-form-urlencoded.

This method is similar to XML.load().

Note: If a file being loaded contains non-ASCII characters (as found in many non-English languages), it is recommended that you save the file with UTF-8 or UTF-16 encoding as opposed to a non-Unicode format like ASCII.

When using this method, consider the Flash Player security model:

For Flash Player 8:

• Data loading is not allowed if the calling SWF file is in the local-with-file-system sandbox and the target resource is from a network sandbox.
• Data loading is also not allowed if the calling SWF file is from a network sandbox and the target resource is local.

For more information, see the following:

• "Understanding Security" in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

For Flash Player 7 and later websites can permit cross-domain access to a resource via a cross-domain policy file. In SWF files of any version running in Flash Player 7 and later, url must be in exactly the same domain. For example, a SWF file at www.someDomain.com can load data only from sources that are also at www.someDomain.com.

var my_lv:LoadVars = new LoadVars();
my_lv.onLoad = function(success:Boolean) {
    if (success) {
    trace(this.toString());
    } else {
    trace("Error loading/parsing LoadVars.");
    }
};
my_lv.load("http://www.helpexamples.com/flash/params.txt");

send Method

public send(url:String, target:String, [method:String]) : Boolean

You must specify the target parameter to ensure that the script or application at the specified URL will be executed. If you omit the target parameter, the function will return true, but the script or application will not be executed.

The send() method is useful if you want the server response to:

• Replace the SWF content (use "_self" as the target parameter);
• Appear in a new window (use "_blank" as the target parameter);
• Appear in the parent or top-level frame (use "_parent" or "_top" as the target parameter);
• Appear in a named frame (use the frame's name as a string for the target parameter).

A successful send() method call will always open a new browser window or replace content in an existing window or frame. If you would rather send information to a server and continue playing your SWF file without opening a new window or replacing content in a window or frame, then you should use LoadVars.sendAndLoad().

This method is similar to XML.send().

The Flash test environment always uses the GET method. To test using the POST method, be sure you are attempting to use it from within a browser.

When using this method, consider the Flash Player security model:

• For Flash Player 8, the method is not allowed if the calling SWF file is in an untrusted local sandbox.
• For Flash Player 7 and later, the method is not allowed if the calling SWF file is a local file.

For more information, see the following:

• "Understanding Security" in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

var my_lv:LoadVars = new LoadVars();
my_lv.playerName = playerName_txt.text;
my_lv.playerScore = playerScore_txt.text;
my_lv.send("setscore.cfm", "_blank", "POST");

sendAndLoad Method

public sendAndLoad(url:String, target:Object, [method:String]) : Boolean

Variables are posted in the same manner as LoadVars.send(). Variables are downloaded into target in the same manner as LoadVars.load().

When using this method, consider the Flash Player security model:

For Flash Player 8:

• Data loading is not allowed if the calling SWF file is in the local-with-file-system sandbox and the target resource is from a network sandbox.
• Data loading is also not allowed if the calling SWF file is from a network sandbox and the target resource is local.

For more information, see the following:

• "Understanding Security" in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

For Flash Player 7 and later:

• Websites can permit cross-domain access to a resource via a cross-domain policy file.
• In SWF files of any version running in Flash Player 7 and later, url must be in exactly the same domain. For example, a SWF file at www.someDomain.com can load data only from sources that are also at www.someDomain.com.

In SWF files that are running in a version of the player earlier than Flash Player 7, url must be in the same superdomain as the SWF file that is issuing this call. A superdomain is derived by removing the left-most component of a file's URL. For example, a SWF file at www.someDomain.com can load data from sources at store.someDomain.com because both files are in the same superdomain named someDomain.com.

This method is similar to XML.sendAndLoad().

var submitListener:Object = new Object();
submitListener.click = function(evt:Object) {
    var result_lv:LoadVars = new LoadVars();
    result_lv.onLoad = function(success:Boolean) {
    if (success) {
        result_ta.text = result_lv.welcomeMessage;
    } else {
        result_ta.text = "Error connecting to server.";
    }
    };
    var send_lv:LoadVars = new LoadVars();
    send_lv.name = name_ti.text;
    send_lv.sendAndLoad("http://www.flash-mx.com/mm/greeting.cfm", result_lv, "POST");
};
submit_button.addEventListener("click", submitListener);

toString Method

public toString() : String

var my_lv:LoadVars = new LoadVars();
my_lv.name = "Gary";
my_lv.age = 26;
trace (my_lv.toString()); //output: age=26&name=Gary