LoadVars class

The LoadVars class lets you send all the variables in an object to a specified URL and lets you 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-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.

Availability

Flash Media Server 2

Property summary

Property

Description

LoadVars.contentType

The MIME type sent to the server when you call the LoadVars.send() or LoadVars.sendAndLoad() method.

LoadVars.loaded

A boolean value that indicates whether a LoadVars.load() or LoadVars.sendAndLoad() operation has completed (true) or not (false).

Method summary

Method

Description

LoadVars.addRequestHeader()

Adds or changes HTTP request headers (such as Content-Type or SOAPAction) sent with POST actions.

LoadVars.decode()

Converts the query string to properties of the specified LoadVars object.

LoadVars.getBytesLoaded()

Returns the number of bytes loaded from the last or current LoadVars.send() or LoadVars.sendAndLoad() method call.

LoadVars.getBytesTotal()

Returns the number of total bytes loaded during all LoadVars.send() or LoadVars.sendAndLoad() method calls.

LoadVars.load()

Downloads variables from the specified URL, parses the variable data, and places the resulting variables in the LoadVars object that calls the method.

LoadVars.send()

Sends the variables in the specified object to the specified URL.

LoadVars.sendAndLoad()

Posts the variables in the specified object to the specified URL.

LoadVars.toString()

Returns a string containing all enumerable variables in the specified object, in the MIME content encoding application/x-www-urlform-encoded.

Event handler summary

Event handler

Description

LoadVars.onData()

Invoked when data has completely downloaded from the server or when an error occurs while data is downloading from a server.

LoadVars.onHTTPStatus()

Invoked when Flash Media Interactive Server receives an HTTP status code from the server.

LoadVars.onLoad()

Invoked when a LoadVars.send() or LoadVars.sendAndLoad() operation has completed.

    LoadVars constructor

    new LoadVars()

    Creates a LoadVars object. You can use the methods of the LoadVars object to send and load data.

    Availability

    Flash Media Server 2

    Example

    The following example creates a LoadVars object called my_lv:

    var my_lv = new LoadVars();

    LoadVars.addRequestHeader()

    myLoadVars.addRequestHeader(header, headerValue)

    Adds or changes HTTP request headers (such as Content-Type or SOAPAction) sent with POST actions. There are two possible use cases for this method: you can pass two strings, header and headerValue, or you can pass an array of strings, alternating header names and header values.

    If multiple calls are made to set the same header name, each successive value replaces 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.

    Availability

    Flash Media Server 2

    Parameters

    header
    A string or an array of strings that represents an HTTP request header name.

    headerValue
    A string that represents the value associated with header.

    Example

    The following example adds a custom HTTP header named SOAPAction with a value of Foo to the my_lv object:

    var my_lv = new LoadVars(); 
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 a parameter to the addRequestHeader() method.

    var my_lv = new LoadVars(); 
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 the server can check.

    var my_lv = 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");

    LoadVars.contentType

    myLoadVars.contentType

    The MIME type sent to the server when you call the LoadVars.send() or LoadVars.sendAndLoad() method. The default is application/x-www-urlform-encoded.

    Availability

    Flash Media Server 2

    Example

    The following example creates a LoadVars object and displays the default content type of the data that is sent to the server:

    application.onConnect = function(client){ 
    this.acceptConnection(client); 
    var my_lv = new LoadVars(); 
    trace(my_lv.contentType); 
}; 
 
// Output to Live Log: application/x-www-form-urlencoded

    LoadVars.decode()

    myLoadVars.decode(queryString)

    Converts the query string to properties of the specified LoadVars object. 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.

    Availability

    Flash Media Server 2

    Parameters

    queryString
    A URL-encoded query string containing name-value pairs.

    Example

    The following example traces the three variables:

    application.onConnect = function(client){ 
    this.acceptConnection(client); 
    // Create a new LoadVars object. 
    var my_lv = 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]); 
    } 
};

    The following is output to the Live Log panel in the Administration Console:

    name=Mort&score=250000 
name -> Mort 
score -> 250000 
contentType -> application/x-www-form-urlencoded 
loaded -> false

    LoadVars.getBytesLoaded()

    myLoadVars.getByesLoaded()

    Returns the number of bytes loaded from the last or current LoadVars.load() or LoadVars.sendAndLoad() method call. The value of the contentType property does not affect the value of getBytesLoaded().

    Availability

    Flash Media Server 2

    Returns

    A number.

    See also

    LoadVars.getBytesTotal()

    LoadVars.getBytesTotal()

    myLoadVars.getBytesTotal()

    Returns the total number of bytes loaded into an object during allLoadVars.load() or LoadVars.sendAndLoad() LoadVars.load() or LoadVars.sendAndLoad()method calls. Each time a call to load() or sendAndLoad() is issued, the getBytesLoaded() method is reset, but the getBytesTotal() method continues to grow.

    The value of the contentType property does not affect the value of getBytesLoaded().

    Availability

    Flash Media Server 2

    Returns

    A number. Returns undefined if no load operation is in progress or if a load operation has not been initiated. Returns undefined if the number of total bytes can’t be determined—for example, if the download was initiated but the server did not transmit an HTTP content length.

    See also

    LoadVars.getBytesLoaded()

    LoadVars.load()

    myLoadVars.load(url)

    Downloads variables from the specified URL, parses the variable data, and places the resulting variables into the LoadVars object that calls the method. You can load variables from a remote URL or from a URL in the local file system; the same encoding standards apply to both.

    Any properties in the myLoadVars object that have the same names as downloaded variables are overwritten. The downloaded data must be in the MIME content type and be application/x-www-urlform-encoded.

    The LoadVars.load() method call is asynchronous.

    Availability

    Flash Media Server 2

    Parameters

    url  A string indicating the URL from which to download variables.

    Returns

    A boolean value indicating success (true) or failure (false).

    Example

    The following code defines an onLoad() handler function that signals when data is returned:

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

    LoadVars.loaded

    myLoadVars.loaded

    A boolean value that indicates whether a LoadVars.load() or LoadVars.sendAndLoad() operation has completed (true) or not (false).

    Availability

    Flash Media Server 2

    Example

    The following example loads a text file and writes information to the log file when the operation is complete:

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

    See also

    LoadVars.onLoad()

    LoadVars.onData()

    myLoadVars.onData(src){}

    Invoked when data has completely downloaded from the server or when an error occurs while data is downloading from a server.

    Availability

    Flash Media Server 2

    Parameters

    src
    A string or undefined; the raw (unparsed) data from a LoadVars.load() or LoadVars.sendAndLoad() method call.

    Details

    This handler is invoked before the data is parsed and can be used to call a custom parsing routine instead of the one built in to Flash Player. The value of the src parameter that is passed to the function assigned to LoadVars.onData() can be either undefined or a string that contains the URL-encoded name-value pairs downloaded from the server. If the src parameter is undefined, an error occurred while downloading the data from the server.

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

    Example

    The following example loads a text file and traces the content when the operation is complete:

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

    LoadVars.onHTTPStatus()

    myLoadVars.onHTTPStatus(httpStatus){}

    Invoked when Flash Media Interactive Server receives an HTTP status code from the server. This handler lets you capture and act on HTTP status codes.

    Availability

    Flash Media Server 2

    Parameters

    httpStatus
    A number; the HTTP status code returned by the server. For example, a value of 404 indicates that the server has not found a match for the requested URL. HTTP status codes can be found in sections 10.4 and 10.5 of the HTTP specification. (For more information, see the W3 website at www.w3.org.)

    Details

    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 Flash Media Interactive Server did not try to make the URL request.

    If Flash Media Interactive Server cannot get a status code, or if it cannot communicate with the server, the default value of 0 is passed to your ActionScript code.

    Example

    The following example shows how to use onHTTPStatus() to help with debugging. The example collects HTTP status codes and assigns their value and type to an instance of the LoadVars object. (Notice that this example creates the instance members this.httpStatus and this.httpStatusType at runtime.) The onData() handler uses these instance members to trace information about the HTTP response that can be useful in debugging.

    var myLoadVars = new LoadVars(); 
 
myLoadVars.onHTTPStatus = function(httpStatus) { 
    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) { 
    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) {} 
 
myLoadVars.load("http://weblogs.macromedia.com/mxna/flashservices/getMostRecentPosts.cfm");

    LoadVars.onLoad()

    myLoadVars.onLoad(success){}

    Invoked when a LoadVars.load() or LoadVars.sendAndLoad() operation has completed. If the variables load successfully, the success parameter is true. If the variables were not received, or if an error occurred in receiving the response from the server, the success parameter is false.

    If the success parameter is true, the myLoadVars object is populated with variables downloaded by the LoadVars.load() or LoadVars.sendAndLoad() operation, and these variables are available when the onLoad() handler is invoked.

    Availability

    Flash Media Server 2

    Parameters

    success
    A boolean value indicating whether the LoadVars.load() operation ended in success (true) or failure (false).

    Example

    The following example creates a new LoadVars object, attempts to load variables into it from a remote URL, and prints the result:

    myLoadVars = new LoadVars(); 
myLoadVars.onLoad = function(result){ 
    trace("myLoadVars load success is " + result); 
} 
myLoadVars.load("http://www.someurl.com/somedata.txt");

    LoadVars.send()

    myLoadVars.send(url [, target, method])

    Sends the variables in the myLoadVars object to the specified URL. All enumerable variables in the myLoadVars object are concatenated into a string that is posted to the URL by using the HTTP POST method.

    The MIME content type sent in the HTTP request headers is the value of LoadVars.contentType.

    Availability

    Flash Media Server 2

    Parameters

    url
    A string; the URL to which to upload variables.

    target
    A File object. If you use this optional parameter, any returned data is output to the specified File object. If this parameter is omitted, the response is discarded.

    method
    A string indicating the GET or POST method of the HTTP protocol. The default value is POST. This parameter is optional.

    Returns

    A boolean value indicating success (true) or failure (false).

    See also

    LoadVars.sendAndLoad()

    LoadVars.sendAndLoad()

    myLoadVars.sendAndLoad(url, target[, method ])

    Posts the variables in the myLoadVars object to the specified URL. The server response is downloaded and parsed as variable data, and the resulting variables are placed in the target object. Variables are posted in the same way as LoadVars.send(). Variables are downloaded into target in the same way as LoadVars.load().

    Availability

    Flash Media Server 2

    Parameters

    url
    A string; the URL to which to upload variables.

    target
    The LoadVars object that receives the downloaded variables.

    method
    A string; the GET or POST method of the HTTP protocol. The default value is POST. This parameter is optional.

    Returns

    A boolean value indicating success (true) or failure (false).

    LoadVars.toString()

    myLoadVars.toString()

    Returns a string containing all enumerable variables in myLoadVars, in the MIME content encoding application/x-www-form-urlencoded.

    Availability

    Flash Media Server 2

    Returns

    A string.

    Example

    The following example instantiates a new LoadVars() object, creates two properties, and uses toString() to return a string containing both properties in URL-encoded format:

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