• Overview
• New in this Version

• API Index
• Static Methods
• Static Properties
• Instance Methods
• Instance Properties

» Tutorials
• Compatibility
• Version History
• License
• Logic Flow chart

Extend the FlashSound API

FlashSound API extensions are JavaScript libraries that extend the core capability of the flashsound.js. Anyone familiar with object oriented JavaScript can create an extension to add new capabilities to the FlashSound API.

Coding Guidelines

1. Place copyright information at the top of the page. This statement should also include the extension version number and release date in long date format. You may also want to provide email contact information and links to licensing information.

/*
ActionScript Extension for FlashSound Javascript API
copyright 2001 Hayden Porter, name@domain.com
v 1.0.4 last update February 17, 2003
Available under the open source Artistic License
http://www.flashsoundapi.com
*/

2. Insert your custom JavaScript methods and properties. If you are calling native Flash JavaScript API methods it is a good idea to use the following code to check that the player is ready for script control.

// Check for player readiness
if(!this.isPlayerReady()) {return;}

Example of a custom method based upon native Flash JavaScript API:

function Flash_GetVariable(variablePath){
  if(!this.isPlayerReady()) {return;}
  window.document[this.playerID].GetVariable(variablePath);
}

The flashsound.js has three naming conventions. All API function names start with "fs_". Any Function which duplicates a native flash ActionScript statement adds "api_" to the "fs_" convention. Finally, any function which has a target argument should start with a capital T.

fs _functionName(arguments) - any custom API method.
fs_api_functionName(arguments) - API methods that duplicate actionscript statements.
fs_TfunctionName(arguments) - API methods that have a target argument.

3. After adding custom code, use the prototype property to extend the FlashSound( ) class. The prototype is based upon the following syntax.

FlashSound.prototype.mynewmethod = fs_functionname;
FlashSound.prototype.mynewproperty = somevalue;

Example of adding a custom method to the FlashSound( ) JavaScript class.

FlashSound.prototype.GetVariable = fs_GetVariable;

The prototype property extends the FlashSound( ) class so that all new instances of the class inherit these methods and properties. To create static methods or properties, append them to the FlashSound object directly, rather than using the prototype property.

Example of creating static property or method:

FlashSound.mynewstaticmethod = fs_functionname;
FlashSound.mynewstaticproperty = somevalue;

4. To prevent errors in Netscape 3.x, which does not properly support the prototype property, you need to create a dummy instance before using the prototype property.

Example of creating a dummy instance:

// prevent errors on Netscape 3
if(FlashSound.oldNN){x=new FlashSound(); x=null;}

Full example:
/*
ActionScript Extension for FlashSound Javascript API
copyright 2001 Hayden Porter, hayden@aviarts.com
available under open source Artistic License
www.flashsoundapi.com/documentation/license.html
v 1.0.4 last update February 23, 2003
*/

// prevent errors on Netscape 3
if(FlashSound.oldNN){x=new FlashSound(); x=null;}

// define custom functions
function fs_GetVariable(variablePath){
  if(!this.isPlayerReady()) {return;}
  window.document[this.playerID].GetVariable(variablePath);
}

... other functions

// extend the FlashSound class
FlashSound.prototype.GetVariable = fs_GetVariable;

... other prototype statements.

Documentation
Documentation should accurately describe the extended functionality of the extension. It should also provide instructions on how to add the extension to a web site sonified with the FlashSound API. (Note that extensions should be sourced in after the flashsound.js and not before) Ideally you should also provide code examples and swf examples where appropriate.

At the top of the documentation main page should be the following information:

Compatibility Issues
If your code is JavaScript 1.2 compliant or higher, be sure to provide instructions for developers to add JavaScript version to the script tag. Be sure to test that your code fails without error on non compatible browsers.

If your code is only compatible with certain player version or versions greater than Flash 4, use the FlashSound.playerVersion static property or the FlashSound.setMinPlayer( ) static method to configure the flashsound.js to engage under these circumstances only.