Recipe 15.1 Loading an External SWF

15.1.1 Problem

You want to load an external SWF into your Flash movie.

15.1.2 Solution

Use the loadMovie( ) method.

15.1.3 Discussion

The loadMovie( ) method is the preferred technique for loading external .swf files into a Flash movie. You should call this method from the movie clip into which you want to load the .swf file and pass it the URL at which the .swf file can be found:

// Load a .swf file into myMovieClip using a relative URL to a file in the same
// directory as the loading Flash movie.
myMovieClip.loadMovie("mySWF.swf");

// Load a .swf file into myMovieClip using a full URL to a file within the same
// domain as the loading Flash movie.
myMovieClip.loadMovie("http://www.mydomain.com/path/mySWF.swf");

Flash's security sandbox prevents Flash movies from loading assets from different domains. In other words, a Flash movie being served from www.mydomain.com can load a .swf file from www.mydomain.com or any other server in the same domain (such as www2.mydomain.com), but it cannot load a .swf file from www.yourdomain.com. Recipe 15.2 describes how you can create trusted relationships between domains using allowDomain( ). Recipe 15.6 shows a different approach that uses a proxy script to load content from any domain.

The loadMovie( ) method replaces the timeline of the movie clip from which it is called with the timeline of the specified .swf. All existing content within the movie clip is wiped out when loadMovie( ) is called. Therefore, it is convenient to use the createEmptyMovieClip( ) method to create a container movie clip into which you load the .swf file (as opposed to creating instances at authoring time). For example:

// Create myMovieClip using createEmptyMovieClip(  ).
_root.createEmptyMovieClip("myMovieClip", 1);

// Load the .swf file into myMovieClip.
myMovieClip.loadMovie("mySWF.swf");

The loadMovie( ) method works asynchronously. This means that when the ActionScript interpreter encounters a loadMovie( ) call, it initiates the request to load the external content, but it does not wait for the content to load before proceeding to the next line of code. This can have very important ramifications. For example, if you want to resize a movie clip into which you have loaded a new .swf file, you have to wait until the file has fully loaded. Here is some sample code to illustrate the problem:

// Create myMovieClip using createEmptyMovieClip(  ).
_root.createEmptyMovieClip("myMovieClip", 1);

// Load the .swf file into myMovieClip.
myMovieClip.loadMovie("mySWF.swf");

// This displays 0 even if the width of the loaded .swf is greater than 0 because the
// width of the movie clip is not properly set until the .swf file has fully loaded.
trace(myMovieClip._width);

To solve this problem you should monitor the loading progress, as shown in Recipe 15.7 and Recipe 15.8.

Although it is recommended that you use loadMovie( ) to load content into movie clips when loading external .swf files, there is an exception in which it is preferable to use a different technique. When you load content using loadMovie( ), the content must be fully loaded before it can be viewed. Therefore, in situations in which you want to stream the loaded .swf file you need to use a different technique. For loading streaming content you must load the .swf file into a level instead of a movie clip.

The Flash Player can contain more than one level. The default level is level 0, and you can target it in ActionScript using _level0. In fact, you may have noticed that in your movies, _root and _level0 are often synonymous (this is not necessarily the case when you start adding more levels). Additional levels can be created, and they are simply named level 1 (_level1), level 2 (_level2), etc. As the level number increases, so does the stacking order. In other words, content in level 1 will appear in front of content in level 0. You can treat each level in the same way you treat _root. This means you can move the contents of a level using the _x and _y properties, change the size using the _height and _width properties, etc.

You can load content into levels by using the loadMovieNum( ) global function. All you need to do is tell Flash the URL of the content and the level into which you want to load the content.

// Load someSWF.swf into _level1.
loadMovieNum("someSWF.swf", 1);

If the level does not yet exist, Flash first creates it, and then loads the content. If the level already exists, Flash replaces the existing content with the loaded content.

If you load a new .swf file into _level0, you will lose all the contents of the original movie as well as any other contents that have been loaded into other levels. Likewise, be careful when using the global loadMovie( ) function. If you specify a nonexistent path for the target, such as specifying _level1 when no _level1 object exists, loadMovie( ) replaces the current timeline with the newly loaded movie. To avoid the problem altogether, specify the target clip as a string, such as "_level1", or use the MovieClip.loadMovie( ) method instead.

If you want to hide the contents of level 0 it is better to set the level's visibility to false:

_level0._visible = false;

You can unload levels (remove the contents and the level itself) using the unloadMovieNum( ) global function:

// Unload level 2.
unloadMovieNum(2);

The getURL( ) method is also worth noticing. It is useful (aside from opening new browser windows) when you have a Flash movie being played from an HTML page and you want to replace both the .swf contents and the entire HTML page. This is important if, for example, you want to load a new .swf file with different dimensions. You can call the getURL( ) method from any movie clip as well. To replace the contents of the existing HTML page, use the value "_self" for the window parameter, as follows.

_root.getURL("newHTMLPage.html", "_self");

15.1.4 See Also

For a detailed discussion of document levels within the Player, see the section "The .swf Document `_level' Stack" in Chapter 13 of ActionScript for Flash MX: The Definitive Guide. This chapter is freely downloadable from http://www.oreilly.com/catalog/actscript2/chapter/index.html.