Macromedia Flash MX 2004 ActionScript Programming Tutorial

Loading External Variables

Besides declaring variables within your Flash movie, you can use the loadVariables() action to send and load variables to and from an external source, such as a server-side script or text file. The loadVariables() action has three parameters: URL, target, and method:

loadVariables(URL, target, method);

The URL parameter specifies the location of the external file, whether that’s a text file or a web page containing a server-side script. The target parameter specifies a timeline target in the movie (such as a movie clip instance) into which the variables should be loaded. Both of these parameters can be expressed using absolute or relative paths, as well as with variables.

The method parameter is optional, and can be either GET or POST. You specify a method when sending data to a server-side script.

The loadVariablesNum() action performs the same task, but requires you to specify the target as a level. If you’re targeting a specific movie clip, use the loadVariables() action instead.

ActionScript’s LoadVars class has improved on the loadVariables action, giving you more control over data being sent to, and received from, a server-side script. Later, we’ll create a Flash form that uses LoadVars to send information stored in variables to an ASP script. But the loadVariables action works well for loading variables from external files. To give you an idea of how this works, we’ll use loadVariables to load the contents of a text file into a dynamic text field:

1. Below, we’ve drawn a large dynamic text field on the stage:

In the Property Inspector, we assigned the field the variable scenedescription, which stores the description of the first scene of a fictional movie.

The dynamic text field will display the contents of the variable scenedescription, which will be stored in an external text file.

1. We named the text field instance “txt_scenedescription” and set the display options we wanted for the text—Arial 12-point font, white text color. We made sure the field was set to display as Multiline and that the text would render as HTML . Rending the text as HTML lets us include some simple HTML formatting tags in our text file, so certain elements appear in bold.

1. Open Notepad or a similar text editing program and type the following text:

scenedescription=<p></p>

The word “scenedescription” at the beginning of the file declares the scenedescription variable, with the value of the variable appearing on the right side of the equal sign (=). The variable must be declared at the top of the file with an equal sign followed by the string value in URL-encoded format.

Multiple variables can be declared in a single file with the syntax:

variable1=sometext&variable2=sometext&variable3=sometext

Note:

The loadVariablesNum() and loadVariables() actions require the text file to be URL-encoded—that is, any special characters must be typed with the URL-encoded equivalent (which begins with a % sign).

1. Between the paragraph tags (<p></p>), type some text you’d like to appear in the text field. If you like, include some simple HTML tags (this only works with simple formatting tags, like the Bold (<B></B>) tag).

This is what our text file looks like:

1. Save the text file as “scene1.txt” and place it in the same folder as your movie.
2. We now need to add the loadVariablesNum() action to load the text file into the field. Click on the first frame of the Actions layer and, in the Actions panel, click the Add item button. This opens a menu of available actions, which are organized just like the folders in the Actions toolbox on the left. Select Global Functions, then Browser/Network, and then loadVariablesNum.

When you add the action, Flash displays a code hint that shows you the required parameters:

Because we’ve saved our text file in the same directory as our Flash movie, we can just type the name of the file, in quotation marks. Add a comma and then a 0 for the level. Since we won’t be relaying or receiving information using the text file, we can leave the third parameter, method, blank.

When you’ve finished, the code should look like the following:

1. Now test the movie:

Taking this example one step further, we can assign variables representing different text files to the click (or release) events of buttons on the stage, so when the user clicks the button for a particular scene, the corresponding scene description is displayed:

1. Open the text file and change the variable at the top from scenedescription to scenedescription1. Save the file.
2. Make a copy of the text file, saving it as “scene2.txt”. In the second text file, change the variable being declared to scenedescription2. Change the text in the body of the file so you’ll be able to tell the difference between the two when you test the movie. Save both files in the same directory as your Flash file.
3. In Flash, select the dynamic text field and change the variable name in the var field of the Property Inspector to scenedescription1. This ensures that default text (the description of Scene1) is displayed as soon as the movie loads.

1. Next, open the Actions panel and add a second loadVariablesNum() action, this time specifying the name of the second text file:

Although you could include the loadVariablesNum() or loadVariables() function in the event handler of the button, Flash takes a while to load the text files, so including these actions (the first of which is required for the default text to load at the start of the movie) outside the event handlers, in the first frame of the main timeline, ensures that the text is already loaded and waiting when the user clicks the buttons. Otherwise, you risk the user seeing “undefined” displayed in the text field the first time he or she clicks a button other than the first one.

1. Now we need to add the event handlers to our buttons. Our buttons are static text fields with the scene numbers, which we’ve converted to button symbols. To add the script to the first button, select it and, if necessary, re-open the Actions panel. Type the following code:

The code should be fairly straightforward: “txt_scedescription” is the name of our dynamic text field; .htmlText is a property of the TextField object, which renders HTML contents in the text field. If the contents were plain text, you could use .text instead. scenedescription1 is the variable declared in the first text file.

1. For the second button, we’ll add the same code, but change the variable to scenedescription2, the variable declared in the second text file:

1. Now test the movie. The contents of the first text file should appear as soon as the movie loads:

Click the second button. The dynamic text field should display the contents of the second text file:

Click the first button again to make sure the text field again displays the contents of the first file.

As we mentioned earlier, you can use the loadVariables() and loadVariablesNum() actions to load any number of variables from an external file. For example, you might use a text file to store user data that includes the user’s first name, last name, and phone number. The name/value pairs can be saved in the text file, with each pair separated by an ampersand (&):

firstname=Jane&lastname=Smith&phone=555-5555

When used with the GET or POST method, the loadVariables() and loadVariablesNum() actions can send the name/value pairs to a server, which in turn sends name/value pairs back to the movie. If you want to send data to a server without receiving a response, you can use the getURL() action, described in the next section.