JSFCommunicator Library

Last updated: June 08, 2004

(Single argument was being passed from flash to JavaScript functions, FIXED)

Background: JSFCommunicator Library makes a developer’s life easy. It provides some higher-level API to establish communication between JavaScript and Flash movie.

Library includes a JavaScript Class named “JSFCommunicator” and a Flash Component named “JSFCommunicatorHelper”.

To use this library, developer needs to do following steps:

1) Import JSFCommunicatorHelper component in flash movie. This component is required in movie’s library only.

2) Include ‘JSFCommunicator.js’ file in HTML document.

3) Create an object of JSFCommunicator Class.

Once you complete above steps, library is setup to use.

Click here to Download Library code with files including this document.

For Quick Start, Please go through the example.html and example.fla file.

API Reference

1) JSFCommunicator class (JavaScript)

Description

The JSFCommunicator class lets you set/get variables inside any flash movie. Moreover, it lets you call custom flash functions also from JavaScript.

To create a JSFCommunicator object, use the constructor

new JSFCommunicator(refFlashObject),

refFlashObject is reference of Flash ActiveX or Flash Plugin object embedded in html document.

Method summary for the JSFCommunicator class

Method	Description
`JSFCoomunicator.setVariable()`	Sets value of a variable in Flash movie
`JSFCoomunicator.getVariable()`	Gets value of a variable in Flash movie.
`JSFCoomunicator.callFunction()`	Calls a function in Flash movie.
`JSFCoomunicator.setMovie()`	Sets the target Flash Movie, which is used for Communication.

Constructor for the JSFCommunicator class

Usage

new JSFCommunicator(refFlashObject)

new JSFCommunicator()

Parameters

refFlashObject A reference to flash object(Flash ActiveX or Plugin). refFlashObject can be retrieved by following ways. Way to retrieve the reference differs in IE and Netscape.

For IE:

refFlashObject = window[id_attribute_of_OBJECT_TAG]

For Netscape:

refFlashObject = window.document[name_attribute_of_EMBED_TAG];

Returns

A reference to JSFCommunicator object.

Description

Constructor; lets you create an instance of JSFCommunicator Class. This instance is then used to set/get variables in flash movie or call functions in flash movie.

Usage 1: If you specify reference of Flash ActiveX or Plugin, corresponding flash movie would be accessible by JSFCommunicator.

Usage 2: If you don't specify reference of Flash ActiveX or Plugin, flash movie won’t be accessible until JSFCommunicator.setMovie (refFlashObject) is called.

Example

Usage 1: The following example creates a new JSFCommunicator object with a target Flash Object.

//assuming “myFlashMovie” is value of id or name attributes of OBJECT or EMBEDS
// tags respectively

jsfc = new JSFCommunicator(thisMovie(“myFlashMovie”));

//set value of Flash variable

jsfc.setVariable(“foo”,”bar”);

//this function accepts the name or id of Flash Object and returns the reference to Flash Object. It takes of different browsers.

function thisMovie(movieName) {

  // IE and Netscape refer to the movie object differently.

  // This function returns the appropriate syntax depending on the browser.

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

    return window[movieName]

  } else {

   return window.document[movieName]

Usage 2: The following example creates a new JSFCommunicator object without any argument.

jsfc = new JSFCommunicator();

//this call would fail because there is no target Flash Movie.

jsfc.callFunction(“_root”,“myFlashFunction”,[“param1”,”param2”]);

//set the target flash movie

jsfc.setMovie(thisMovie(“myFlashMovie”));

//this would successfully call myFlashFunction inside the flash movie.

jsfc.callFunction(“_root”,“myFlashFunction”,[“param1”,”param2”]);

//this function accepts the name or id of Flash Object and returns the reference to Flash Object. It takes of different browsers.

function thisMovie(movieName) {

  // IE and Netscape refer to the movie object differently.

  // This function returns the appropriate syntax depending on the browser.

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

    return window[movieName]

  } else {

   return window.document[movieName]

JSFCommunicator Methods:

JSFCommunicator.setVariable()

Usage

jsfc.setVariable(propName,propValue)

Parameters

propName A String specifying the name(flash 4 format) of variable in target flash movie.

propValue A Number, string, Boolean (any primitive) value for a variable in flash movie.

Returns

Nothing.

Description

Method; Sets the value of a flash variable specified by propName.

Example

The following code sets some variable in flash movie from javascript.

jsfc = new JSFCommunicator(refFlashObject);

//following lines sets value of variable on _root timeline.

jsfc.setVariable (“/:foo”,10);

/*following line of code sets value of variable in a movieclip on root timeline.

 /my_mc:foo is similar to _root.mymc.foo in ActionScript syntax.

*/

jsfc.setVariable (“/my_mc:foo”,10);

JSFCommunicator.getVariable()

Usage

jsfc.setVariable(propName)

Parameters

propName A String specifying the name(flash 4 format) of variable in target flash movie.

Returns

Variables value

Description

Method; Gets the value of a flash variable specified by propName.

Example

The following code sets some variable in flash movie from javascript.

jsfc = new JSFCommunicator(refFlashObject);

//following lines sets value of variable on _root timeline.

var foo = jsfc.getVariable (“/:foo”);

/*following line of code gets value of variable in a movieclip on root timeline.

 /my_mc:foo is similar to _root.mymc.foo in new ActionScript syntax.

*/

var foo = jsfc.setVariable (“/my_mc:foo”);

JSFCommunicator.callFunction()

Usage

jsfc.callFunction(fnLocation,fnName,fnArgs)

Parameters

fnLocation A String specifying the path of function in Flash Movie.

fnName A String specifying the name of function in flash, to be called.

fnArgs An Array, this is an array which contains the parameters to be passed to function being called.

Returns

Boolean; If true, function call was successful otherwise failed

Description

Method; Calls a function (fnName) at fnLocation in flash movie.

Example

//following line calls a flash function on root timeline

jsfc.callFunction (“_root”,”setInfo”, [“Rajiv”,22]);

Above code excutes a flash function on main timeline. Parameters are passed in an Array; parameters could be any type of primitive value (String, Number, Boolean).

JSFCommunicator.setMovie()

Usage

jsfc.setMovie(flashMovie)

Parameters

flashMovie A reference to Flash ActiveX or Plugin.

Returns

None

Description

Method; Set the target Flash Movie for JSFCommunicator.

Example

jsfc = new JSFCommunicator();

jsfc.setMovie(refFlashMovie)

jsfc.callFunction (“_root”,”setInfo”, [“Rajiv”,22]);

2) JSFCommunicatorHelper Component (Flash)

Description

The JSFCommunicatorHelper is a Flash MX Component. It helps the JavaScript JSFCommunicator class while communication and execution of function within the Flash Movie.

It needs to be present in the Flash Movie’s library only. Once imported in Flash movie, at runtime JSFCommunicatorHelper component would create an instance of it in global scope.
Instance can be accessed from anywhere in flash movie using JSFCHelperObject identifier and further can be used to call the JavaScript functions from anywhere in the flash movie.

Method summary for the JSFCommunicatorHelper class

Method	Description
`JSFCoomunicatorHelper.javascriptFunctionName()`	Call the javascript function.

There is no need to create any object of JSFCommunicatorHelper manually, as it is supposed to run as Singleton object. To avoid any problems caused by manual instance creation, component it self creates JSFCHelperObject while initialization. That’s why JSFCommunicatorHelper component should not be placed anywhere except library.

//following code would execute sayHello function in javascript.

JSFCHelperObject.sayHello(“Lara”);

Similarly, any javascript function can be executed.

JSFCHelperObject is actually working as proxy object here. That is, if you execute any function in JSFCHelperObject’s context it will resolve the corresponding the JavaScript function and execute it.

Please let me know (on [email protected]) for any bug/suggestion/doubts/queries.

COPYRIGHT & LICENSE

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the

documentation and/or other materials provided with the distribution.

- Neither the name of this software nor the names of its contributors

may be used to endorse or promote products derived from this software

without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.