Loading External Text in Flash Using AS3 URLLoader

By Riyadh Al Balushi (Blue_Chi) | Flash CS3 | ActionScript 3.0 | Beginner

Flash is capable of loading external textual content at run time using the ActionScript 3 URLLoader Class. Loading external text at run time is a technique used to create Flash movies which can be easily updated without the need to go back to the FLA. The URLLoader Class is responsible for loading all textual content and that include in addition to regular text files, XML, HTML, and CSS.

The text shown in the Flash movie below is loaded from a separate text file each time this SWF is displayed.


Link to the text file

This tutorial will teach you how to use the URLLoader Class to load basic texts and a variable from a text file. This is a beginner ActionScript 3.0 tutorial that requires you to know only the basics of Event Handling in AS3 to be able to follow it.

The URLLoader is used to load textual content only. If you would like to know how to load graphical content please review the AS3 Loader Class tutorial.

Our tutorial is divided into the following small sections:

  1. Settings Up the Files
  2. Quick ActionScript 3.0 Test
  3. Code Explanation
  4. Displaying the External Content in a Text Field
  5. Loading Variables From a Text File

Setting Up The Files

The first step in loading an external file is to create it! Loading an external file is dead easy as long as both the external file and the Flash movie that calls it reside on the same server. To make it even much simpler and not care about the actual URL, we are going to place both the text file and the Flash movie in same folder.

Create a new folder to host all the files to be used in this project. Create in this folder a text file named myText, type any text in this text file and then save it.

Loading External Text in AS3

Notice for languages other than English: If you plan on loading text in any language other than English you will probably be using special characters. To make sure that your characters appear correctly you will need to encode your file using Unicode. The encoding options can usually be found in the Save As window of any text editor.

Once you have your text field saved, simply create a new Flash file in the same folder. You can name this file Text Loader though this will not really affect our project.

Flash File Saved in the Same Folder

Back in Flash - Quick Test

We are going to start coding right away. Right-click the only frame you have on your timeline and select Actions to open up the Actions panel. Copy and paste the code below to quickly see your external text displayed on the output window. Explanation will follow.

var myTextLoader:URLLoader = new URLLoader();

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
trace(e.target.data);
}

myTextLoader.load(new URLRequest("myText.txt"));

You can press Ctrl+Enter on your keyboard to see your text displayed the text output window!

Explanation

That was a quick test just to show you how easy it is to load an external text file. We are going to explain in detail now what that code does. In order to use the URLLoader Class you must follow the procedure described below:

  1. Create an instance of the URLLoader Class.
  2. Use an Event Listener to know when the file finishes loading.
  3. Create the Event Listener function to take action when notified by the Event Listener.
  4. Use the .load() method to load the actual text file.

This is a very simple process in real code as you have seen above. As with the majority with ActionScript 3.0 classes, the first step in using any of the classes is creating an instance of that class (instantiation). This can be simply done using the new operator. So the first line of our code simply creates an instance of the URLLoader Class and names it myTextLoader:

var myTextLoader:URLLoader = new URLLoader();

We then have to register an event listener to take action with the text file successfully finishes loading. This is simply done by using the .addEventListener to register our instance with the the event Event.COMPLETE and a function named onLoadded that we will later define with the action to be taken:

var myTextLoader:URLLoader = new URLLoader();

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

You can learn more about Events Listeners by reading our tutorial on Event Handling in ActionScript 3.0.

The next step is to create the function that will take action when called by the event listener. We have previously specified that this function will be called onLoaded. The task of this function will be simply to output the content of our text file in the test screen using the trace() command. The data of our text file can be accessed through a property named .data attached to the target of our COMPLETE event (i.e. our instance of the URLLoader Class). You should note that this property can only be accessed once the file has successfully loaded:

var myTextLoader:URLLoader = new URLLoader();

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
trace(e.target.data);
}

The final line with trigger the whole process by loading the text file using the .load() method. The .load() method actually loads the URL of the text you want to load. You should note that you cannot assign the URL directly as a string, but instead you must pass it as instance of the URLRequest Class as shown in the code below:

var myTextLoader:URLLoader = new URLLoader();

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
trace(e.target.data);
}

myTextLoader.load(new URLRequest("myText.txt"));
You can check the entry for the URLRequest Class in the ActionScript reference to learn more about it.

That should do it. You can again test the movie (Ctrl+Enter) to see the content of your text file in the output window.

Displaying the Text in a Text Field

Though this is not strictly part of this tutorial, but I thought that I will provide you with a quick example on how to display the content in a text field that we create dynamically. It is the same exact procedure, but we also have (1) to create an instance of the TextField Class, (2) set its .text property once the file is loaded and finally (3) display it on the screen by adding it to the display list. The code below show these three additional steps clearly in bold.

var myTextLoader:URLLoader = new URLLoader();
var myTextField_txt:TextField = new TextField();

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
myTextField_txt.text = e.target.data;
addChild(myTextField_txt);
}

myTextLoader.load(new URLRequest("myText.txt"));
The addChild() method adds the target object to the display list. If used on the main timeline without any qualification it will display the object on the screen, if used through an object, that target object will be displayed when the parent object is displayed.

If you are loading a string of text that exceeds one line you will also need to set the TextField properties .wrapText and .autoSize to make sure that you field is automatically stretched to show your entire text:

var myTextLoader:URLLoader = new URLLoader();
var myTextField_txt:TextField = new TextField();
myTextField_txt.wordWrap=true;
myTextField_txt.autoSize=TextFieldAutoSize.LEFT;


myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
myTextField_txt.text = e.target.data;
addChild(myTextField_txt);
}

myTextLoader.load(new URLRequest("myText.txt"));
Check the TextField Class entry in the ActionScript reference to learn about all the available properties of a text field.

Again, all you have to do now is test your movie to (Ctrl+Enter) see your text field and text!

Loading Variables From a Text File

In addition to the possibility of loading a whole chunk of text in Flash from a text file, it is possible to divide up this textual content into logical pieces using variables. So for example, if you have a string of text as a title, a block of text as the body text, and a string containing a URL. You have all these in a single text file, yet have each of them stored in a variable of its own.

This can be done by using the equals sign operator = to specify the value of a variable and the ampersand sign & to identify a new variable. If you open our original text file myText, you can replace its original content with the following to see some variables in action:

myTitle=Oman3D&myBody=Oman3D has many interesting tutorials&myURL=www.republicofcode.com

The code above defines three variables, myTitle, myBody, and myURL. The value of each of these variables is specified after an equals sign = while the start of a new variable (other than the first one) is specified using the ampersand sign &. Here is the same text field with the variable names and the operators only highlighted:

myTitle=Oman3D&myBody=Oman3D has many interesting tutorials&myURL=www.republicofcode.com

So how can we retrieve these variables using ActionScript? We first need to tell the Flash Player that we are loading variables and not simple text. This is done by setting a property of the URLLoader Class called URLLoaderDataFormat. We simply set its value to URLLoaderDataFormat.VARIABLES:

 

var myTextLoader:URLLoader = new URLLoader();
myTextLoader.dataFormat=URLLoaderDataFormat.VARIABLES;

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
trace(e.target.data);
}

myTextLoader.load(new URLRequest("myText.txt"));

Now instead of retrieving the entire content of the .data property of our target we drill deeper into the actual variables of the .data property which we have defined in our text file:

var myTextLoader:URLLoader = new URLLoader();
myTextLoader.dataFormat=URLLoaderDataFormat.VARIABLES;

myTextLoader.addEventListener(Event.COMPLETE, onLoaded);

function onLoaded(e:Event):void {
trace(e.target.data.myTitle);
trace(e.target.data.myBody);
trace(e.target.data.myURL);
}

myTextLoader.load(new URLRequest("myText.txt"));

No other changes are required. You can now test your movie (Ctrl+Enter) to see each of your variables displayed on a line on its own in the output window. The application of this technique will vary depending on the project you are working on. However, your should always considering using XML instead of text file variables if you would like to load small pieces of information that add logic to your project the XML Class provides a much more extensive set of methods for filtering and searching the loaded data.

This concludes our tutorial. You can download the source file of our last example here. If you have any comments or questions please post them at the Oman3D Forum.

-End of Tutorial.