One of the most common uses for the external API is to allow
ActionScript applications to communicate with a web browser. Using
the external API, ActionScript methods can call code written in
JavaScript and vice versa. Because of the complexity of browsers
and how they render pages internally, there is no way to guarantee
that a SWF document will register its callbacks before the first
JavaScript on the HTML page runs. For that reason, before calling
functions in the SWF document from JavaScript, your SWF document
should always call the HTML page to notify it that the SWF document
is ready to accept connections.
For example, through a series of steps performed by the IMManager
class, the Introvert IM determines whether the browser is ready
for communication and prepares the SWF file for communication. The
first step, determining when the browser is ready for communication,
happens in the IMManager constructor, as follows:
public function IMManager(initialStatus:IMStatus)
{
_status = initialStatus;
// Check if the container is able to use the external API.
if (ExternalInterface.available)
{
try
{
// This calls the isContainerReady() method, which in turn calls
// the container to see if Flash Player has loaded and the container
// is ready to receive calls from the SWF.
var containerReady:Boolean = isContainerReady();
if (containerReady)
{
// If the container is ready, register the SWF's functions.
setupCallbacks();
}
else
{
// If the container is not ready, set up a Timer to call the
// container at 100ms intervals. Once the container responds that
// it's ready, the timer will be stopped.
var readyTimer:Timer = new Timer(100);
readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
readyTimer.start();
}
}
...
}
else
{
trace("External interface is not available for this container.");
}
}
First of all, the code checks whether the external API is even
available in the current container using the ExternalInterface.available property.
If so, it begins the process of setting up communication. Because
security exceptions and other errors can occur when you attempt
communication with an external application, the code is wrapped
in a try block (the corresponding catch blocks
were omitted from the listing for brevity).
The code next calls the isContainerReady() method,
listed here:
private function isContainerReady():Boolean
{
var result:Boolean = ExternalInterface.call("isReady");
return result;
}
The isContainerReady() method in turn uses ExternalInterface.call() method
to call the JavaScript function isReady(), as follows:
<script language="JavaScript">
<!--
// ------- Private vars -------
var jsReady = false;
...
// ------- functions called by ActionScript -------
// called to check if the page has initialized and JavaScript is available
function isReady()
{
return jsReady;
}
...
// called by the onload event of the <body> tag
function pageInit()
{
// Record that JavaScript is ready to go.
jsReady = true;
}
...
//-->
</script>
The isReady() function simply returns the value
of the jsReady variable. That variable is initially false;
once the onload event of the web page has been
triggered, the variable’s value is changed to true.
In other words, if ActionScript calls the isReady() function
before the page is loaded, JavaScript returns false to ExternalInterface.call("isReady"),
and consequently the ActionScript isContainerReady() method
returns false. Once the page has loaded, the JavaScript isReady() function
returns true, so the ActionScript isContainerReady() method
also returns true.
Back in the IMManager constructor, one of two things happens
depending on the readiness of the container. If isContainerReady() returns true,
the code simply calls the setupCallbacks() method,
which completes the process of setting up communication with JavaScript.
On the other hand, if isContainerReady() returns false,
the process is essentially put on hold. A Timer object is created
and is told to call the timerHandler() method every 100
milliseconds, as follows:
private function timerHandler(event:TimerEvent):void
{
// Check if the container is now ready.
var isReady:Boolean = isContainerReady();
if (isReady)
{
// If the container has become ready, we don't need to check anymore,
// so stop the timer.
Timer(event.target).stop();
// Set up the ActionScript methods that will be available to be
// called by the container.
setupCallbacks();
}
}
Each time the timerHandler() method gets called,
it once again checks the result of the isContainerReady() method.
Once the container is initialized, that method returns true. The
code then stops the Timer and calls the setupCallbacks() method
to finish the process of setting up communication with the browser.
