Loading External Text Files In Flash ActionScript 3.0

Work Files:
Load_Text_Start.fla
summer.txt (right-click > save as )

In this article, we're going to learn how to load text from an external source into a Flash movie.

What is the benefit of loading text from an external source?
The nice thing about loading text externally is that when you need to update the text, then you simply need to edit the text file. You won't have to make changes to the .fla file anymore.

To load text from an external source, we will need the ff:

• a plain text file that contains the text we would like to load
• a URLRequest object to specify the path to the external text file
• a URLLoader object which will load the external text file into the Flash movie
• a TextField that will display the loaded text

2 exercise files accompany this tutorial:

1. Load_Text_Start.fla - this is the Flash movie where the external text will be loaded into
   
2. summer.txt - this is the plain text file that contains the text we will be loading into the Flash movie

The download links are found at the beginning of the article. Make sure that you save both files in the same folder. By the end of this tutorial, you should be able to load the external text into the Flash movie. And in succeeding articles, you will also learn how to format the text using a TextFormat object, and how to add text scrolling functionality.

So let's begin. Go ahead and open the Load_Text_Start.fla file. You will see that the document contains some artwork (a sun drawing) and 2 buttons (these buttons will be used to scroll the text up and down). We'll be creating a TextField which will be placed within the empty white area on the stage. This TextField will display the text loaded from the external source.

Let's now begin writing the code. Let's first create the TextField, add it to the display list and set some of it's properties. Select frame 1 of the Actions layer and go to the Actions Panel and type the ff:

// Create a TextField object
var myTextField:TextField = new TextField();

// Add the TextField object to the display list so that
// it will be visible on the stage
addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true; 
myTextField.width = 215; 
myTextField.height = 225; 
myTextField.x = 300; 
myTextField. y = 50;

If you test your movie now, you should see the TextField just above the scroll buttons and to the right of the sun artwork.

Now that we have the TextField, we'll need a URLRequest object and a URLLoader object in order to load the external text file. The URLRequest allows us to specify the path to the external file that we would like to load. In this example, we want to load the summer.txt file, which we saved in the same folder as the Flash document. So since they are in the same directory, all we have to do is specify the filename summer.txt when we create the URLRequest object. The URLLoader, on the other hand, has the capability to load external text files into Flash movies. It is the URLRequest object that simply tells the URLLoader which file it's supposed to load.

So to recap, the URLRequest specifies which file is to be loaded, while the URLLoader is the one that loads the specified file. Now, let's go ahead and create the URLRequest and URLLoader objects:

var myTextField:TextField = new TextField();

// This next line creates the URLRequest object named textURL.
// The file name of the external text file to be loaded is
// passed as a parameter to the URLRequest constructor.
var textURL:URLRequest = new URLRequest("summer.txt");

// This next line creates a URLLoader object named textLoader
var textLoader:URLLoader = new URLLoader();

addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

After creating the URLRequest and URLLoader objects, we can now tell Flash to load the external text file. The load() method of the URLLoader class is what instructs the URLLoader to load an external text file. The URLRequest object is passed as a parameter to the load() method so that the URLLoader will know which file it is supposed to load (ex. textLoader.load(textURL); ). But in addition to writing the load statement, we'll also need an event handler. Why is that? This is because we'll only be able to display the text in the TextField once the external text file has finished being loaded (and not while the loading process is still happening). Once the URLLoader begins to load the text file, we'll have to wait for the text file to be loaded completely, and only then can we display the text in the TextField. The event that will tell us when the file has been loaded completely is Event.COMPLETE (this event will be dispatched if and when the external text file has been successfully loaded). This event will be dispatched by the URLLoader object, so the event listener will be added to our URLLoader which we named textLoader. So let's go back to the Actions Panel and create the event handler and the load statement.

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

// This next lines adds an event listener that waits
// for the textLoader to completely load
// the external text file (Event.COMPLETE). Once loaded,
// the function named displayText will be called.
textLoader.addEventListener(Event.COMPLETE, displayText);

function displayText(e:Event):void 
{
     // This function will contain the code that will display the text in the 
     // TextField once the external text file has been loaded. But let's add
     // that code later. For now, let's just put in a trace statement.
     // This trace statement will just indicate that the file has loaded.
     trace("File loaded successfully.");
}

// This next line tells the TextLoader to load the
// external text file specified by the URLRequest object
// named textURL (which specifies the summer.txt file)
textLoader.load(textURL);

Now go ahead and test the movie. You should see the output window display the phrase File loaded successfully. So this means that the Event.COMPLETE event has been triggered and that the text file has been loaded successfully. If it doesn't, you might want to check that you typed in the correct file name - "summer.txt" - and that the text file is saved in the same directory as your Flash movie.

So now that the external text file has been loaded, where is the text? I don't see it.
What we've done so far is that we've simply just loaded the external text file. The text data is already in the Flash movie, we just haven't displayed it yet. So the next thing we need to do is to get the text data and then display it in the TextField.

Ok. So where exactly do I find the text data?
Once loaded, the text contained inside the external text file can be found in the URLLoader object that was used to load the external text file. That text can be accessed by using the data property of the URLLoader class (ex. textLoader.data).

And once I get the text data, how do I assign it to the TextField?
You'll use the same way you assign text to any TextField - by using the text property of the TextField class (ex. myTextField.text = textLoader.data; ). And REMEMBER, you'll have to do this only after the text file has been loaded completely. So you must place the text assignment statement inside the Event.COMPLETE listener function (which in this example is the displayText function).

So let's go back to the event listener function named displayText and let's remove the trace statement and replace it with the text assignment statement. But instead of typing textLoader.data inside the event listener function, we'll type in e.target.data . Since the even listener was added to the textLoader URLLoader object, then e.target will refer to textLoader as well. One advantage of using e.target is that we'll be able to use the same event listener function with other URLLoader objects as well (for example, we might want to have multiple URLLoader objects that load different external text files).

function displayText(e:Event):void 
{
     // This next line will assign the text from the external text file to the
     // TextField instance named myTextField
     myTextField.text = e.target.data;
}

Now if you test the movie, you should be able to see the text displayed inside the TextField.

Here's the code in full:

import flash.text.TextField;
import flash.net.URLRequest;
import flash.net.URLLoader;

var myTextField:TextField = new TextField();
var textURL:URLRequest = new URLRequest("summer.txt");
var textLoader:URLLoader = new URLLoader();

addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

textLoader.addEventListener(Event.COMPLETE, displayText);

function displayText(e:Event):void 
{
     myTextField.text = e.target.data;
}

textLoader.load(textURL);

In the next part, we'll style the text using a TextFormat object.

NEXT: Formatting Externally Loaded Text In Flash ActionScript 3.0