14.1 Sharing Class Source Files

Probably the most common reason for sharing classes is to reuse them across multiple projects. For example, suppose you work in a small web shop called Spider Services, whose web site is http://www.spiderservices.com (while I was writing this book, a company named Spider Solutions LTD registered that domain, but let's pretend Spider Services is a fictitious shop). You've made a TextAnimation class to handle various text effects. You want to use the TextAnimation class on two sites you're working on, Barky's Pet Supplies and Mega Bridal Depot. Rather than place a copy of the class file (that is, the .as file) in each project folder, you should store the class file centrally and merely refer to it from each project. For example, on Windows, you could store the TextAnimation.as class file in the following location:

c:\data\actionscript\com\spiderservices\effects\TextAnimation.as

To make the TextAnimation class accessible to both projects, you'd add the directory c:\data\actionscript to Flash MX 2004's global classpath (under Edit Preferences ActionScript Language ActionScript 2.0 Settings).

If there were several members on your team, you might think it would be handy to store your class on a central server so everyone would be able to use it. For example, your team might want to store all shared classes on a server called codecentral , in a directory matching the company's domain name ( \com\spiderservices ):

\\codecentral\actionscript\com\spiderservices\effects\TextAnimation.as

That practice is highly perilous and is not recommended.

If you store your classes on a central server and allow developers to modify them directly, the developers are liable to overwrite one another's changes. Furthermore, if the clock of the server and the clock of a programmer's personal computer are not in perfect sync, then the latest version of the class might not be included in the movie at compile time. To avoid these problems, you should always use version control software to manage your class files when working on a team. One popular (and free!) option is CVS (see http://www.cvshome.org).

On large projects, you might also want to automate the .swf export process using a build tool such as Apache Ant (http://ant.apache.org). To do so, you'd have to execute a command-line JSFL script to tell Flash to create the .swf for each .fla file in your project(s). Complete coverage of command-line compilation is outside the scope of this book (and is still in its infancy), but here's a quick sample that gives the general flavor of it on Windows:

   // Code in exportPetSupplies.jsfl:   // =============================== // Open the   .fla   file. var doc = fl.openDocument("file:///c/data/projects/pet/petsupplies.fla"); // Export the   .swf   file. doc.exportSWF("file:///c/data/projects/pet/petsupplies.swf", true); // Quit the Flash MX 2004 authoring tool (optional). fl.quit(false);   // Command issued on command line from /pet/ directory:   // ==================================================== "c:\program files\macromedia\flash mx 2004\flash.exe" exportPetSupplies.jsfl 

For this command to work, Flash MX 2004 must not be running. After the command is issued, the compiled petsupplies.swf movie appears in the directory c:\data\projects\pet .

14.1.1 Loading Classes at Runtime

When working with multiple .swf files that make use of the same class, compiling the class into every .swf is a waste of space. When file size is a concern, you can prevent such redundancies by externalizing the class library into a separate .swf file and loading it at runtime. Once the library has loaded the first time, it is cached on the end user 's machine and can be reused by other .swf files without being downloaded again.

A class library loaded at runtime is known as a dynamic class library .

To create a dynamic class library, we compile the desired classes into a .swf file. We then use loadMovie( ) to load that .swf into any movie that needs the classes. However, in order for this technique to work, we must be sure that the classes in the class library are excluded from the movies that load them. To prevent runtime-loaded classes from being compiled into the movies that load them, we use an exclusion XML file . The exclusion XML file lets a .fla file access classes locally for the sake of compile-time type checking but prevents those classes from being included in the exported .swf file, thus allowing them to be loaded at runtime.

To see how to create a runtime-loaded class library, we'll return to our earlier Spider Services TextAnimation class example.

Here are the general tasks we have to complete:

1. Create the classes in the class library (in our case, just the TextAnimation class).

2. Create the .swf file that will contain the classes in the class library.

3. Create the movie that loads the class library .swf file.

4. Create the exclusion XML file.

Now let's look at each task individually. The source files discussed in the next few sections can be downloaded from http:// moock .org/eas2/examples.

14.1.1.1 Create the classes in the class library

The first step in creating a class library is to create the classes that it will contain. Our sole class is called TextAnimation , stored in the file c:\data\actionscript\com\spiderservices\effects\TextAnimation.as . Here's the source for the TextAnimation class. For this example, our focus is class library building, so we won't show the actual text animation code in the class; we'll just provide a trace( ) statement in the class constructor to verify that the class is working:

 class com.spiderservices.effects.TextAnimation {   public function TextAnimation ( ) {     trace("Imagine a text effect with great majesty.");   } } 

Now that our class library is complete, we can create the .swf file that will contain it.

14.1.1.2 Create the class library .swf file

To make the class library .swf file, follow these steps:

1. Create the following working directory for the class library source files: c:\data\spiderservices\spidercore . In this case, we use the name of the company, spiderservices , as a general folder name for all projects and spidercore as the name of the folder that will contain our class library .swf file (the class library contains the " core " classes for most Spider Services projects, so we call it spidercore ).

2. Add the directory c:\data\actionscript to Flash MX 2004's global classpath using Edit Preferences ActionScript Language ActionScript 2.0 Settings. With the c:\data\actionscript directory in the global classpath, we'll be able to access our TextAnimation class when we export our class library .swf file.

3. Create a new .fla file named spidercore_runtime.fla in the following location: c:\data\spiderservices\spidercore\spidercore_runtime.fla . We'll export the class library .swf file from spidercore_runtime.fla . We use the word "runtime" in the document's name to indicate that our class library will be loaded and used at runtime.

4. On frame 1 of spidercore_runtime.fla , add the following code:

    com.spiderservices.effects.TextAnimation; 

   
   

   By referring to the TextAnimation class in our .fla file, we force the class to be included in our class library .swf file. Each class in the class library should be listed on frame 1. The compiler finds and includes all dependent classes automatically (for example, if the TextAnimation class uses a Tween class, then the Tween class will be included in the spidercore_runtime.swf file automatically). This conveniently relieves us from finding and individually including all classes upon which TextAnimation is dependent.

5. Use Insert Timeline Keyframe to add a new keyframe at frame 2 of the main timeline of spidercore_runtime.fla .

6. On frame 2 of spidercore_runtime.fla , add the following code:

    // Notify the parent movie clip that the class library // has finished loading. _parent.spidercoreLoaded( ); stop( ); 

   
   

7. Select File Export Export Movie to create spidercore_runtime.swf in the same directory as spidercore_runtime.fla . Be sure to specify ActionScript 2.0 in the publish settings when you export the .swf file.

8. Save the spidercore_runtime.fla file.

Now that our class library .swf file is ready, we can use it in any movie. Let's do that next.

14.1.1.3 Create the movie that loads the class library .swf file

For this example, the movie that loads spidercore_runtime.swf is the homepage of Barky's Pet Supplies. To create the homepage movie, follow these steps:

1. Create the following working directory for the Barky's Pet Supplies project: c:\data\spiderservices\barkys . As usual, we place company- related files in the folder spiderservices and project files in a subfolder named after the current project (in this case, barkys ).

2. Create a new .fla file named barkyshome.fla in the following location: c:\data\spiderservices\barkys\barkyshome.fla .

3. On frame 1 of barkyshome.fla , add the following code:

    import com.spiderservices.effects.TextAnimation; // This function is called when the class library finishes loading. function spidercoreLoaded ( ):Void {   // Classes are loaded. It's now safe to proceed with the application.   // Just to prove everything's working, make a   TextAnimation   instance.   var ta:TextAnimation = new TextAnimation( ); } // Load class library. this.createEmptyMovieClip("spidercore", 0); this.spidercore.loadMovie("../spidercore/spidercore_runtime.swf"); 

   
   

Our Barky's homepage movie is ready to use the class library, but there's a problem. If we use it in its current state, it will automatically include the TextAnimation class file in the barkyshome.swf movie! We don't want that to happen because we'll be loading that class at runtime via spidercore_runtime.swf , and we don't want to load the class twice for no reason. Hence, we now need to create a special XML file that tells the compiler not to include the class TextAnimation in barkyshome.swf .

You might assume we could prevent the TextAnimation class from being included in barkyshome.swf simply by removing the path c:\data\actionscript from the global classpath. In fact, that would work but would also prevent the compiler from finding the TextAnimation class for the sake of type checking! Hence, type errors would occur and our barkyshome.swf file wouldn't be compiled. So, even though we're loading classes at runtime, we still need access to the source files for those classes at authoring time. Later in this chapter, we'll see how to ship a dynamic class library without also shipping source code.

14.1.1.4 Create the exclusion XML file

The exclusion file specifies which classes should not be compiled into the associated .swf file. We want to prevent those classes that will be loaded dynamically at runtime from being compiled into the applicable .swf .

To make the exclusion XML file, follow these steps:

1. Create a new text file named barkyshome_exclude.xml in the following location: c:\data\spiderservices\barkys\barkyshome_exclude.xml .

   The precise name of the exclusion file in this step is very important. It must exactly match the name of the .fla file to which it applies, followed by _exclude.xml .

2. The exclusion file prevents the specified class(es) from being compiled into the associated .swf file. To prevent the TextAnimation class from being compiled into the .swf file, add the following code to barkyshome_exclude.xml :

    <excludeAssets>   <asset name="com.spiderservices.effects.TextAnimation"></asset> </excludeAssets> 

   
   

   Here's a hypothetical exclusion file that shows how to exclude more than one class. It excludes the TextAnimation class as well as the hypothetical classes Tween and Randomizer :

    <excludeAssets>   <asset name="com.spiderservices.effects.TextAnimation"></asset>   <asset name="com.spiderservices.effects.Tween"></asset>   <asset name="com.spiderservices.util.Randomizer"></asset> </excludeAssets> 

   
   

3. Save the barkyshome_exclude.xml file.

By listing the TextAnimation class in an <asset> tag, we force it to be excluded from our barkyshome.swf file. Each class in the spidercore_runtime.swf class library should be listed in its own <asset> tag.

The compiler does not automatically exclude dependent classes. For example, if our spidercore class library contains a Tween class that is used by TextAnimation , but the barkyshome_exclude.xml file does not list Tween as an exclusion in an <asset> tag, the Tween class is included in the barkyshome.swf file (which is undesirable and unnecessary because the code resides in the class library too).

You must name each and every class you want excluded in its own <asset> tag, and there are no wildcards to help you exclude a whole package.

Our spidercore class library is now ready for use!

14.1.1.5 Try it out

We can test our dynamic class library by exporting a .swf file from barkyshome.fla using Control Test Movie (Ctrl-Enter on Windows or Cmd-Enter on Mac). The barkyshome.swf file will not include the TextAnimation class but will have access to it via the loaded dynamic class library, spidercore_runtime.swf . Remember that the class library loads because we told it to on frame 1 of barkyshome.fla :

 // Load class library. this.createEmptyMovieClip("spidercore", 0); this.spidercore.loadMovie("../spidercore/spidercore_runtime.swf"); 

If you're following along at home, you should see this text appear in the Output panel:

 Imagine a text effect with great majesty. 

Note that if we were to load another class library with its own version of the class com.spiderservices.effects.TextAnimation , the second version of the class would not overwrite the first version; it would be ignored. To prevent that kind of name collision, you should always keep your classes in a uniquely named package, particularly when working with dynamic class libraries.