Flash Tech Resources - Flash Methods

A Flash Bible Tech Note
by John Croteau

Flash Methods

Flash Methods allow to you control Flash from the scripting environment. You can send commands (actions) from script to Flash in the form of special functions such as Play(), GotoFrame(frameNum) and TGotoLabel(target, label). Many of these commands are the same as in Flash, but others such as Zoom(percent) are only available from JavaScript. There are still others such as ReadyState(num) that are only available from an ActiveX control (in a Window versions of Internet Explorer or embedded in another application).

To send commands from JavaScript to Flash there are some additional requirements. There are 3 special tags needed for the HTML page, there is script needed to send the commands and the Flash player must be loaded before commands are sent to the Flash player.

Send Script Only After The Flash Player Is Loaded
You should not try to send Flash method commands before the Flash plugin or ActiveX control has been loaded by the browser because an attempt to control the plugin/ActiveX control with a Flash method before the plugin has loaded can result in an error message that the object does not have a property defined. For a Flash method to work without error, frame 1 of the Flash movie must already exist at the time the script is executed. If the command addresses a frame that isn't loaded it may not work but it will not create an error.

There are two ways to make sure the Flash player is available before sending it a command from JavaScript. . One solution is to use an onLoad event handler to delay the loading of the script, until after the Flash plugin has been loaded. The second solution prevents execution of the Flash methods from JavaScript until an FS Command event (sent from the Flash movie) is received by the script. Failure to use one of these solutions can result in intermittent failure of Flash methods in some browsers when used on the web. These solutions will be covered in more detail in another tutorial.

The Special HTML Tags
When Flash is used in FS Command capable browsers there are three HTML tag parameters that are needed for Flash to be able to receive Flash methods from the scripting environment. The first two NAME and ID are used to identify the Flash movie. NAME is used in the EMBED for the plugin (Netscape) and ID is used in the OBJECT for the ActiveX control for Windows versions of Internet Explorer. A third tag swLiveConnect needs to be set to true for Netscape 4+ to start Java if it isn't already running. To enable communications (Flash methods and FS Commands) between script and Flash a 32 bit implementation of either LiveConnect (Java) for Netscape or ActiveX must be enabled. See MM 13101 for more on swLiveConnect.

Map is the NAME/ID of the movie that we are controlling with Flash methods in our example below.

<OBJECT ID="map" CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" 
 CODEBASE="http://active.macromedia.com/flash2/cabs/swflash.cab#version=2,0,0,0" 
 WIDTH="100%" HEIGHT="100%">
 <PARAM NAME="Movie" VALUE="map.swf"<
 <EMBED NAME="map" SRC="map.swf" swLiveConnect="true" WIDTH="100%" HEIGHT="100%" mayscript
  pluginspage="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash2"<
 </EMBED>
 </OBJECT>

NOTE... The FS Command Publish template that came with Flash 4 does not have a needed template variable NAME=$TI. For Netscape to work with Flash methods or FS Command you need to add the NAME manually in each HTML page, modify your copy of the template by adding NAME=$TI to the EMBED or install a corrected copy of the template.
See MM 13997 for more info on template problem. Get a new template from Macromedia or Flash Central.

Flash Methods - Sending Commands To Flash
Flash Methods are special JavaScript functions that are in the form of

   ObjectPath.Function(argument, argument)

The ObjectPath tells JavaScript where to send the Flash method commands. The path varies depending on the browser used because Internet Explorer and Netscape use different object models.

The Function is the actual Flash Method command. The available Flash Methods are found in the table of FS Commands, which lists the available functions, what versions of Flash are supported and the arguments required (if any). An argument is a value that a method uses. If there is no argument for a particular command then the parentheses are left empty. Multiple arguments are separated by commas.

The following sends a Tell Target Go To command to a frame labeled Park in the movie clip Main on the main timeline:

   ObjectPath.TGotoLabel("/Main", "Park")

Differences between Netscape and IE Object Paths
We need to know the path of the Flash player so that commands can be sent to it. Internet Explorer treats objects (ActiveX controls) as members of the "window", while in Netscape embedded objects (plugins) are members of "window.document". Because of this difference we normally use a function to get the object path or store it in a variable. The full path for IE is in the form of parent.framename.activex_ID and for Netscape it is parent.framename.document.plugin_Name.

In the EMBED and OBJECT of our examples we have set the parameters Name and ID to 'Demo' to identify our Flash player object (plugin/ActiveX control). In the 'Frame' demo the HTML frame that the Flash plugin/ActiveX control is in has its NAME set to demo_methods. The resulting path for the ActiveX control in IE is:

     parent.demo_methods.Demo

and the path for the plugin in Netscape is:

     parent.demo_methods.document.Demo

However, we don't normally use the above syntax for Netscape and instead use the embedded object method because using it has been found to be more reliable: If there is more than one Flash movie or other embedded objects on a page the number in the embeds may change. The first embedded object is zero.

      parent.demo_methods.document.embeds(0)

For HTML pages that are not in Frames the frame name is removed from the formula:

      parent.Demo
      parent.document.embeds(0)

Scripting Methods
In this section we will show four ways JavaScript can be written to provide the correct Flash player object path needed for sending Flash methods to the Flash player. Careful attention should be paid to the details in each.

1) The Standard Method uses the standard form of the 'if conditional'.
2) The Shorthand Method uses a shorthand version of JavaScript.
3) The Object Method which is used in pages without frames. This is the method used for the clock at FlashTek.
4) The Single Line Method is the method used in the Hawaii Demo.

In each of these methods we use the same expression to determine if a browser is IE or Netscape. The expression is True if the browser is IE and it is False if not.

      navigator.appName.indexOf("Microsoft") != -1

The Standard, Shorthand and Object methods all use the same JavaScript hyper link placed in the Body of the HTML page. When one of the links is clicked the function jc() is called and the correct object path is retrieved, combined with the Flash method and then sent to the Flash player.

     <a href='javascript:jc().StopPlay()'>Stop</a>
     <a href='javascript:jc().Play()'>Start</a>

The Standard Method See Demo
In the Standard Method we use the standard JavaScript if conditional:

    if (expression)
         {do if the expression is true}
    else     
         {do if the expression is false}

The function is placed in the head of the HTML page and when it is called will return the correct path of the Flash plugin/ActiveX control based on the browser detection.

  function jc()
 {
    if (navigator.appName.indexOf("Microsoft") != -1) 
        return parent.demo_methods.Demo;
    else
        return parent.demo_methods.document.embeds(0);
  }

When a link in the Body of the HTML is clicked the function jc() returns the correct object path, which is combined with the Flash method and then sent to the Flash player.

     <a href='javascript:jc().StopPlay()'>Stop</a>
     <a href='javascript:jc().Play()'>Start</a>

Shorthand Method See Demo
This method uses the shorthand form of a JavaScript 'if conditional' where the question mark (?) and the colon (:) are used to separate the components.

    expression ? do if the expression is true : do if the expression is false

An expression sets the value of the variable InternetExplorer to True if the browser is IE and to False if it is Netscape. When the function is called the value (true or false) of the variable InternetExplorer is used to return the correct object path.

    var InternetExplorer = navigator.appName.indexOf("Microsoft") != -1;
    return InternetExplorer ? parent.demo_methods.Demo : parent.demo_methods.document.embeds[0];

When a link in the Body of the HTML is clicked the function jc() returns the correct object path, which is combined with the Flash method and then sent to the Flash player.

     <a href='javascript:jc().StopPlay()'>Stop</a>
     <a href='javascript:jc().Play()'>Start</a>

The Object Method See Demo
The script for the function jc() is placed in the head of the HTML page and when called will return the correct path of the Flash plugin/ActiveX control. It uses a different method to determine the correct object path for the Flash player. This method only works when the script and the Flash file are in the same HTML frame (page).

function jc(){
     if (navigator.appName.indexOf ("Microsoft") !=-1) 
           { return window['Demo'] }
     else  { return document['Demo'] }
              }

When a link in the Body of the HTML is clicked the function jc() returns the correct object path, which is combined with the Flash method and then sent to the Flash player.

     <a href='javascript:jc().StopPlay()'>Stop</a>
     <a href='javascript:jc().Play()'>Start</a>

The Single Line Method See Demo
This method evaluates more than one expression inside each of the of links placed in the Body of the HTML page. The expressions are separated by semicolons.

    <a href='javascript:expression1; expression2'>Text</a>

The first expression uses the shorthand form of JavaScript to set the variable jc to the correct object path. The second expression uses the variable jc calculated in the first expression and combines this with the Flash method function, which is then sent to the Flash player.

The shorthand form of a JavaScript 'if conditional' uses the question mark (?) and the colon (:) are used to separate the components.

    <a href='javascript:var jc = InternetExplorer ? if true : if false; jc.Function'>Text</a>

The complete script is quite long and even though the script looks kind of cool in a text editor this method is not very efficient or easy to read.

     <a href='javascript:var jc = InternetExplorer ? parent.demo_methods.Demo : parent.demo_methods.document.embeds[0]; jc.StopPlay()'>Stop</a>
     <a href='javascript:var jc = InternetExplorer ? parent.demo_methods.Demo : parent.demo_methods.document.embeds[0]; jc.Play()'>Start</a>

Though the browser detection variable InternetExplorer could also be included in the link 
in our example we have placed it in the Head of the document. 
The value of InternetExplorer is True if the browser is IE and is False if it is Netscape. 
                 
    var InternetExplorer = navigator.appName.indexOf("Microsoft") != -1;




Back to FS Commands
More on FS Commands



Comments and Questions