| LoadVars Class | Flash 6 |
| export variables to, or import variables from, an external source |
new LoadVars()
The MIME content type used for send( ) and sendAndLoad( ) operations.
Status of a load( ) or sendAndLoad( ) operation.
Convert a URL-encoded string of variables to properties.
Check what portion of loading variables has arrived, in bytes.
Check the expected total byte size of loading variables.
Import URL-encoded variables from a text file or a server-side application.
Transfer URL-encoded variables to a server-side application or script.
Transfer variables to a server-side application, and receive variables in return.
Returns the URL-encoded string of variables that would be sent by send( ) or sendAndLoad( ).
Handler executed when external variable data finishes loading.
Handler executed when external variables have been converted into object properties.
The LoadVars class transfers variables to or from an external source, such as a text file or a server-side script. Table 18-9 shows typical LoadVars usage scenarios and lists the method associated with each scenario.
|
Desired Action |
Method |
|---|---|
|
Retrieve external variables from a text file or server-side script. |
LoadVars.load( ) |
|
Send ActionScript variables to a server-side script, and receive optional results in a web browser. |
LoadVars.send( ) |
|
Send ActionScript variables to a server-side script, and receive results in Flash. |
LoadVars.sendAndLoad( ) |
The send( ), load( ), and sendAndLoad( ) methods must be invoked through an instance of LoadVars, not through the class itself. The properties of the instance are either the variables to be sent or those that have been received. The send( ) method converts the properties of the LoadVars instance to a string of URL-encoded variables, and sends them as an HTTP request to a server-side application. The load( ) method retrieves URL-encoded variables and converts them to properties of the LoadVars object. The sendAndLoad( ) method does both. For details and examples, see each method's listing.
The LoadVars class provides the same basic service as the global loadVariables( ) function, first introduced in Flash 4, but in a more logical format and with several important advantages:
An onLoad( ) handler executes when variables arrive, notifying you automatically rather than requiring you to poll for results as you must with loadVariables( ).
Variable load progress can be monitored with getBytesLoaded( ) and getBytesTotal( ), allowing you to diagnose problems or provide a status bar during lengthy operations.
Variables are stored as properties of LoadVars objects, not in physical movie clips, allowing you to separate code from media more effectively. This also allows you to send a subset of variables from a timeline, rather than sending all variables on a timeline, as is the case with loadVariables( ).
Variables transferred by a load( ) or sendAndLoad( ) operation are formatted according to the rules of URL encoding, as follows:
Every variable name is separated from its value with an equals sign, without spaces, as in firstName=stephen.
Multiple variable name/value pairs are separated by ampersands (&), as in firstName=stephen&lastName=burke.
Spaces are replaced with plus (+) signs, not %20.
Any character that is not a space, a number (1-9), or an unaccented Latin 1 letter (a-z or A-Z) is replaced as follows:
If System.useCodepage is false (the default), the character is replaced by one or more hexadecimal escape sequences of the form %xx, representing the UTF-8 sequence for the character. Characters in the Unicode range 0-127 are encoded as %xx (single-byte), characters 128-2047 are encoded as %xx%xx (double-byte), and characters 2048 and above are encoded as %xx%xx%xx (triple-byte).
If System.useCodepage is true and the system is not an Asian language double-byte system, the character is replaced with a hexadecimal escape sequence %xx, where xx is the hex code point for the character. The code point is determined using the system code page (typically Latin 1 on most Western computers). Note that on Macs, the system code page is Mac Roman, but Flash uses Latin 1 instead.
If System.useCodepage is true and the system is an Asian language double-byte system, the character is replaced with a hexadecimal escape sequence %xx or %xx%xx, using the double-byte character encoding supported by the system (for example, Shift-JIS).
Flash 5 and previous Players behave as if System.useCodepage is true.
The following code shows the contents of a text file to be imported into Flash. The imported variables are name and address, which have the values "stephen" and "65 nowhere st!", respectively (note that the exclamation point is encoded as %21):
name=stephen&address=65+nowhere+st%21
Generally, server-side applications automatically URL encode variables for transmission to Flash, but variables in text files must be URL-encoded by hand. For example, in Flash Player 5 (or when System.useCodePage is true in Flash Player 6), the high-ASCII character é is at code point 233, which is hex E9, so it is written manually as %E9. The word resumé becomes resum%E9. In contrast, in Flash Player 6, when System.useCodePage is false (the default), the character é should be entered directly, and the variables file should be saved in Unicode UTF-8 format. (In Windows Notepad, the UTF-8 format can be chosen in the "Save as..." dialog box.) If the file cannot be saved as UTF-8, or if the character cannot be entered directly, the single-, double-, or triple-byte UTF-8 escape sequence for the character must be used. For example, the UTF-8 sequence for é is %C3%A9, so the word resumé would be written as resum%C3%A9. You can check the UTF-8 escape sequence for a character in Flash Player 6 using the escape( ) function. For example:
trace(escape("é")); // Displays: %C3%A9
As a general rule, where many international characters are required, data should be loaded from Unicode-formatted XML files rather than via LoadVars.
For security reasons, LoadVars works only with hosts in the domain from which the movie was downloaded. For more information, see System.security.
The LoadVars class is not always the best means of importing data into Flash. For variables that need to be imported only once at load-time in a browser, consider using the FLASHVARS attribute of the HTML <OBJECT> and <EMBED> tags (see Section 2.6). For large quantities of data, consider using the XML class.
loadVariables( ), System.security, the XML class; "Loading External Variables," in Chapter 2; Chapter 17