external text

Load External Text into Flash MX, Page 4.

Advanced Techniques

Okay —, to be honest there are techniques far more advanced than what I’m about to cover, but for an introductory tutorial these are advanced enough!

Error Detection

Up until now, we have operated under the optimistic assumption that the data we asked for will just load as expected. In a reasonably perfect world this is a reasonable expectation. However, the onLoad callback offers a way to check the success of the operation. The Event Handler will accept one parameter: “success”. This will return a boolean value of either true or false, depending on whether the loading was successful or not. By “successful”, we merely mean that the server’s response to a request for data was not empty. We add a conditional check as follows:

myData = new LoadVars();
myData.onLoad = function(success){
if (success) {
myText_txt.text = this.content;
} else {
myText_txt = "no variables loaded";

If “success” returns as true, the function continues. If the server returns an empty response, “success” returns false and an error message is written to the text field. Note that even more sophisticated error checking is required to account for everything that might possibly go wrong, but for most purposes I consider this to be enough.

Multiple Variables

Your .txt file is not limited to defining one variable; it can contain many in this form:

variable1=value&variable2=value&variable3=value and so on

One way to apply this feature in a text field is to include a headline and body copy in the same .txt file. For instance:

headline=this is the headline&content=This text is the body copy.

If we create two text fields (“myHeadline_txt” and “myBody_txt”), they can both be populated by the same text file. Our onLoad function could be modified as follows:

myData.onLoad = function(success){
	if (success) {
		myHeadline_txt.text = this.headline;
		myBody_txt.text = this.content;
	} else {
		myBody_txt.text = "error loading variables";

Format Text With HTML Tags

Flash MX understands rudimentary HTML tags. It does not accept CSS instructions, forms or other advanced HTML tags, but it does understand enough to be quite useful. A complete list of legal HTML tags is available in the documentation.

In order to employ HTML tags, we need to modify the .txt file (inserting the tags), the properties of the text field and the ActionScript code.

With the text field selected, check the “render text as html” tile in the Properties Palette:

render text as html property

Next, open the ActionScript editor and modify the code as follows:

myData.onLoad = function(success){
if (success) {
myHeadline_txt.htmlText = this.headline;//note: .htmlText, not .text
myBody_txt.htmlText = this.content;//note: .htmlText, not .text
} else {
myBody_txt.htmlText = "error loading variables";

Test your movie and notice how it has changed. The source for this example is available here.

Load Text in a Floating Window

So far we have kept to a text field at the _root level. Creating a floating window requires that we create the dynamic text field(s) in a MovieClip. This is scarcely any harder than what we have done so far. Note that the code wich loads the data can exist on the timeline of the MovieClip or the movie’s main timeline. For this demo I will use the latter approach to demonstrate how to target the text field in the clip. Because the focus of this tutorial is on working with external text files, the techniques involved in dragging the window are not covered. Look in the source file for this project if you are interested in that aspect.

I will assume you are familiar with the basics of creating MovieClips, so I won’t belabor that process. Press command/control F8 to create a new MovieClip, and name it something meaningful, such as “window1”.. Add whatever features and ornaments you wish. Don’t forget to create the dynamic text field or fields, just as you did in the earlier examples. Be sure to give each text field an instance name — this is just as important now as it was before. Add the ScrollBar component if that feature is required.

Return to the movie’s main timeline. Drag your clip from the library to the stage. Be sure to give the clip an instance name too. For this example, let’s identify the clip as “window1_mc”. (As we learned earlier with the suffix “_txt”, the suffix “_mc” will trigger Flash’s code hinting feature.)

Nearly there. All that remains is a small modification of the ActionScript to target the text field(s) in the clip instead of the _root timeline:

myData.onLoad = function(success){
if (success) {
window1_mc.myHeadline_txt.htmlText = this.headline;
window1_mc.myBody_txt.htmlText = this.content;
} else {
myBody_txt.htmlText = "error loading variables";

The source for this project is available here.

The techniques in these four pages should be enough to allow you to cope with the majority of things you will need to get external text files to display in a Flash movie. If you do have a server–side script that generates dynamic content, experiment with pointing Flash at that script instead of a static .txt file and savor the possibilites available to you now!

A note about unicode: You can embed unicode characters in an external text file and they should show up in your Flash movie (as demonstrated in the movie above) IF you are careful to save the text file as “UTF–8” (many text editors are capable of this, including NotePad, TextEdit, BBEdit and many more I am sure; most of the ones I use require that you select “save as” to access this feature).

If you find you are experiencing difficulties with unicode characters showing up perfectly when you test your Flash movie but getting mangled when you post your text files to a server, look first at your FTP client. I spent many hours of frustration until I discovered that the FTP client I was using (Fetch) has a preference setting called “Translate ISO Characters”; this was turned on by default. I can’t blame Fetch - it was trying to be helpful (by filtering out accidental non–ASCII characters you sometimes pick up when copying and pasting text from a word processor for instance). However, the unintended consequence was that it was also translating the non–ASCII characters I wanted to display! Once I disabled that preference, unicode characters in my external text files showed as expected. Just a little tip from the trenches!

Custom Scroll Mechanism

Macromedia worked very hard to create Components in Flash MX so that developers could concentrate on new ideas instead of spending their time creating the same interface widgets over and over again.

However, efficient though they are, sometimes the Components don’t fit with a custom user interface. Sometimes it’s worth the effort to cook up an interface widget from scratch. This tutorial isn’t going to go step-by-step through the process of creating a custom scroll mechanism. However, a carefully commented .fla is provided. Download the demo .fla file here. Examine the code and library contents and you should have enough information to create one yourself!

Reader Responses

Tutorial readers always encounter some issues that the tutorial author didn’t cover. When more than one individual writes with the same issue it’s clear to me I should have addressed it. For the benefit of other readers I will mention a few of the “gotchas” that have perplexed readers.

Masks and type visibility
It should be possible to load a .swf of the text movie into another movie. For example you might have a small Flash movie that loads and displays some welcome text or some recent news. You might choose to import this movie into a container movie to keep things modular. That is a good strategy actually. However, if your container movie utilizes a mask layer, be advised that you must embed your font in the dynamic text field or it will be blocked by the mask.

The ampersand
As we learned above in the “Multiple Variables” section, an ampersand symbol (“&”) is used to indicate to Flash the start of a new variable. But what if your external text file has one or more ampersands in the text (or the title of a song, or a book, or a company name…) that is supposed to be part of the text? Well, the short answer to that question is that your external text will abruptly stop displaying at the first instance of an ampersand. Hair pulling on the part of the developer is a common consequence.

The fix requires two steps. First, the external text document needs to have every instance of an ampersand symbol that is not meant to indicate a new variable replaced with the ASCII string “%26” (that is, the percent sign, a two and a six). It is a bit of a chore, but most text editors can do a multiple find and replace.

Next, you have to tell Flash that the source file has been encoded, and that you want Flash to unencode the data before displaying it. Flash conveniently has a built in function that does that job: unescape(). You would modify your ActionScript to something along these lines (naturally using the text field and variable names you have used in your own project):

myText_txt.text = unescape(this.content);


During the course of writing this tutorial, I took both inspiration and information from several sources, including

1 | 2 | 3 | 4

divider ornament