Recipe 1.13 Reusing and Organizing Code in Multiple Movies

1.13.1 Problem

You want to reuse code that you've created for one project in another Flash movie. Or you want to write your ActionScript code in an external text editor.

1.13.2 Solution

Place your ActionScript code in external .as files and use the #include directive to add them to your Flash movies:

// Adds all the code within MyActionScriptFile.as to your Flash movie.
#include "MyActionScriptFile.as"

1.13.3 Discussion

Use the #include directive to incorporate code from external text files into your Flash movie during compilation from a .fla file to a .swf file. When you export a .swf file, Flash replaces the #include directive with the contents of the specified file. The external file must be a text file with valid ActionScript code in it. By convention the file should be named with the .as extension, though it is not absolutely necessary:

#include "ASutils.as"

Notice that the #include directive is not followed by a semicolon. Adding a semicolon causes an error.

Additionally, Flash must be able to locate the file when you export the movie. Therefore, you should place the file in a location relative to where the Flash document is saved. For example, the previous example looks for a file named ASutils.as in the same directory as the .fla document. You can also place the file in a subdirectory of the directory in which the Flash document is saved:

// Look for a file named ASutils.as in a subdirectory named myASFiles.
#include "myASFiles/ASutils.as"

You can also place the ActionScript files in the Flash installation's Include directory. And, in fact, this is recommended for all ActionScript files that you anticipate you might use in multiple movies. If Flash cannot find a file with the specified name relative to the .fla file, it looks in the Configuration\Include subdirectory of the directory in which Flash is installed. For example, on Windows-based computers, the default Include folder is located in C:\ProgramFiles\Macromedia\Flash MX\Configuration\Include.

If Flash is unable to find the external file in the folder specified by the #include directive (by default, the same directory as the .fla file) and is unable to find the file within the Flash Include directory, it displays an error message.

You should not upload your .as files along with your .swf file. The contents of the external text file are added to the .swf file when it is exported. Because the contents are not loaded into the .swf file dynamically at runtime, you must reexport the .swf file if the external .as file changes. Remember that future changes to the .as file will affect any movie that includes it the next time the movie is reexported. To prevent future changes in an external file from affecting a given movie, you can copy and paste the external code into the particular .fla and remove the original #include statement.

There is one additional consideration when working with external ActionScript files: it is good practice to add at least one blank line to the end of each .as file. This is because when Flash includes the code from the external file, it can sometimes combine the last line of the external file with the next line of code within the Flash document. This can sometimes cause errors if the last line in the external file contains code. But if the last line is blank, you can avoid these sorts of problems.

Note also that an included file can include another file (a nested #include). But paths inside an included file are relative to the original .fla file, not relative to the parent file location. Developers typically use a package-style reference incorporating their domain name or a project name as a directory for included files to avoid name collisions with other libraries. For example:

#include "com/person13/utilities/ASutils.as"