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:

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 .swffile 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.