Preloading TLF runtime shared libraries in Flash Professional CS5.5

Adobe Flash Professional CS5 introduced a new type of text field to Flash called TLF text. TLF text has several advantages over Classic text, such as advanced formatting options, better font compression and rendering, and support for complexly formatted languages. In order to support TLF text, Adobe Flash Player was updated to change how it loads the related runtime shared libraries (RSLs) and the content you define in the SWF file.

In this article you'll learn about the changes to Flash Player and the best options for publishing files containing TLF text. You'll review key concepts and then follow the instructions to build a sample project to help you visualize how it all fits together. The steps guide you through creating a simple modular banner using a loader SWF file and content SWF files, each of which contains TLF text (click Figure 1 to see an example). Along the way, you'll learn how to build a custom RSL preloader, correctly load content SWF files, and work with ActionScript and FlashVars across multiple SWF files.

Special thanks to Jeff Kamerer at Adobe Systems for his help and suggestions. Be sure to check out Jeff's blog post, Using a custom preloader loop with TLF text, for more related information.

For best results in your projects that use TLF text, it's important to have a solid understanding of what TLF text is and how it works in Flash Player. This section covers key concepts related to TLF text and runtime shared libraries.

What is the Text Layout Framework?

The Text Layout Framework (TLF) is a new and more powerful option for displaying text content in Flash. You can use the Property inspector to choose the TLF Text option in Flash while the Text tool is selected (see Figure 2).

TLF text is an authortime representation of the Text Layout Framework (TLF), which is an ActionScript 3 library built on top of the Flash Text Engine (FTE) classes. Essentially it's an extension of the core ActionScript language which adds a wide range of features to the text rendering engine.

New text features include the following:

• Support for Asian languages and vertical text layout
• Support for right-to-left languages, such as Arabic and Hebrew
• Support for bi-directional text layout
• Additional font and paragraph formatting options including advanced ligatures, highlight color, paragraph spacing, and more
• Ability to link text flows across multiple text boxes
• Ability to treat text as a regular DisplayObject to create animation effects such as rotation and fades

The fact that TLF is an ActionScript framework "under the hood" means that you can work with TLF text in both a visual mode during authortime in Flash or in ActionScript at runtime. Authortime TLF text provides an enhanced visual interface for working with TLF (see Figure 3).

Flash supplies the TLF library at authortime. A runtime shared library is used to supply the functionality at runtime.

For more information on TLF text basics, see the following resources:

• Creating text with the Text Layout Framework (Todd Perkins, Adobe TV)
• TLF text (Text Layout Framework) (Flash glossary)

Why use preloaders for files containing TLF?

The TLF ActionScript classes are distributed in the form of a runtime shared library (RSL) contained in a SWZ file. By using an external RSL for the ActionScript library, the RSL can be cached locally on end users' machines and reused by all subsequent SWF files. In order for Flash Player to display TLF text, it first tries to load the RSL from the user's local cache, then from adobe.com, and then finally looks for it on the server hosting the SWF file. The RSL is always loaded in Flash Player before the content loads. This can create a delay if the RSL isn't already cached on the user's local computer.

You basically have four options for handling the potential delay of RSL loading. Three of these options involve using a preloader assigned to the file in the Advanced ActionScript 3 Settings (see Figure 4).

Selecting the runtime shared library (RSL) option from the Default linkage menu enables you to choose the preloader options from the fields below it. Your options include the following:

• Merge the code in the SWF: You can embed the RSL directly in the SWF file, which eliminates the need to preload it. This option has the benefit of simplicity but the drawback of adding 150 KB or greater file size to every SWF file.
• Use the Adobe preloader SWF: The default option is to use the Adobe preloader animation that appears as five black circles with white borders. This option has the benefit of sharing the TLF framework across all SWFs but has the drawback of creating timing considerations when loading SWF files into other SWF files.
• Use a custom preloader SWF: This option has the same benefits and drawbacks of the previous Adobe preloader option but with the added benefit of being able to create your own graphics for the preloader.
• Use a custom preloader loop: This option has the same benefits and drawbacks of the previous custom preloader option but with the added benefit of being able to control the code of the preloader in Flash Player.

Tip: The source files for the Adobe preloader SWF are located in the Flash application folder on your computer (Adobe Flash CS5.5/Common/Configuration/ActionScript 3.0/rsls/).

Most people probably use the default Adobe preloader option without ever knowing it is there. For most use cases, that's fine, but there are a few exceptions.

The following are considered best practices for working with RSLs:

• For web-based applications: Load the RSL at runtime using a preloader. Also, you'll notice that Flash publishes a local copy of the RSL file next to the SWF file when you publish the movie. Place a copy of the SWZ file next to your SWF file on your server as a fallback in case Flash Player can't load the RSL from the local cache or adobe.com.
• For desktop applications: Merge the TLF library into the Adobe AIR file so that the library is available offline to all users.
• For iOS applications (iPod, iPad): It's recommended that you use Classic text instead of TLF text due to performance considerations. If do you use TLF text, embed the RSL in the SWF file, since iOS does not load RSLs at runtime.

Working with Flash CS5.5 ActionScript and RSLs

Preloading RSLs introduces a new timing scheme to control how your Flash content loads in Flash Player. This is generally not a problem but it does create some issues with loading SWF files inside other SWF files, like in a banner system or other kind of modular application.

The primary issues when loading a SWF with an ActionScript 3 Loader object are as follows:

• Event timing does not work as expected
• Cross-scripting between SWF files does not work as expected

Not to worry—these issues are easy to work around if you know how to do it.

Flash Professional CS5.5 introduces a handful of new ActionScript APIs to handle the needs of SWFs loading RSLs. The new ProLoader and ProLoaderInfo classes should be used as an alternative to the Loader and LoaderInfo classes when loading SWF files containing TLF. The ProLoader and ProLoaderInfo classes provide the same API and functionality as the Loader and LoaderInfo classes, but the Proloader has the ability to manage the preloading of the RSLs and provides the expected behavior when cross-scripting and working with events. The ProLoader is built to make these issues transparent to the end user—and when loading SWF files across security domains, the ProLoader minimizes the occurrences of similar issues. The LoaderContext class was also updated to support the ProLoader class. You'll work with the new parameters property in the next section of this article to learn a convenient way to pass FlashVars parameters to the root timeline of any loaded SWF.

The new ActionScript APIs require Flash Player 10.2 or later to function properly.

For more information on working with the ProLoader class, see Using the ProLoader and ProLoaderInfo classes in the ActionScript 3 Developer's Guide.

Workarounds for Flash Professional CS5

If you're still working in Flash Professional CS5, the best strategies involve merging the RSL into the SWF to sidestep the Loader object issues or using the SafeLoader sample files provided on the following TechNote: Loading child SWFs with TLF content generates errors.

In this section you'll learn how to work with RSL preloaders and Flash Professional CS5.5 ActionScript in a banner structure. The banner is a very simple application composed of a loader SWF file and multiple child content SWF files. The loader SWF file loads the content SWF based on a URL supplied in FlashVars, passes the content SWF a reference to the FlashVars for text content, and then calls a transition method on the SWF to fade the content into view. Along the way you'll explore what works and what doesn't work when using TLF text.

Key concepts

There are several key concepts you'll focus on while creating the source files:

• Use Flash Professional CS5.5 and Flash Player 10.2 or later so that you have access to the new ActionScript classes
• Set your RSL preloader options in the Advanced ActionScript 3 Settings dialog box
• Use the new ProLoader class to load child SWF files containing RSLs
• Use the parameters property of the LoaderContext class to pass FlashVars parameters to the child SWF files

Set up the project files

First you'll prepare the source files that make up the sample project. You can use the supplied images in the ZIP file to follow along with the steps below.

By the end of the project, you'll create the following source files:

• CustomPreloader.fla
• Banner.as
• Banner.fla
• Banner.html
• Page.as
• Page1.fla
• Page2.fla
• Page3.fla

Follow these steps to get started:

1. Download the sample files from the top of the article and unzip the banner_project.zip file. Place the uncompressed folder on your desktop or in a convenient location on your computer.
2. Open the folder. This folder will act as your project folder. You'll save all your files into this directory. Also, notice the provided images folder. You can choose to use these images or work with any images you like as you complete the tutorial.

You'll work on the FlashVars and ActionScript code in the next sections, but first you'll start by creating the FLA files.

Create the custom RSL preloader animation

Since you're building a web-based project, you'll create a custom RSL preloader for this exercise. The custom preloader animation can be built in two different ways:

• Create a SWF file containing an animation and use it in place of the Adobe preloader SWF file
• Set up an animation in Frame 1 of Banner.fla and use the custom preloader loop option

For this example, you'll create a separate SWF file as a demonstration of the easiest way to customize the animation (see Figure 5).

Follow these steps to set up your custom preloader FLA file:

1. Open Flash Professional CS5.5 and create a new ActionScript 3 FLA file. Save the file as CustomPreloader.fla in the project folder.
2. Choose Modify > Document and set the Stage dimensions to 720 x 300 pixels in the Document Settings dialog box. Before closing the panel, click the Make Default button so that the next FLA files you create will all be sized at the same dimensions. Click OK to return to the Stage.
3. Name the default layer animation and add a new layer above it named actions & labels.
4. Add a keyframe to Frame 15 of both layers.
5. On Frame 15 of the animation layer, create some sort of indeterminate preloader animation on the main Timeline. An indeterminate animation could be dots that build, similar to the default Adobe animation, or it could be circles that rotate like the supplied sample, and so on. For best results, create graphics with a contrasting color to the Stage color. Check out the Adobe preloader source files or the CustomPreloader.fla sample in the banner_project_completed.zip file for reference or to use the supplied assets.
6. Extend the actions layer's Timeline so it's equal in length to the animation layer's Timeline. Add a frame label named loop to the keyframe on Frame 15. Add a keyframe in the last frame of the actions & labels Timeline. Place a gotoAndPlay("loop") action on the last frame to allow the animation to loop without returning to Frame 1.
7. When you're finished, choose Controls > Test Movie > Flash Professional to view the animation.
8. Save the file.

Tip: Be sure to leave 15 frames of empty space on the Timeline before the animation appears. Otherwise you'll see the animation appear briefly when your SWF file loads.

Create the banner loader FLA

The banner SWF file acts as a loader for the content SWF files. This file is empty except for a TLF text field showing a title. Beyond loading the content SWF files, the banner SWF file can be used to hold any text, content, or functionality that would be used repeatedly across content SWF files. In this case, the title text will appear the same way across any content SWF file loaded. You could also place user interface controls (such as navigation buttons) in the banner FLA or shared functionality like click through areas.

Follow these steps to set up the banner FLA:

1. Create a new ActionScript 3 FLA file in Flash. Save the file as Banner.fla.
2. Notice that the FLA's Stage is the same dimensions as the preloader. If you skipped the Make Default step previously, go ahead and manually size the FLA file to 720 x 300 pixels. All the FLA files for this sample project will be the same size.
3. Name the default layer text.
4. Click the Text tool and select the TLF Text option in the Property inspector if it's not already selected. Add a text field to the lower left corner of the Stage.
5. Name the text field instance title_txt in the Property inspector. Later you'll use ActionScript to force the text field to appear above the content SWF file.
6. Type in a title like Bay Area Destinations 2011 or some placeholder text of your choice.
7. Set the text styles to the following:

• Font: Arial Bold
• Size: 21 pt.
• Color: White

8. Click the Embed button in the Property inspector to open the Font Embedding panel. Name the font ArialBold and check the Basic Latin option in the Character ranges list. Click OK. Notice that a Font symbol named ArialBold appears in the Library.
9. Save the file.

Tip: The loader SWF file can share its embedded fonts with the content SWF file. That means that you don't have to embed the Arial Bold again in each SWF file.

Follow these steps to assign the custom preloader SWF file to the banner SWF file:

1. Choose File > ActionScript Settings in Banner.fla.
2. Set the Runtime Shared Library Settings options as follows:

• Default linkage: runtime share library (RSL)
• Preloader method: Preloader SWF
• Preloader SWF: CustomPreloader.swf

3. Click OK to close the Advanced ActionScript 3 Settings panel.
4. Save the file. You'll test the preloader at the end of the tutorial.

In the last set of steps, you simply assigned your CustomPreloader.swf file in place of the default Adobe SWF file.

Create the child page FLAs

The content FLA files are very simple. They contain a background image and a large TLF text field that gets populated with data supplied in the FlashVars parameters. For simplicity's sake, the images will be scenic pictures and the text will be the name of the location (see Figure 6).

Follow these steps to set up the content FLA files:

1. Create a new ActionScript 3 FLA file in Flash. Save the file as Page1.fla.
2. Confirm that the file's Stage dimensions are set to 720 x 300 pixels.
3. Change the name of the default layer to image.
4. Choose File > Import > Import to Stage and browse for the page1.jpg image from the supplied _images folder. Click Open to import the image.
5. Position the image at the 0,0 coordinates, if it's not already at that location.
6. Add a new layer above the image layer and name it text.
7. Add a TLF text field instance to the text layer and name the text instance name_txt.
8. Select the text field and set the following properties in the Property inspector:

• Font: Arial Bold
• Size: 80 pt.
• Color: White
• Alpha: 75%

9. Choose Control > Test Movie to view the SWF file. Notice that the font rendering appears off and a warning about font embedding appears in the Output panel. You can ignore these issues for now. The loader SWF already has the font embedded in it, so there's no need to embed it here as well.
10. Save the file.
11. Repeat these steps to create Page2.swf and Page3.swf, each respectively containing page2.jpg and page3.jpg. The banner in its simplest form only loads one SWF, but you'll use the other two files to see how easy it is to change content.

Tip: You can set the RSL preloader preferences for the child SWF files too, but theoretically you wouldn't expect a delay since the parent SWF file has already loaded the RSL.

At this point you've created all of the FLA files that will be used in the project. Next you'll set up the HTML page.

Set up the FlashVars parameters

The FlashVars parameter is an optional tag that can be added to the HTML markup that embeds the SWF file on the page. You can use it to pass variables to the SWF file at startup, similar to the way URL string variables can be appended to a URL to pass variables to that URL.

The FlashVars parameter looks like this:

Notice that the value attribute contains a list of name value pairs separated by ampersands.

Using FlashVars to supply text and URLs to the SWF is a great way to make the application modular. If you're editing by hand, you can manually make changes in a text editor without republishing the SWF files. If you're writing your HTML dynamically, you can change the content and text on the fly on the server. By separating the text values from the content, you could localize the content to different languages or provide dynamic variations of the text per user, and other similar strategies.

Follow these steps to publish the HTML page:

1. Return to Banner.fla in Flash and choose File > Publish. The SWF file and HTML file are published next to the FLA file.
2. Choose File > Publish Settings and uncheck the HTML Wrapper option in the OTHER FORMATS section. It's best to turn this off now so that you don't overwrite your FlashVars parameters if you run the Publish command again.
3. Repeat Step 2 for each of the FLA files. You don't need to publish the HTML files for this project and there's no use cluttering the project folder with them.

Follow these steps to add the FlashVars parameters:

1. Open the Banner.html file in Adobe Dreamweaver CS5 or the text editor of your choice.
2. Add the following FlashVars parameters (you can copy the code from the sample below):

• page_url: Page1.swf
• page_name: San Francisco, CA

3. Save the file. You'll test the FlashVars in the last steps of this tutorial.

After making these changes, the object tags in Banner.html should look like this:

For more information on FlashVars, see the following resources:

Using FlashVars with ActionScript 3 (Peter deHaan)

Use FlashVars to pass variables to SWF files

Set up the loader SWF ActionScript

In this section you'll add functionality to the banner FLA by creating an ActionScript class and assigning it as the Document class of the banner.fla file. This is the equivalent of writing ActionScript code on Frame 1 of the main Timeline, but as you'll see when you get to the code for the content SWF files, you can reuse Document classes across FLA files.

In the next steps you'll create an ActionScript class called Banner.as that can do the following:

• Read and parse FlashVars values
• Load content SWF files using the ProLoader class
• Pass FlashVars parameters to the content SWF's root timeline
• Cross-script with the content SWF to initiate a fade transition

Tip: Review the completed files in the supplied banner_project_completed.zip file and use them as a reference as you work through the next sections of this tutorial.

Follow these steps to create the ActionScript class:

1. Return to Flash and choose File > New. Select the ActionScript 3 Class option in the New Document dialog box. Enter the name Banner in the Class name field (see Figure 7) and click OK to create the file.

2. Save the new Banner.as file into the project folder next to the Banner.fla file.
3. Add the following import statements after the package line. Import statements allow you to reference the class directly by name and they itemize which classes are used in the script:

4. Update the class line to make it a subclass of MovieClip. You'll assign this class to the root timeline of the banner SWF file so the class needs to be (extend) a MovieClip:

5. Add the following variables below the class line. Notice that the pageURL variable contains default data for testing in Flash:

6. Update the constructor function by adding the loading code. First, you'll retrieve the page_url parameter from FlashVars using the loaderInfo.parameters object:

7. Immediately following the condition statement inside the constructor function's brackets, add the following code. In the next couple of statements, you'll create a LoaderContext object and assign the FlashVars parameters to the LoaderContext's parameters property. This step provides a convenient way to pass the FlashVars values to the loaderInfo object of the content SWF file:

8. Immediately following the LoaderContext statements, add the following code to finish off the constructor function. This code instantiates a ProLoader instance, assigns an event handler to its complete event, and loads the SWF using the optional LoaderContext parameter. Also notice that the text field is brought forward in the z order so that it appears above the content:

9. Add the following event code below the constructor function. This function catches the complete event from the ProLoader instance and attempts to cross-script with the content by starting a fade transition:

10. Save the file.
11. Compare your work to the Banner.as file in the completed sample files. Go ahead and copy the completed file and paste the code into your file if needed.

Tip: Notice that the code in Step 9 assigns the data types of the content SWF file to MovieClip instead of its Document class type, Page. Use this approach as your simplest solution when cross-scripting from one SWF file to another. The Document class for each SWF file includes auto-generated code for TLF support. If the loader SWF file imports the Page class for data typing, the loader SWF file's version of Page will be used in the content SWF files instead of their own version. The result is that the content SWF files don't have access to the auto-generated TLF code and therefore appear without text formatting.

Follow these steps to assign the Banner class to the Banner FLA file:

1. Return to Banner.fla and choose File > ActionScript Settings to launch the Advanced ActionScript 3 Settings dialog box.
2. Type the word Banner in the Document class field at the top of the panel. ActionScript classes are referred to by their name in the class path, so adding the .as file extension is not necessary. Click OK to close the panel.
3. Publish the SWF file and save the FLA.

Set up the child (page) SWF ActionScript

In this section you'll create a single Document class for all three child page SWF files. This demonstrates the benefits of using an ActionScript class instead of repeating the same code in each FLA. This workflow also opens up the possibilities of working on your scripts in Adobe Flash Builder or another ActionScript text editor.

In the next steps you'll create an ActionScript class called Page.as that can do the following:

• Read and parse FlashVars parameters
• Set the name_txt text instance with the text from FlashVars
• Transition fade in

Follow these steps to create the child page ActionScript class:

1. Create a new ActionScript Class file in Flash named Page.
2. Save the Page.as file to the project folder.
3. Add the following import statements after the package line:

4. Update the class line to extend MovieClip. Here again the class must be a MovieClip to be assigned as the Document class of a FLA file:

5. Add the following variables below the class line. Notice that the pageNames variable contains default data for testing. The text field instance is explicitly declared so that it does not cause an error when the Banner class references the Page class:

6. Update the constructor function by adding a listener to the ADD_TO_STAGE event:

7. Add the following event code below the constructor function. Basically this code retrieves the FlashVars parameters that were passed to the child SWF file from the parent SWF file. Using the ADDED_TO_STAGE event is a good way to ensure that you'll have access to the FlashVars and text field in the correct timing:

8. Add the following function after the event handler function. The transition method is simply a proof of concept that cross-scripting works between the SWF files:

9. Save the file.
10. Compare your work to the Page.as file in the completed sample files. Go ahead and copy the completed file and paste the code into your file if needed.
11. Assign the Page class as the Document class of each page FLA file using the steps from the end of the last section.

That wraps it up for the development tasks to finish the project. Check your work against the completed sample files for accuracy.

For more information on working with ActionScript 3, refer to the following resources:

• Learning ActionScript 3
• ActionScript 3 Developer's Guide
• ActionScript 3 Reference for the Flash Platform

The last task of the tutorial is to test your work. In a real-world workflow it is important to perform tests along the way many times as you change the files. And be sure to test often when writing ActionScript. It's much easier to identify where issues are, when they occur.

You can use the following approaches for testing the project:

• Use the Flash Debugger
• Use the Bandwidth Profiler to test the preloader
• Use a browser to see the FlashVars configuration work

Tip: You can also use the advanced features of Flash Builder to edit and debug the ActionScript code.

Using the Flash Debugger

The Flash Debugger can be used to find problems in ActionScript when errors occur. When you test the file in the Debugger, it will pause at the point where the code breaks and show you the state of the variables and function call stack. This provides a very handy way of seeing problems that are otherwise difficult to pin point.

Follow these steps to test the project in the debugger:

1. Return to the Banner.fla file in Flash.
2. Choose Debug > Debug Movie > In Flash Professional to launch the Debugger view. If any errors occur, the movie pauses playback and displays variables in the Variables panel and the function call stack in the Debug Console panel.
3. Click the X button on the Debug Console to close the debug session when you are finished.

For more information on debugging ActionScript 3, read my article, Understanding ActionScript 3 debugging in Flash.

Using the Bandwidth Profiler

The Bandwidth Profiler is a utility attached to the SWF window when you publish the SWF using the Control > Test Movie command (see Figure 8).

Follow these steps to test the RSL preloader animation:

1. Return to Banner.fla in Flash.
2. Choose Control > Test Movie > in Flash Professional to launch the SWF file.
3. Choose View > Bandwidth Profiler to display the Bandwidth Profile view.
4. Chose View > Download Settings to choose a setting that's slow enough for you to see the preloader run for bit. The 56 KB setting should work well for the test.
5. Choose View > Simulate Download to launch the SWF file again with the Download Settings applied. You should see your preloader animation display briefly before loading the SWF content.
6. Close the SWF file.

Using a browser

You can also test the project in a browser to see the FlashVars parameters load the content instead of the default parameters.

Follow these steps to test in a browser:

1. Open the Banner.html file in the browser of your choice. The Flash Player is fairly consistent across browsers, but it's a good idea to test in the range of most popular browsers at least.
2. You should see the content SWF and text load as expected. If you run into problems, compare your work to the work in the banner_project_complete.zip file provided at the top of the article.
3. Open the Banner.html file in a text editor again and change the FlashVars parameters to:

• page_url: Page2.swf
• page_name: Sausalito, CA

4. Save the HTML file and refresh the browser to see the page 2 content.
5. Repeat these steps for page 3 to use the following FlashVars:

• page_url: Page3.swf
• page_name: Bolinas Beach, CA

6. Save the HTML file and refresh the browser to see the page 3 content.

Tip: If you see an ActionScript runtime error when you launch the SWF files from your desktop or within a browser, it may be that you don't have Flash Player 10.2 or later installed on your computer. Make sure you have the latest Flash Player version installed before testing.

That's it! You now have a simple modular banner structure capable of dynamically loading content SWF files, passing data to them, and cross-scripting with them.

The sample project described in this tutorial demonstrates how to work with TLF RSLs in Flash Professional CS5.5. It also provides the foundation structure for building modular Flash applications. You could take it a step further by adding localization features (after all, TLF is designed to render languages that were not possible using Classic text). Take a look at my article, Formatting text for localized Flash projects, for more information.

Another way you could extend the sample project involves adding a custom preloader loop animation to Banner.swf in place of the external preloader SWF file. The benefit of this approach is that you can assign event handlers to the main Timeline of the banner SWF file and show a progress bar animation instead of an indeterminate animation.

To research further, check out Using a custom preloader loop with TLF text by Jeff Kamerer.

Here is also some Flash documentation related to TLF and RSLs:

• Publishing SWF files with TLF text
• Working with Text Layout Framework (TLF) text